Create Card - Apple Pay Wallet Decryption

Overview

CMP supports Apple Pay Wallet Decryption, allowing merchants to submit an encrypted Apple Pay payment token directly to CMP during card creation. CMP decrypts the token using an Apple-compliant key, extracts the DPAN or MPAN, creates and securely stores the card, and returns the created card object in the API response.

This feature is designed for merchants who have already obtained the encrypted Apple Pay payment token from the customer’s device and want CMP to handle decryption and card creation. The encrypted wallet token must be generated through the standard Apple Pay flow before calling the Create Card API. If you need guidance on generating encrypted Apple Pay tokens for testing, see the Wallet Decrypt Testing Guide here.

The pan field in the response contains the decrypted DPAN or MPAN, not the original FPAN. Tokenization behavior remains consistent with CMP: PCI-scoped clients receive both PAN and PAN alias, while non-PCI clients receive only the PAN alias. The presence of PAN in the response does not mean tokenization is bypassed.

Benefits

• No need to build or maintain Apple Pay decryption services

• Reduced PCI scope

• Standardized handling of wallet metadata

• Continued access to CMP vaulting and card fingerprinting

Apple Pay wallet decryption flow

After the merchant session is established and the customer authorizes the payment, the encrypted Apple Pay token can be submitted to CMP for decryption and card creation.

Flow overview

• The customer selects Apple Pay during checkout.

• The merchant frontend creates and begins the Apple Pay session.

• The merchant backend completes Apple merchant validation and returns the merchant session object to the frontend.

• The customer authorizes the payment in the Apple Pay sheet.

• Apple returns encrypted payment data to the merchant frontend.

• The merchant backend submits the encrypted Apple Pay token to CMP using the Create Card API.

• CMP decrypts the token using the configured Apple Pay payment processing certificate.

• CMP extracts the wallet token and related card metadata.

• CMP creates and stores the card.

• CMP returns the created card object and associated wallet metadata.

Apple Pay wallet decryption sequence

Setting Up Your Apple Certificates

To use Apple Pay Wallet Decryption with CMP, you need to configure the Apple Pay certificates required for your integration.

For DPAN decryption with CMP, you only need to configure the following with VGS:

• Merchant Identifier

• Payment Processing Certificate

A Merchant Identity Certificate is not required by VGS for DPAN decryption. If your integration requires merchant validation, such as Apple Pay on the web, you may generate and manage your own Merchant Identity Certificate separately.

Before generating certificates or uploading Apple-signed certificates to VGS, make sure the VGS CLI is installed and authenticated.

Getting Your Vault ID

To generate and upload certificates, you need your VGS Vault ID. Work with your VGS customer representative to obtain your Vault ID.

Users must have Admin access to the target vault to generate and upload certificates using the VGS CLI.

VGS CLI Setup

source .venv-pypi/bin/activate
pip install vgs-cli
vgs login

Ensure you can log in successfully using vgs login and confirm that the “Success!” message appears in your terminal before proceeding with the certificate generation steps below.

Create a Merchant Identifier

Create a Merchant Identifier in your Apple Developer account for the Apple Pay integration you plan to use with CMP. The Merchant Identifier represents your Apple Pay merchant configuration and is required when creating Apple Pay certificates.

Apple requires the Merchant Identifier to follow reverse domain notation, for example merchant.com.yourcompany.appname. Identifiers that do not follow this format may be rejected by the Apple Developer portal.

Use the Merchant Identifier that corresponds to the integration you intend to test or use in production. You will reference this identifier when creating both the Payment Processing Certificate and, if needed, the Merchant Identity Certificate.

Create a Merchant Identity Certificate

If your integration requires merchant validation, such as Apple Pay on the web, you may generate and use your own Merchant Identity Certificate directly with Apple.

This certificate is not required by VGS for DPAN decryption, and does not need to be generated or uploaded through the VGS certificate flow described below.

Step 1: Generate a CSR and Private Key

Run the following OpenSSL command:

