> For the complete documentation index, see [llms.txt](https://docs.verygoodsecurity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verygoodsecurity.com/cmp/payment-credentials/apple-pay/create-card-apple-pay-wallet-decryption.md). # 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**.**](https://docs.verygoodsecurity.com/cmp/developer-resources/guides/testing/wallet-decrypt) 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: ```bash openssl req -new -newkey rsa:2048 -nodes \ -keyout merchant_id.key \ -out MyCSR.certSigningRequest \ -subj "/C=/ST=/L=/O=/OU=/CN=" ``` Replace the placeholders: * `` — Two-letter country code (e.g., `US`) * `` — State or province (e.g., `California`) * `` — City name (e.g., `San Francisco`) * `` — Your company or organization name * `` — Organizational unit (e.g., `Payments`) * `` — 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](https://developer.apple.com/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: ```bash 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 --type apple-pay-payment-processing --name merchant.com.example -o payment_processing.csr ``` Replace: * `` 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 \ --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**](https://docs.verygoodsecurity.com/cmp/products-and-services/card-attributes)**:** If Card Attributes is enabled for the account, 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](https://docs.verygoodsecurity.com/cmp/products-and-services/card-attributes) is enabled for the account, 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 CodeSummaryDetailField
422must not be nullmust not be nullencrypted_payload_text
422size must be between 20 and 20000size must be between 20 and 20000encrypted_payload_text
422Invalid input formatMust be a valid Base64-encoded string.encrypted_payload_text
422must not be nullmust not be nullkey_hash
422size must be between 44 and 44size must be between 44 and 44key_hash
422Invalid input formatMust be a valid Base64-encoded string.key_hash
422must not be nullmust not be nullpublic_key
422size must be between 20 and 2048size must be between 20 and 2048public_key
422Invalid input formatMust be a valid Base64-encoded string.public_key
422size must be between 10 and 8192size must be between 10 and 8192digital_signature
422Invalid input formatMust be a valid Base64-encoded string.digital_signature
422size must be between 1 and 256size must be between 1 and 255wallet_transaction_id
422size must be between 1 and 255size must be between 1 and 255display_name
422size must be between 1 and 255size must be between 1 and 255network
422wallet_type is not supported for wallet decryptionwallet_type 'google_pay' is not supported for wallet decryptionwallet_type
422size must be between 1 and 255size must be between 1 and 255type
422Unable to decrypt the data provided. Please ensure it is valid and try againThe request contains invalid values for one or more of the following fields: digital_signature, encrypted_payload_text, key_hash, public_key.
400Validation failedUnexpected value 'EC_v2'version
400Validation failedUnexpected value 'apple_pay1'wallet_type
503
Service Unavailable. The downstream network is temporarily unavailable.
500A 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 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.verygoodsecurity.com/cmp/payment-credentials/apple-pay/create-card-apple-pay-wallet-decryption.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.