For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

  • 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.

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

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: 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

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[].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

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

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

  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). 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)

  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)

  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).

    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

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:

  1. 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.

  2. 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.

  3. 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_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

Last updated