openssl req -new -newkey rsa:2048 -nodes \
  -keyout merchant_id.key \
  -out MyCSR.certSigningRequest \
  -subj "/C=<country_code>/ST=<state>/L=<city>/O=<your_organization_name>/OU=<unit>/CN=<your_merchant_identifier>"

Replace the placeholders:

• <country_code> — Two-letter country code (e.g., US)

• <state> — State or province (e.g., California)

• <city> — City name (e.g., San Francisco)

• <your_organization_name> — Your company or organization name

• <unit> — Organizational unit (e.g., Payments)

• <your_merchant_identifier> — Your Apple merchant identifier (e.g., merchant.com.example.store)

This generates two files:

• merchant_id.key — Your private key (keep this secure)

• MyCSR.certSigningRequest — The CSR to upload to Apple

Step 2: Get the Identity Certificate from Apple

1. Sign in to your Apple Developer Account

2. Navigate to Certificates, Identifiers & Profiles

3. Select Apple Pay Merchant Identity Certificate

4. Click Create Certificate

5. Select your Merchant ID

6. Upload MyCSR.certSigningRequest

7. Download the resulting merchant_id.cer file

Step 3: Convert to PEM Format

Move merchant_id.cer into the same folder where merchant_id.key was generated and convert the downloaded certificate to PEM format:

openssl x509 -inform der -in merchant_id.cer -out merchant_id.pem

You now have the two files needed for Apple Pay merchant validation in the same folder:

• merchant_id.key — Private key

• merchant_id.pem — Certificate in PEM format

Create a Payment Processing Certificate

The Payment Processing Certificate is required for Apple Pay token decryption. CMP uses this certificate to decrypt the encrypted Apple Pay payment token submitted through the Create Card API.

To set this up, generate a certificate signing request (CSR) using an ECC (Elliptic Curve Cryptography) key. CMP supports EC_v1 tokens only, which requires an ECC-based CSR. VGS does not support RSA-based certificates. Apple’s portal may accept an RSA-based CSR without error, but the resulting certificate cannot be used with CMP and decryption will fail at runtime.

Step 1: Generate the CSR

Use the VGS CLI to generate the CSR for the Apple Pay Payment Processing Certificate:

vgs certificate generate-csr -V <VAULT_ID> --type apple-pay-payment-processing --name merchant.com.example -o payment_processing.csr

Replace:

• <VAULT_ID> with your VGS vault ID

• merchant.com.example with your Apple Merchant Identifier

Step 2: Upload the CSR to Apple

Upload the generated .csr file to the Apple Developer portal when creating your Apple Pay Payment Processing Certificate.

The generated CSR is uploaded to Apple, not to VGS. There is no separate command to upload the CSR back into VGS.

Step 3: Upload the Apple-signed certificate to VGS

After Apple signs the certificate and provides the .cer file, upload the Apple-signed certificate back to VGS.

Using certificate ID:

vgs certificate upload \
  -V <VAULT_ID> \
  --cert-id <CERT_ID> \
  -f apple_signed_cert.cer

Once this certificate is uploaded to VGS, it can be used to decrypt Apple Pay payment payloads sent through the Create Card API. CMP identifies the correct certificate using the key_hash value included in the encrypted request payload.

Create the Apple Pay Merchant Session

Before the encrypted Apple Pay token can be submitted to CMP, the merchant must initialize and validate an Apple Pay session in the browser.

A typical merchant session flow is:

• Register and verify your web domain with Apple: The domain association file must be hosted on each domain that will use Apple Pay, and each domain or subdomain must be registered and verified separately with Apple.

• The customer clicks the Apple Pay button.

• Create an ApplePaySession in the frontend using an ApplePayPaymentRequest: This must be done synchronously inside a user gesture handler, such as a click or tap event. Do not create the session after asynchronous work, such as an await, promise resolution, or callback, because it may no longer be considered part of the original user gesture. If the session is created outside a user gesture handler, Safari throws a JavaScript exception and the Apple Pay sheet does not open. The error message is: Must create a new ApplePaySession from a user gesture handler.

