# Wallet Decrypt ## **Apple Pay Wallet Decryption Testing Guide** This guide explains how to test **Apple Pay Wallet Decryption** in a controlled environment. You can test both **DPAN** and **MPAN** wallet decryption flows and validate the resulting **Create Card** and **Get Card by ID** behavior. Testing can be performed in two ways: * **Mock Testing** – using static encrypted Apple Pay payloads that return predictable decrypted DPAN or MPAN card data * **Sandbox Testing** – using encrypted Apple Pay payloads in the sandbox environment with Apple Pay Wallet Decryption enabled on the account ## **General Setup** * **Content-Type header:** `application/vnd.api+json` * **HTTP method:** `POST` for card creation * **GET /cards/{id}** can be used after card creation to retrieve the stored card * Apple Pay Wallet Decryption supports encrypted Apple Pay payloads using the **EC\_v1** format * The encrypted payload is sent in the `encrypted_payment_data` object of the **Create Card API** request Each successful request creates a new CMP card and returns a new `card_id`. ## **What Apple Pay Wallet Decryption Does** When an encrypted Apple Pay payload is submitted to CMP: * CMP performs **wallet decryption** * CMP extracts the **DPAN** or **MPAN** * CMP creates and stores the card in CMP * CMP returns the created card object, including wallet metadata For successful responses, the wallet metadata may include: * `wallet_type` * `token_type` * `wallet_details.payment_data_type` * `wallet_details.device_manufacturer_identifier` * `wallet_details.transaction_id` * `wallet_details.cryptogram` for DPAN * `wallet_details.merchant_token_identifier` for MPAN ## **Mock Testing** Use Mock Testing to verify Apple Pay Wallet Decryption behavior without requiring Apple Pay Wallet Decryption to be enabled on the CMP account. ### Mock Testing Requirements When using mock testing: * A **CMP account** is required * A **JWT auth token** is required * **Apple Pay Wallet Decryption account configuration is not required to be enabled** * A **new card ID** is generated for each successful request * The decrypted card content returned by the mock remains otherwise static for the same test payload ### Request Requirements * **Base URL:** * **Header required:** `Content-Type: application/vnd.api+json` * Send the encrypted Apple Pay payload using the standard **Create Card API** shape ### Mock Testing – DPAN Use the following encrypted Apple Pay payload to simulate decryption of a **DPAN** token. ```json { "data": { "attributes": { "encrypted_payment_data": { "digital_signature": "TUlBR0NTcUdTSWIzRFFFSEFxQ0FNSUFDQVFFeERUQUxCZ2xnaGtnQlpRTUVBZ0V3Z0FZSktvWklodmNOQVFjQkFBQ2c=", "encrypted_payload_text": "OzF2HRdPNYZPixxpyZ3GzTxm/qXSLP65bZ+yM8I0XFjuB72B+dtRPZKjNwNV13Yy2TD+6LInN8LzvZXk9Q0WW+gms+tacfDKsdIR1vidJhsKSZF9yZ5BwyKN3Nv0J7RQsGi8hjILxVBNxnA5vdTHCMOGcy/9cwBDLyU1boTRrxd8gBbu4UWzdDy+8KhCxMpADBbTF0J9DEaa6Iz/uCLlQgv26xxvBSSdDcn1ZhsaHJN+YJlnkcyckPj1zf2F+2EfqOdEvxAWQNAGd2d5zi+tl3LVwVes1xorl7M8qC+LFqo9MNCefhmSsLT8P3RTEkrn2SoZ5qEv0uBXapQWJMnLlkBCpZF0fkTKEzC67i7wiz4qnDaBogaiY/qsaccgJ5xHk2Il2Wgt6Y2+gdk9wBqaRu0kKgEThth6mU/NCOYKoIPzJm6KWa0o3gJ9bhq/SJaVlsVrov81Ps7i03/sHmq/Sve/5uRJys0d0BUHzDrasQH35973JMpxaZ0TdiwHnHU5VWNbV2FKxh6k9e0YqmMZ//DX36h5EOa7iSinfRGQdF6IQ/8e7nazYwtX0iV8IQ4n8P/cwIn9Gn5xmeTSdfOEO1o=", "key_hash": "DPAN/4VEn0bzlhTscArIT3Gvbq2MKiZlHAlZc76kAUx=", "public_key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE0eamXz+Xza8La9eOAIYf307qxJOVRRf9oTLlm61o0dLPvpXtPiEno2QzvzX/ucbugivotW2+gi5x/Ff8c7adfg==", "version": "EC_v1", "wallet_type": "apple_pay", "wallet_transaction_id": "6e21f9bf4aea3f767c5e48eeae92d8af9b8919c3ad9854fd1320b7867499c6fe", "payment_method": { "display_name": "Visa 0121", "network": "Visa", "type": "credit" } } } } } ``` ### Expected DPAN Mock Response A successful mock DPAN request returns a card with: * `token_type: dpan` * `wallet_type: apple_pay` * `payment_data_type: 3DSecure` * `device_manufacturer_identifier` * `cryptogram` * `transaction_id` * `payment_method` details if provided in the request #### Example response ```json { "data": { "id": "CRDKfukrUmMsUdotydKS4euZ1v2exoN617mWi7avaehqkYh2J5JP", "type": "cards", "attributes": { "pan": "5100260000019206", "exp_month": 12, "exp_year": 99, "cardholder": { "name": "John Q. Public", "company": "VGS", "phone": "+18881112222", "address": { "address1": "301 Test Loop", "city": "San Francisco", "region": "California", "postal_code": "11111", "country": "US" } }, "token_type": "dpan", "wallet_type": "apple_pay", "pan_alias": "tok_sandbox_QfJDZdyBR6pygJ13xPXrkB", "bin": "510026", "first8": "51002600", "last4": "9206", "card_fingerprint": "fjLdCHgcSJmnSqzpSQafJvmuPep5vSdV5w2nJC1sWuFp", "created_at": "2025-08-01T00:00:00", "updated_at": "2025-08-01T00:00:00", "wallet_details": { "currency_code": "USD", "amount": 2500, "device_manufacturer_identifier": "040010030273", "payment_data_type": "3DSecure", "cryptogram": { "type": "TAVV", "value": "Ab2c/XwBBB/EknV76pyc2NBBCCC=", "eci": "7" }, "payment_method": { "display_name": "Visa 0121", "network": "Visa", "type": "credit" }, "transaction_id": "9a0650018c263c03fb34618407fb00a3026aee366b230e013605a12e5201574b" } } }, "metadata": { "observability": { "trace_id": "c2a171cff919032f17515338db2527fe", "client_id": "ACwmzJCti-3DS_Account-dFbIj", "vault_id": "tntfn3pqdcf", "account_id": "ACT3Wjs6gwrcHxzjcro4H9G8W", "fingerprint": "4GqVMtYY8uohfuZ5zhrAZfs5VexAbihfrL8qyTfudEBpEgWiXCPuEAJtC91" } } } ``` ### Mock Testing – MPAN Use the following encrypted Apple Pay payload to simulate decryption of an **MPAN** token. ```json { "data": { "attributes": { "encrypted_payment_data": { "digital_signature": "TUlBR0NTcUdTSWIzRFFFSEFxQ0FNSUFDQVFFeERUQUxCZ2xnaGtnQlpRTUVBZ0V3Z0FZSktvWklodmNOQVFjQkFBQ2c=", "encrypted_payload_text": "JFk4RJoiod18IQmwcjtU88ZimrS543kxzoXw2vQjTl08ud6MV9kzf6NiSJ1Ev7HZ8IcrtzUXb69sbO/W/PcV13h+WRtYvmD7GTCSypimqcitvE78zCDRUpV6g2zsapFm2/R3jFcdDlmvP4L5/mkKU/pWx0hA/MiUe7XoGc+2jEUI7tAB8XZebV7lPlSFLBA2Q46JKsmsigkvmY3wfuYKJDg/niD6yL4LgIA0KAnh8YjU/88UjLbvi6mkII7MjJri6RiTqQ3EDGBZX84SlPus1NYVe1yMwqjG8e7Pza8kDZ6C4Wyz/5SksMpEnUxanWAfKnc37nJGkn9KiCktLwXGRLT7hEHszsvs/yu6ZUY3E8SJ9LYb2fAn3IXqJEyDXWZgRdF1tVrW0hqYrWRvUfcJ7gqRCL8/0k9nRGHhw4+r4hiVOz2hadd4T5cxjfWsfCSg4UEFv2rCZ8K7qkS1XQsZmbuqjDNnzS+vPd/Hk7xDJ+cSiySD/KcE8g==", "key_hash": "MPAN/3FruspO6vAy8AQ3UKiJeF14wgTUYmGAPwlbiqk=", "public_key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE0mrNoedmyYa/Qfp+1GlUIa8x0Fu1tgTattp0678fEUTPEcVfqsizY/8LP/4T34wNGbvLPV8zTEICHaoFWxpeig==", "version": "EC_v1", "wallet_type": "apple_pay", "wallet_transaction_id": "9f0f709cc538c7207169cf9f44e668b8e3cadf73c2d84b0c1b1e2b6caf7f07a1", "payment_method": { "display_name": "Visa 0121", "network": "Visa", "type": "credit" } } } } } ``` ### Expected MPAN Mock Response A successful mock MPAN request returns a card with: * `token_type: mpan` * `wallet_type: apple_pay` * `payment_data_type: MerchantToken` * `device_manufacturer_identifier` * `merchant_token_identifier` * `transaction_id` * `payment_method` details if provided in the request #### Example response ```json { "data": { "id": "CRDqL55P51GVUMbZMDgYakHQTJSoFP2e8NoMXzhQpVPgLh91ZEQo", "type": "cards", "attributes": { "pan": "5100260000009207", "exp_month": 12, "exp_year": 99, "cardholder": { "name": "John Q. Public", "company": "VGS", "phone": "+18881112222", "address": { "address1": "301 Test Loop", "city": "San Francisco", "region": "California", "postal_code": "11111", "country": "US" } }, "token_type": "mpan", "wallet_type": "apple_pay", "pan_alias": "tok_sandbox_oO3YeAP3eDJhPclNtEPcJI", "bin": "510026", "first8": "51002600", "last4": "9207", "card_fingerprint": "2kPZBjQpaX6PnxrbvPTYzAC2ckcVNqNTxCAkdAn3tnTn", "created_at": "2025-08-01T00:00:00", "updated_at": "2025-08-01T00:00:00", "wallet_details": { "currency_code": "USD", "amount": 2500, "device_manufacturer_identifier": "040010030273", "payment_data_type": "MerchantToken", "merchant_token_identifier": "DNITHE302308980001844", "payment_method": { "display_name": "Visa 0121", "network": "Visa", "type": "credit" }, "transaction_id": "9a0650018c263c03fb34618407fb00a3026aee366b230e013605a12e5201574b" } } }, "metadata": { "observability": { "trace_id": "250631059828f5a07e92f202fde52fa6", "client_id": "ACwmzJCti-3DS_Account-dFbIj", "vault_id": "tntfn3pqdcf", "account_id": "ACT3Wjs6gwrcHxzjcro4H9G8W", "fingerprint": "4GqVMtYY8uohfuZ5zhrB2MNc1fKeqyK8VaZ7AqS8oBtqrehfoHhAFsztc3Q" } } } ``` ### Mock Testing – 5xx Error Use the following encrypted Apple Pay payload to simulate a 5xx error response. ```json { "data": { "attributes": { "encrypted_payment_data": { "digital_signature": "TUlBR0NTcUdTSWIzRFFFSEFxQ0FNSUFDQVFFeERUQUxCZ2xnaGtnQlpRTUVBZ0V3Z0FZSktvWklodmNOQVFjQkFBQ2c=", "encrypted_payload_text": "OzF2HRdPNYZPixxpyZ3GzTxm/qXSLP65bZ+yM8I0XFjuB72B+dtRPZKjNwNV13Yy2TD+6LInN8LzvZXk9Q0WW+gms+tacfDKsdIR1vidJhsKSZF9yZ5BwyKN3Nv0J7RQsGi8hjILxVBNxnA5vdTHCMOGcy/9cwBDLyU1boTRrxd8gBbu4UWzdDy+8KhCxMpADBbTF0J9DEaa6Iz/uCLlQgv26xxvBSSdDcn1ZhsaHJN+YJlnkcyckPj1zf2F+2EfqOdEvxAWQNAGd2d5zi+tl3LVwVes1xorl7M8qC+LFqo9MNCefhmSsLT8P3RTEkrn2SoZ5qEv0uBXapQWJMnLlkBCpZF0fkTKEzC67i7wiz4qnDaBogaiY/qsaccgJ5xHk2Il2Wgt6Y2+gdk9wBqaRu0kKgEThth6mU/NCOYKoIPzJm6KWa0o3gJ9bhq/SJaVlsVrov81Ps7i03/sHmq/Sve/5uRJys0d0BUHzDrasQH35973JMpxaZ0TdiwHnHU5VWNbV2FKxh6k9e0YqmMZ//DX36h5EOa7iSinfRGQdF6IQ/8e7nazYwtX0iV8IQ4n8P/cwIn9Gn5xmeTSdfOEO1o=", "key_hash": "DPAN/RGVjcnlwdGlvbkVycm9yVGVzdEtleUZvck1vY2=", "public_key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE0eamXz+Xza8La9eOAIYf307qxJOVRRf9oTLlm61o0dLPvpXtPiEno2QzvzX/ucbugivotW2+gi5x/Ff8c7adfg==", "version": "EC_v1", "wallet_type": "apple_pay", "wallet_transaction_id": "6e21f9bf4aea3f767c5e48eeae92d8af9b8919c3ad9854fd1320b7867499c6fe", "payment_method": { "display_name": "Visa 0121", "network": "Visa", "type": "credit" } } } } } ``` ### Expected Error Mock Response A failed mock request returns an error response with: * `errors[].detail` * `errors[].error_code` * `meta.observability.trace_id` * `meta.observability.client_id` * `meta.observability.vault_id` * `meta.observability.account_id` * `meta.observability.fingerprint` #### Example response ```json { "errors": [ { "detail": "Decryption failed due to an internal error", "error_code": "INTERNAL" } ], "meta": { "observability": { "trace_id": "ff058f978b58bee834ba2b806a8b0aed", "client_id": "ACsPTgxhw-AutoTest5-vP8pD", "vault_id": "tntefvvq6tt", "account_id": "ACTgSbmT2R7a6pjgi4cCrTkoj", "fingerprint": "4GqVMtYY8uohfBxjwFF4PF4ANEYCgGFMrpWzHmgU5zvHBsjXdR78yrY3YJC" } } } ``` ### Get Card by ID After Mock Creation You can call **GET /cards/{id}** using the `card_id` returned from either the DPAN or MPAN mock response. This allows you to verify what wallet metadata is persisted after card creation. **Static mock CardIDs** The following static CardIDs can be used with the **Get Card by ID** request for mock test payloads: * **MPAN:** `CRDifkUMiwjdcZTA6USirUsC7xoN617mWi7avaehqkYhMPAN1JP` * **DPAN:** `CRDifkUMiwjdcZTA6USirUsC7xoN617mWi7avaehqkYhDPAN1JP` ### Important GET Behavior Wallet transaction artifacts are not persisted and therefore are not included in GET responses. These artifacts include: * `currency_code` * `amount` * `cryptogram` For DPAN cards, the GET response will still include persisted wallet details such as: * `device_manufacturer_identifier` * `payment_data_type` * `payment_method` details if provided in the request For MPAN cards, the GET response will still include persisted wallet details such as: * `device_manufacturer_identifier` * `payment_data_type` * `merchant_token_identifier` * `payment_method` details if provided in the request #### Example GET Response – DPAN ```json { "data": { "id": "CRDoEYk47qUtndEHR9w8kGKra", "type": "cards", "attributes": { "pan": "4111111111111444", "cvc_status": "not-set", "exp_month": 8, "exp_year": 28, "cardholder": {}, "token_type": "dpan", "wallet_type": "apple_pay", "pan_alias": "tok_sandbox_kAYsfM1wyRwbJEesrnqFFi", "bin": "411111", "first8": "41111111", "last4": "1444", "card_fingerprint": "Qg3rYRJd4gjHYefhxpwfS2XkUovBwF2uVNhUPXgCj2H", "created_at": "2026-03-11T01:47:32.601715", "updated_at": "2026-03-11T01:47:32.601716", "wallet_details": { "device_manufacturer_identifier": "040010030400", "payment_data_type": "3DSecure", "payment_method": { "display_name": "Visa 0121", "network": "Visa", "type": "credit" } } } }, "metadata": { "observability": { "trace_id": "707a927ca06a9db1d6ac0cc6705cdf11", "client_id": "AChkBQQGH-3DS-scope-61fC0", "vault_id": "tntiugemxfd", "account_id": "ACT9eeBkBsxXe9wWJkQdpG2kC", "fingerprint": "4GqVMtYY8uohftF2NdrQjH4TApUbjScwsB5oXACgvq8ATZkzALLtZSGYwo5" } } } ``` #### Example GET Response – MPAN ```json { "data": { "id": "CRDm3dzAeDCnfkwfqTEufFtz6", "type": "cards", "attributes": { "pan": "4111111111111222", "cvc_status": "not-set", "exp_month": 11, "exp_year": 27, "cardholder": {}, "token_type": "mpan", "wallet_type": "apple_pay", "pan_alias": "tok_sandbox_kQy6qwjCP2NGGExD81dRpa", "bin": "411111", "first8": "41111111", "last4": "1222", "card_fingerprint": "b3p67ZCV6FcVnx9WtyKH2EQtfeax7yyq9cdvSm7k7rRX", "created_at": "2026-03-11T01:52:11.803918", "updated_at": "2026-03-11T01:52:11.803919", "wallet_details": { "device_manufacturer_identifier": "040010030299", "payment_data_type": "MerchantToken", "merchant_token_identifier": "DNITHE302308980001846", "payment_method": { "display_name": "Visa 0121", "network": "Visa", "type": "credit" } } } }, "metadata": { "observability": { "trace_id": "d88aa1542357f9ae5be8b3f53df79762", "client_id": "AChkBQQGH-3DS-scope-61fC0", "vault_id": "tntiugemxfd", "account_id": "ACT9eeBkBsxXe9wWJkQdpG2kC", "fingerprint": "4GqVMtYY8uohftF2NdrQjFSG6JsmX1gTaVFegV9uF4zsdjEdKCP7CUyc1tA" } } } ``` ## Sandbox Testing ### Test Apple Pay decryption in sandbox Before running sandbox tests, make sure Apple Pay Wallet Decryption is enabled for your CMP account and that your Apple Pay setup is complete, including the required certificate configuration and upload of the signed certificates in VGS. For setup instructions, see [Setting Up Your Apple Certificates](https://docs.verygoodsecurity.com/cmp/payment-credentials/apple-pay#setting-up-your-apple-certificates). VGS uses the configured Apple Pay payment processing certificate to decrypt Apple Pay payment tokens. Before testing, make sure your Apple Pay setup includes all required Apple-side prerequisites. This includes: * an Apple Developer account with Apple Pay enabled * a Merchant Identifier created in Apple Developer * a Payment Processing Certificate generated for that Merchant Identifier and uploaded to VGS * if testing Apple Pay on the web, a Merchant Identity Certificate generated and configured on your side for merchant validation * if testing Apple Pay on the web, a verified domain registered with Apple so the Apple Pay button and merchant validation flow can work correctly For **Apple Pay on the web**, your integration must also be fully configured to support merchant validation and domain verification. For **app-based integrations**, make sure your Apple Pay entitlement and sandbox test setup are complete. **The Payment Processing Certificate is required for VGS to decrypt the Apple Pay token.** The Merchant Identity Certificate is not used by VGS for decryption itself, but it is still required for Apple Pay on the web because Apple uses it during merchant validation. To test Apple Pay decryption, generate an encrypted Apple Pay payload by completing a **real Apple Pay test transaction** in Apple’s sandbox environment. Apple Pay returns the encrypted payment token as part of the payment authorization response, and that token can be sent to VGS for decryption testing. Apple’s sandbox supports testing Apple Pay transactions with sandbox accounts and test cards. ([Apple Developer](https://developer.apple.com/apple-pay/sandbox-testing)). #### Steps 1. **Set up Apple Pay for your app or website**\ Make sure your Apple Pay integration is configured in your Apple Developer account. Apple’s implementation guide is here. ([Apple Developer](https://developer.apple.com/apple-pay/implementation)). This setup should include the Merchant Identifier you plan to use for testing. If you are testing Apple Pay on the web, your domain must also be registered and verified with Apple, and your merchant validation flow must be configured using your Merchant Identity Certificate. 2. **Create a Sandbox Apple Account**\ In App Store Connect, create a sandbox tester account to use for Apple Pay sandbox transactions. ([Apple Developer](https://developer.apple.com/help/app-store-connect/test-in-app-purchases/create-a-sandbox-apple-account)) 3. **Add a sandbox test card to Wallet**\ Sign in to your test device with the sandbox account and add one of Apple’s sandbox test cards to Wallet. Apple’s sandbox testing guide covers this setup. ([Apple Developer](https://developer.apple.com/apple-pay/sandbox-testing/)) 4. **Run a test Apple Pay checkout**\ Start an Apple Pay payment from your app or Safari website on a supported Apple device and complete the authorization using the sandbox card. Apple Pay will return an encrypted payment token in the authorization response. ([Apple Developer](https://developer.apple.com/apple-pay/sandbox-testing/)). 1. For Apple Pay on the web, this step assumes your verified domain, Apple Pay button setup, and merchant validation flow are already working. Without that setup, you may not be able to generate the encrypted Apple Pay payload needed for VGS decryption testing. 5. **Send the encrypted payload to VGS**\ Use the encrypted Apple Pay token returned by Apple Pay as the Create Card API payload for VGS decryption testing. VGS will use the Payment Processing Certificate configured for the associated Merchant Identifier to decrypt the payload. Apple Pay sandbox requires a real card in Apple Wallet. #### Important Sandbox Testing Notes * Apple Pay sandbox testing requires a **sandbox tester account** and an **Apple Pay sandbox test card** added to Wallet. * For **web integrations**, Apple Pay sandbox testing also requires successful **domain verification** and **merchant validation**. * This guide focuses on testing VGS decryption with a real Apple Pay sandbox token. **Customers building the full Apple Pay flow from scratch will also need to complete the surrounding Apple Pay integration, including:** * merchant validation for web integrations * domain verification for Apple Pay on the web * Apple Pay session setup in the app or website * extraction of the encrypted Apple Pay token from the payment authorization response * mapping the Apple Pay token fields into the VGS Create Card request * any required hosted test environment needed for Apple Pay validation flows * **This guide assumes your Apple Pay integration is already set up and functioning in Apple’s sandbox environment.** ## What to Validate During Testing For both Mock testing, validate the following: ### DPAN Validation Confirm that the response includes: * `token_type: dpan` * `wallet_type: apple_pay` * `wallet_details.payment_data_type: 3DSecure` * `wallet_details.device_manufacturer_identifier` * `wallet_details.transaction_id` * `wallet_details.cryptogram` * `wallet_details.payment_method` if it was provided in the request ### MPAN Validation Confirm that the response includes: * `token_type: mpan` * `wallet_type: apple_pay` * `wallet_details.payment_data_type: MerchantToken` * `wallet_details.device_manufacturer_identifier` * `wallet_details.transaction_id` * `wallet_details.merchant_token_identifier` * `wallet_details.payment_method` if it was provided in the request ### GET Validation After card creation, call **GET /cards/{id}** and confirm that: * the card is retrievable * persisted wallet metadata is returned * `currency_code` is not returned * `amount` is not returned * `cryptogram` is not returned ## Important Notes * Apple Pay Wallet Decryption mock testing does **not** require Wallet Decryption to be enabled on the account * Apple Pay Wallet Decryption sandbox testing **does** require Wallet Decryption to be enabled on the account * A new `card_id` is generated for each successful request * `payment_method` is returned in the response only if it is provided in the request * Wallet transaction artifacts are not persisted and therefore are not included in GET responses --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.verygoodsecurity.com/cmp/developer-resources/guides/testing/wallet-decrypt.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.