> 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/platform/vgs-for-merchants-wallet-decrypt-implementation-guide.md).
# VGS for Merchants - Wallet Decrypt Implementation Guide
### Overview
Use this guide to create a [Credential Management Platform](/cmp/platform/overview.md#vgs-card-management-platform-cmp) 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
{% hint style="info" %}
This flow lets you accept Apple Pay without building your own decryption service.
{% endhint %}
***
### 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.
{% hint style="warning" %}
Do not send wallet aliases or raw wallet credentials directly to your PSP. Route payment requests through the VGS Outbound Proxy.
{% endhint %}
***
### 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](/cmp/payment-credentials/apple-pay.md) and [Create Card - Apple Pay Wallet Decryption](/cmp/payment-credentials/apple-pay/create-card-apple-pay-wallet-decryption.md).
***
### Create a card from an encrypted Apple Pay token
Submit the encrypted Apple Pay payload to the Cards API.
```http
POST /cards
```
```json
{
"data": {
"attributes": {
"encrypted_payment_data": {
"encrypted_payload_text": "",
"key_hash": "",
"public_key": "",
"digital_signature": "",
"version": "EC_v1",
"wallet_type": "apple_pay",
"wallet_transaction_id": ""
}
}
}
}
```
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`
{% hint style="info" %}
The cryptogram is single-use. Use it only for the initial customer-authorized transaction. CMP does not persist it.
{% endhint %}
***
### 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](/cmp/developer-resources/guides/testing/wallet-decrypt.md).
***
### Next steps
Use these pages to complete the integration:
* [VGS for Merchants - Implementation Guide](/cmp/platform/vgs-for-merchants-implementation-guide.md)
* [Apple Pay](/cmp/payment-credentials/apple-pay.md)
* [Create Card - Apple Pay Wallet Decryption](/cmp/payment-credentials/apple-pay/create-card-apple-pay-wallet-decryption.md)
* [Wallet Decrypt](/cmp/developer-resources/guides/testing/wallet-decrypt.md)
---
# 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/platform/vgs-for-merchants-wallet-decrypt-implementation-guide.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.