• Populate the Apple Pay payment request: The payment request includes values such as:

  • merchantIdentifier — your registered Merchant Identifier

  • countryCode and currencyCode

  • supportedNetworks

  • merchantCapabilities — include supports3DS, which Apple requires for standard card payments

  • total

  • optional line items

• Handle merchant validation: The Apple Pay session triggers merchant validation and provides a validationURL in the onvalidatemerchant event. The frontend sends this validationURL to the merchant backend. The server-side merchant validation flow must use the validationURL provided by the event.

• Request the merchant session from the backend: The merchant backend sends a POST request to the validationURL to obtain the merchant session object. This request must be made from your server, not the client, as it requires your Merchant Identity Certificate for mutual TLS authentication.

• Complete merchant validation in the frontend: Apple returns a merchant session object. The backend passes it to the frontend, which calls session.completeMerchantValidation(merchantSession) to complete validation and enable the Apple Pay sheet. The merchant session object is single-use and expires after five minutes.

• The customer authorizes the payment: The customer uses Face ID, Touch ID, or device passcode to authorize.

• Receive the encrypted Apple Pay payment token: The onpaymentauthorized event returns the Apple Pay payment data, including the encrypted payment token.

• Submit the encrypted payment data to CMP: The frontend passes event.payment.token.paymentData to the merchant backend, which submits it to CMP. CMP uses the configured Payment Processing Certificate to decrypt the token, extract the wallet card data, create and securely store the card, and return the created card object.

Create Card request

To use Apple Pay Wallet Decryption, submit the encrypted Apple Pay payment token in the Create Card request instead of a decrypted PAN.

CMP uses the key_hash field to identify the correct Apple Pay payment processing certificate for decryption.

Apple Pay token to CMP field mapping

When constructing the Create Card API request, map the fields from event.payment.token.paymentData as follows:

Apple Pay token field	CMP API field	Notes
paymentData.data	encrypted_payload_text	Base64-encoded encrypted payload
paymentData.header.publicKeyHash	key_hash	Used by CMP to identify the correct Payment Processing Certificate. Do not confuse with ephemeralPublicKey
paymentData.header.ephemeralPublicKey	public_key	The ephemeral EC public key for this transaction
paymentData.signature	digital_signature	Base64-encoded signature for payload verification
paymentData.version	version	Must be EC_v1. CMP does not support EC_v2
paymentData.header.transactionId	wallet_transaction_id	Unique transaction identifier generated by Apple per payment authorization
(recommended to set explicitly)	wallet_type	Set to "apple_pay"

Supported encryption version

CMP currently supports Apple Pay tokens using the EC_v1 encryption format.

Create Card response

After decryption, CMP returns a card object containing the decrypted token and associated wallet metadata.

For Apple Pay card creation, the response can include wallet-related metadata such as:

• wallet_type

• token_type

• wallet payment method information

• eci is optional. The card network may add an ECI indicator to the payment data that the payment token includes. If you receive an ECI indicator, you must pass it on to your payment processor; otherwise, the transaction fails.

• masked card details such as BIN, first8, and last4

Response Behavior

• Synchronous response: Apple Pay Wallet Decryption uses a synchronous request-response flow. When you submit an encrypted Apple Pay token to the Create Card API, CMP processes the request and returns the created card object directly in the API response.

• No webhook notifications are sent for this flow. Customers should expect the result in the synchronous Create Card response only. The Create Card response contains all card data and wallet metadata immediately upon successful decryption and card creation.

• Card Attributes: If Card Attributes is enabled for the tenant, the Create Card response also includes advanced card attributes.

Cryptogram handling

For DPAN transactions, the Create Card response may include a cryptogram generated by the wallet at the time of payment.

Cryptogram behavior:

• the cryptogram is single-use

• it is intended only for the initial customer-initiated authorization

• it is not stored by CMP

