⚒️VGS for Merchants - Wallet Decrypt Implementation Guide

Decrypt Apple Pay payment tokens with CMP and route payments through the Outbound Proxy.

Overview

Use this guide to create a Credential Management Platform card from an encrypted Apple Pay payment token.

CMP decrypts the token, stores the wallet credential, and returns a card object with wallet metadata.

In most merchant flows, your backend stores card_id and aliases only.

Wallet Decrypt currently supports Apple Pay only.

Benefits

Use Wallet Decrypt to:

• Keep raw wallet credentials out of merchant systems

• Reduce PCI scope

• Create reusable wallet cards in CMP

• Route authorizations through the Outbound Proxy with aliases

---

Before you begin

Make sure you have:

• A VGS organization with CMP enabled

• OAuth credentials for CMP APIs

• A configured VGS Outbound Proxy

• Access to your PSP sandbox

• Apple Pay sandbox test accounts and devices

For Apple Pay, you also need:

• An Apple Developer account

• A Merchant Identifier

• A Payment Processing Certificate uploaded to VGS

• A Merchant Identity Certificate only if you use Apple Pay on the web

---

High-level solution architecture

This flow lets you accept Apple Pay without building your own decryption service.

---

How Wallet Decrypt works

1. The customer authorizes Apple Pay at checkout.

2. Apple returns an encrypted payment token to your frontend.

3. Your backend sends the encrypted token to POST /cards.

4. CMP decrypts the token with your configured Apple Pay payment processing certificate.

5. CMP creates a card and returns the card object with aliases and wallet metadata.

6. Your backend builds the authorization request with the returned values.

7. The payment request goes through the VGS Outbound Proxy to your PSP.

8. The proxy detokenizes aliases before forwarding the request.

Do not send wallet aliases or raw wallet credentials directly to your PSP. Route payment requests through the VGS Outbound Proxy.

---

Configure Apple Pay certificates

CMP uses your Apple Pay payment processing certificate to decrypt the token.

1. Generate an Apple Pay payment processing CSR in VGS.

2. Upload the CSR to Apple Developer.

3. Download the Apple-signed certificate.

4. Upload the signed certificate to VGS.

5. Send the token's publicKeyHash value as key_hash in the Create Card request.

Use an ECC-based CSR. Apple Pay Wallet Decryption supports EC_v1 only.

For the full certificate flow, see Apple Pay and Create Card - Apple Pay Wallet Decryption.

---

Create a card from an encrypted Apple Pay token

Submit the encrypted Apple Pay payload to the Cards API.

POST /cards

{
  "data": {
    "attributes": {
      "encrypted_payment_data": {
        "encrypted_payload_text": "<paymentData.data>",
        "key_hash": "<paymentData.header.publicKeyHash>",
        "public_key": "<paymentData.header.ephemeralPublicKey>",
        "digital_signature": "<paymentData.signature>",
        "version": "EC_v1",
        "wallet_type": "apple_pay",
        "wallet_transaction_id": "<paymentData.header.transactionId>"
      }
    }
  }
}

You can also include payment_method if you want CMP to persist wallet display metadata such as display name, network, and type.

What the response includes

On success, CMP returns a card object and related wallet metadata.

Expect the response to include:

• card_id

• pan_alias

• wallet_type

• token_type as dpan or mpan

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

• wallet_details.payment_data_type

For DPAN flows, the response can also include:

• wallet_details.cryptogram

• wallet_details.cryptogram.eci

For MPAN flows, the response can include:

• wallet_details.merchant_token_identifier

The cryptogram is single-use. Use it only for the initial customer-authorized transaction. CMP does not persist it.

---

Process payments

After card creation:

1. Store the returned card_id.

2. Build the authorization request with the aliases and wallet values from the Create Card response.

3. Send the request through the VGS Outbound Proxy.

4. Let the proxy reveal aliases before the request reaches your PSP.

Customer-initiated transactions

For the first Apple Pay authorization, pass the single-use cryptogram and ECI when they are present in the response.

Typical fields include:

• DPAN

• Cryptogram

• ECI

• Expiration date

Merchant-initiated transactions

Recurring or scheduled transactions do not generate a new wallet cryptogram.

Store the network transaction ID returned by your PSP from the original customer-initiated authorization. Many PSPs require it for later stored credential transactions.

---

Retrieve the card

Use GET /cards/{card_id} to retrieve the stored card later.

The response includes persisted wallet metadata and masked card details.

Single-use payment artifacts are not returned.

This includes:

• cryptogram

• amount

• currency

---

Limitations

Cards created through Apple Pay Wallet Decryption have these limitations:

• Wallet Decrypt supports Apple Pay only

• Duplicate card detection is not applied

• Network Tokens are not supported

• Account Updater is not supported

• 3DS is not supported

• Card meta is not supported

---

Test the integration

Validate the integration in this order:

1. Create a card from an encrypted Apple Pay payload.

2. Confirm the response includes the expected wallet metadata.

3. Retrieve the card with GET /cards/{card_id}.

4. Send an authorization through your sandbox PSP and the Outbound Proxy.

Keep these points in mind:

• Apple Pay cryptograms are single-use

• Apple Pay sandbox testing requires Apple sandbox setup

• GET /cards/{card_id} does not return cryptogram, amount, or currency

For step-by-step testing flows, see Wallet Decrypt.

---

Next steps

Use these pages to complete the integration:

• VGS for Merchants - Implementation Guide

• Apple Pay

• Create Card - Apple Pay Wallet Decryption

• Wallet Decrypt