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+jsonHTTP method:
POSTfor card creationGET /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_dataobject 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_typetoken_typewallet_details.payment_data_typewallet_details.device_manufacturer_identifierwallet_details.transaction_idwallet_details.cryptogramfor DPANwallet_details.merchant_token_identifierfor 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: https://sandbox.vgsapi.com
Header required:
Content-Type: application/vnd.api+jsonSend 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.
Expected DPAN Mock Response
A successful mock DPAN request returns a card with:
token_type: dpanwallet_type: apple_paypayment_data_type: 3DSecuredevice_manufacturer_identifiercryptogramtransaction_idpayment_methoddetails if provided in the request
Example response
Mock Testing – MPAN
Use the following encrypted Apple Pay payload to simulate decryption of an MPAN token.
Expected MPAN Mock Response
A successful mock MPAN request returns a card with:
token_type: mpanwallet_type: apple_paypayment_data_type: MerchantTokendevice_manufacturer_identifiermerchant_token_identifiertransaction_idpayment_methoddetails if provided in the request
Example response
Mock Testing – 5xx Error
Use the following encrypted Apple Pay payload to simulate a 5xx error response.
Expected Error Mock Response
A failed mock request returns an error response with:
errors[].detailerrors[].error_codemeta.observability.trace_idmeta.observability.client_idmeta.observability.vault_idmeta.observability.account_idmeta.observability.fingerprint
Example response
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:
CRDifkUMiwjdcZTA6USirUsC7xoN617mWi7avaehqkYhMPAN1JPDPAN:
CRDifkUMiwjdcZTA6USirUsC7xoN617mWi7avaehqkYhDPAN1JP
Important GET Behavior
Wallet transaction artifacts are not persisted and therefore are not included in GET responses. These artifacts include:
currency_codeamountcryptogram
For DPAN cards, the GET response will still include persisted wallet details such as:
device_manufacturer_identifierpayment_data_typepayment_methoddetails if provided in the request
For MPAN cards, the GET response will still include persisted wallet details such as:
device_manufacturer_identifierpayment_data_typemerchant_token_identifierpayment_methoddetails if provided in the request
Example GET Response – DPAN
Example GET Response – MPAN
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. 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).
Steps
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). 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.
Create a Sandbox Apple Account In App Store Connect, create a sandbox tester account to use for Apple Pay sandbox transactions. (Apple Developer)
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)
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).
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.
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: dpanwallet_type: apple_paywallet_details.payment_data_type: 3DSecurewallet_details.device_manufacturer_identifierwallet_details.transaction_idwallet_details.cryptogramwallet_details.payment_methodif it was provided in the request
MPAN Validation
Confirm that the response includes:
token_type: mpanwallet_type: apple_paywallet_details.payment_data_type: MerchantTokenwallet_details.device_manufacturer_identifierwallet_details.transaction_idwallet_details.merchant_token_identifierwallet_details.payment_methodif 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_codeis not returnedamountis not returnedcryptogramis not returned
Troubleshooting: "You don't have enough permissions to the requested resource"
If you receive the error: You don't have enough permissions to the requested resource when generating a certificate or CSR using the VGS CLI, verify the following:
User Permissions
The user account used to log in to the VGS CLI must have Admin access to the target vault.
Users with only Read or Write permissions may receive this error when attempting to generate certificates or CSRs.
Command Formatting
Incorrect spacing or formatting in multi-line CLI commands can sometimes result in this error.
If you encounter issues, try running the command as a single-line command instead.
Vault ID Validation
Ensure the Vault ID specified in the command is correct.
Using an incorrect Vault ID can also result in the same permissions error, even if the user has the required access to other vaults.
If the issue persists after validating the above items, please contact VGS Support and include the command used, the Vault ID, and the user account details for further investigation.
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_idis generated for each successful requestpayment_methodis returned in the response only if it is provided in the requestWallet transaction artifacts are not persisted and therefore are not included in GET responses
Last updated

