Apple Pay

Apple Pay Integration

Overview

CMP supports storing Apple Pay wallet cards, including Device Primary Account Numbers (DPANs) and Merchant Primary Account Numbers (MPANs). Merchants can store Apple Pay cards in CMP in two ways:

1. Submit a decrypted wallet token (DPAN or MPAN) directly to CMP.

2. Submit an encrypted Apple Pay payment token, which CMP decrypts and converts into a stored card.

Both approaches result in a card stored in CMP that can be retrieved using the standard GET /cards/{id} API.

Understanding Apple Pay Tokens

When a customer pays using Apple Pay, the wallet generates a tokenized representation of the card rather than exposing the original PAN.

DPAN (Device PAN)

A DPAN is generated by the wallet for a specific device and card combination. It is commonly used for Apple Pay payments today.

Characteristics:

• Device-specific

• Used in Apple Pay transactions initiated by the customer

• Requires a cryptogram for the first authorization

• Can support recurring payments when properly linked to prior transactions

MPAN (Merchant PAN)

An MPAN is a merchant-specific network token provisioned by the card network.

Characteristics:

• Merchant-scoped rather than device-scoped

• Supports token lifecycle management (updates, suspensions, expiration changes)

• Designed to improve authorization rates for recurring payments

• Not tied to a specific device

MPAN support is expected to expand as Apple and card networks increase adoption.

Create Card - Using DPAN or MPAN

The CMP Create Card API supports storing digital wallet cards, including Apple Pay Device PANs (DPANs) and Merchant PANs (MPANs), alongside traditional physical cards (PANs).

Cards classified as dpan or mpan from Apple Pay do not trigger downstream services such as Account Updater, Network Token provisioning, even if the account is configured for onCreate enrollment type. Cards stored in this way behave similarly to traditional cards but are tagged with Apple Pay metadata.

To store an decrypted Apple Pay DPAN or MPAN, include the wallet token in the pan field of the Create Card request. Additionally, specify the following in the card object:

• wallet_type: apple_pay

• token_type: dpan / mpan

It’s important that merchants pass these values in lowercase only, as incorrect formatting will cause validation errors.

Note:

• Apple Pay wallet tokens are only retrievable through GET /cards/{id}. They are clearly marked as DPAN or MPAN and are not included in notifications.

• Apple Pay DPAN/MPAN cards do not trigger downstream services such as Account Updater, Network Token provisioning or 3DS.

• This applies even if the account is configured for onCreate enrollment.

• Tokenized wallet cards are retrievable via GET /cards/{id} .

Validation Rules when Creating a Card with DPAN/MPAN

• If creating a DPAN or MPAN from Apple Pay, the wallet_type field must be included. Omitting it will return a 422 Unprocessable Entity error.

• For physical PANs, wallet_type and token_type are optional, but token_type is always returned in the response as pan.

• Both wallet_type and token_type must be lowercase. For example: "Apple Pay" or "apple_Pay" will fail validation. Similarly, "DPAN" or "MPAN" in uppercase will also fail, returning 400 Bad Request.

You can see a sample request and response for Apple Pay cards here: VGS Card Management API – Create a Card.

Retrieve Card (GET /cards/{id})

When retrieving an Apple Pay card, the response includes wallet_type and token_type in the card object. These values match the ones sent during creation (wallet_type: apple_pay, token_type: dpan/mpan) and clearly indicate that the card is an Apple Pay DPAN or MPAN.

Sample response: VGS Card Management API – Get a Card.

Onboarding Requirements

No extra steps are needed. Customers already using CMP for card creation can immediately store Apple Pay cards without additional setup.

Create Card - Apple Pay Wallet Decryption

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 Apple-compliant key, extracts the DPAN or MPAN, creates and securely stores the card, and returns the created card object in the API response.

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

Before you begin

To use Apple Pay Wallet Decryption with CMP:

• Apple Pay Wallet Decryption must be enabled for your account

• your Apple Pay domain must be verified and registered

• you must configure the required Apple Pay certificates:

  • Merchant Identity Certificate

  • Payment Processing Certificate

CMP uses the payment processing certificate to decrypt Apple Pay tokens and identifies the correct certificate using the key_hash value provided 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:

• The merchant registers and verifies the web domain with Apple. The apple-developer-merchantid-domain-association file must be hosted at /.well-known/apple-developer-merchantid-domain-association.

• The customer clicks the Apple Pay button.

• The frontend creates an ApplePaySession using an ApplePayPaymentRequest. This includes payment request details such as:

  • country and currency codes

  • supported networks, such as Visa, Mastercard, and Amex

  • merchant capabilities, such as supports3DS

  • total payment amount and optional line items

• The Apple Pay session triggers merchant validation and provides a validationURL.

• The frontend sends the validationURL to the merchant backend.

• The merchant backend sends the validation request to Apple using the Merchant Identity Certificate to authenticate the merchant and retrieve a merchant session object.

• Apple returns the merchant session object, and the backend passes it back to the frontend. The frontend then calls session.completeMerchantValidation(merchantSession) to complete merchant validation and enable the Apple Pay sheet.

• The customer authorizes the payment using Touch ID, Face ID, or device passcode.

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

• The merchant submits the encrypted Apple Pay payment data 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.

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

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.

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

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

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.

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

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	encryptedPayloadText
422	size must be between 20 and 20000	size must be between 20 and 20000	encryptedPayloadText
422	Invalid input format	Must be a valid Base64-encoded string.	encrypted_payload_text
422	must not be null	must not be null	keyHash
422	size must be between 44 and 44	size must be between 44 and 44	keyHash
422	Invalid input format	Must be a valid Base64-encoded string.	key_hash
422	must not be null	must not be null	publicKey
422	size must be between 20 and 2048	size must be between 20 and 2048	publicKey
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	digitalSignature
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 256	walletTransactionId
422	size must be between 1 and 255	size must be between 1 and 255	displayName
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	decryption

Onboarding Requirements

To enable Wallet Decryption Flow support with CMP:

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

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

Apple Pay Recurring Payment Model

When using wallet tokens such as DPANs or MPANs for subscriptions or recurring billing, payments follow a Customer-Initiated Transaction (CIT) followed by Merchant-Initiated Transactions (MIT).

Step 1 — Customer-Initiated Transaction (CIT)

The first payment must be initiated by the customer (for example, during checkout using Apple Pay).

During this step:

• Apple Pay generates a single-use cryptogram

• The merchant submits the DPAN + cryptogram to their PSP

• The PSP processes the authorization request

If authorization succeeds, the card network returns a Network Transaction ID (NTID).

The merchant must store:

• DPAN (vaulted by CMP)

• Expiration date

• Network Transaction ID (NTID)

The cryptogram:

• Is single-use

• Expires quickly

• Cannot be reused if the authorization fails

If the transaction fails, the customer must initiate a new Apple Pay session to generate a new cryptogram.

Step 2 — Merchant-Initiated Transactions (MIT)

All subsequent recurring payments occur without customer interaction.

MIT requests typically include:

• DPAN or MPAN

• Expiration date

• Previous Network Transaction ID (NTID)

• Stored credential indicators

• ECI value

The NTID links the recurring payment chain back to the original customer-authorized transaction. Without it, authorization rates may drop or transactions may be declined.

Card Attributes

Card Attributes are available for DPAN.