The Create Card response includes cryptogram and ECI values for DPAN flows. For MPAN flows, instead of cryptogram/ECI, the response includes a merchant_token_identifier and payment_data_type = "MerchantToken".

Because cryptogram and ECI are single-use transaction artifacts, they are not persisted and will not be returned in the GET Card response.

Wallet	Network	ECI value	Authentication / liability meaning	What it means when passed to processor
Apple Pay	Visa / Mastercard / others	Value may or may not be present	eciIndicator may be present, and the value is network-provided. Use processor/network-specific ECI interpretation.	eciIndicator is network-provided and may or may not be present. When present, VGS returns it as received and does not normalize or map it to Apple Pay-specific values. Customers should pass it to their processor unchanged, as altering or hardcoding the value may cause the transaction to fail.

Retrieve Card

When retrieving a card created from Apple Pay using GET /cards/{id}, CMP returns the stored card together with persisted Apple Pay metadata.

Wallet transaction artifacts are not persisted and are therefore not included in GET responses. These include:

• cryptogram

• transaction amount

• currency

• If Card Attributes is enabled for the tenant, the GET Card response also includes advanced card attributes

Limitations

Cards created using Apple Pay Wallet Decryption currently have the following limitations:

• Meta object support is not available for cards created through Apple Pay Wallet Decryption.

• Duplicate card detection logic is not applied when creating cards from encrypted Apple Pay tokens.

• Network Token (NT) services are not supported.

• Account Updater (AU) services are not supported.

• 3D Secure (3DS) authentication is not currently supported for cards created from Apple Pay DPAN or MPAN tokens.

These limitations apply to cards created using Apple Pay Wallet Decryption regardless of whether the resulting token type is DPAN or MPAN.

Currently, CMP supports Apple Pay decryption only. Google Pay is not supported at this time, but the API structure is designed to support additional wallet types in the future.

Apple Pay Wallet Decryption Error Messages

HTTP Code	Summary	Detail	Field
422	must not be null	must not be null	encrypted_payload_text
422	size must be between 20 and 20000	size must be between 20 and 20000	encrypted_payload_text
422	Invalid input format	Must be a valid Base64-encoded string.	encrypted_payload_text
422	must not be null	must not be null	key_hash
422	size must be between 44 and 44	size must be between 44 and 44	key_hash
422	Invalid input format	Must be a valid Base64-encoded string.	key_hash
422	must not be null	must not be null	public_key
422	size must be between 20 and 2048	size must be between 20 and 2048	public_key
422	Invalid input format	Must be a valid Base64-encoded string.	public_key
422	size must be between 10 and 8192	size must be between 10 and 8192	digital_signature
422	Invalid input format	Must be a valid Base64-encoded string.	digital_signature
422	size must be between 1 and 256	size must be between 1 and 255	wallet_transaction_id
422	size must be between 1 and 255	size must be between 1 and 255	display_name
422	size must be between 1 and 255	size must be between 1 and 255	network
422	wallet_type is not supported for wallet decryption	wallet_type 'google_pay' is not supported for wallet decryption	wallet_type
422	size must be between 1 and 255	size must be between 1 and 255	type
422		Unable to decrypt the data provided. Please ensure it is valid and try again	The request contains invalid values for one or more of the following fields: digital_signature, encrypted_payload_text, key_hash, public_key.
400	Validation failed	Unexpected value 'EC_v2'	version
400	Validation failed	Unexpected value 'apple_pay1'	wallet_type
503		Service Unavailable. The downstream network is temporarily unavailable.
500		A problem has occurred with this request.
500		Decryption failed: Failed to decrypt Apple Pay token

Onboarding Requirements

To enable Wallet Decryption Flow support with CMP:

• Apple Pay wallet decryption support must be enabled for the tenant.

• Merchants must configure Apple Pay certificates:

  • Merchant Identity Certificate

  • Payment Processing Certificate

• The payment processing certificate is used by CMP to decrypt Apple Pay tokens. CMP identifies the correct certificate using the key_hash provided in the encrypted request payload.