# Wallet Decrypt

## **Apple Pay Wallet Decryption Testing Guide**

This guide explains how to test **Apple Pay Wallet Decryption** in a controlled environment. You can test both **DPAN** and **MPAN** wallet decryption flows and validate the resulting **Create Card** and **Get Card by ID** behavior.

Testing can be performed in two ways:

* **Mock Testing** – using static encrypted Apple Pay payloads that return predictable decrypted DPAN or MPAN card data
* **Sandbox Testing** – using encrypted Apple Pay payloads in the sandbox environment with Apple Pay Wallet Decryption enabled on the account

## **General Setup**

* **Content-Type header:** `application/vnd.api+json`
* **HTTP method:** `POST` for card creation
* **GET /cards/{id}** can be used after card creation to retrieve the stored card
* Apple Pay Wallet Decryption supports encrypted Apple Pay payloads using the **EC\_v1** format
* The encrypted payload is sent in the `encrypted_payment_data` object of the **Create Card API** request

Each successful request creates a new CMP card and returns a new `card_id`.

## **What Apple Pay Wallet Decryption Does**

When an encrypted Apple Pay payload is submitted to CMP:

* CMP performs **wallet decryption**
* CMP extracts the **DPAN** or **MPAN**
* CMP creates and stores the card in CMP
* CMP returns the created card object, including wallet metadata

For successful responses, the wallet metadata may include:

* `wallet_type`
* `token_type`
* `wallet_details.payment_data_type`
* `wallet_details.device_manufacturer_identifier`
* `wallet_details.transaction_id`
* `wallet_details.cryptogram` for DPAN
* `wallet_details.merchant_token_identifier` for MPAN

## **Mock Testing**

Use Mock Testing to verify Apple Pay Wallet Decryption behavior without requiring Apple Pay Wallet Decryption to be enabled on the CMP account.

### Mock Testing Requirements

When using mock testing:

* A **CMP account** is required
* A **JWT auth token** is required
* **Apple Pay Wallet Decryption account configuration is not required to be enabled**
* A **new card ID** is generated for each successful request
* The decrypted card content returned by the mock remains otherwise static for the same test payload

### Request Requirements

* **Base URL:** <https://sandbox.vgsapi.com>
* **Header required:** `Content-Type: application/vnd.api+json`
* Send the encrypted Apple Pay payload using the standard **Create Card API** shape

### Mock Testing – DPAN

Use the following encrypted Apple Pay payload to simulate decryption of a **DPAN** token.

```json
{
  "data": {
    "attributes": {
      "encrypted_payment_data": {
        "digital_signature": "TUlBR0NTcUdTSWIzRFFFSEFxQ0FNSUFDQVFFeERUQUxCZ2xnaGtnQlpRTUVBZ0V3Z0FZSktvWklodmNOQVFjQkFBQ2c=",
        "encrypted_payload_text": "OzF2HRdPNYZPixxpyZ3GzTxm/qXSLP65bZ+yM8I0XFjuB72B+dtRPZKjNwNV13Yy2TD+6LInN8LzvZXk9Q0WW+gms+tacfDKsdIR1vidJhsKSZF9yZ5BwyKN3Nv0J7RQsGi8hjILxVBNxnA5vdTHCMOGcy/9cwBDLyU1boTRrxd8gBbu4UWzdDy+8KhCxMpADBbTF0J9DEaa6Iz/uCLlQgv26xxvBSSdDcn1ZhsaHJN+YJlnkcyckPj1zf2F+2EfqOdEvxAWQNAGd2d5zi+tl3LVwVes1xorl7M8qC+LFqo9MNCefhmSsLT8P3RTEkrn2SoZ5qEv0uBXapQWJMnLlkBCpZF0fkTKEzC67i7wiz4qnDaBogaiY/qsaccgJ5xHk2Il2Wgt6Y2+gdk9wBqaRu0kKgEThth6mU/NCOYKoIPzJm6KWa0o3gJ9bhq/SJaVlsVrov81Ps7i03/sHmq/Sve/5uRJys0d0BUHzDrasQH35973JMpxaZ0TdiwHnHU5VWNbV2FKxh6k9e0YqmMZ//DX36h5EOa7iSinfRGQdF6IQ/8e7nazYwtX0iV8IQ4n8P/cwIn9Gn5xmeTSdfOEO1o=",
        "key_hash": "DPAN/4VEn0bzlhTscArIT3Gvbq2MKiZlHAlZc76kAUx=",
        "public_key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE0eamXz+Xza8La9eOAIYf307qxJOVRRf9oTLlm61o0dLPvpXtPiEno2QzvzX/ucbugivotW2+gi5x/Ff8c7adfg==",
        "version": "EC_v1",
        "wallet_type": "apple_pay",
        "wallet_transaction_id": "6e21f9bf4aea3f767c5e48eeae92d8af9b8919c3ad9854fd1320b7867499c6fe",
        "payment_method": {
          "display_name": "Visa 0121",
          "network": "Visa",
          "type": "credit"
        }
      }
    }
  }
}
```

### Expected DPAN Mock Response

A successful mock DPAN request returns a card with:

* `token_type: dpan`
* `wallet_type: apple_pay`
* `payment_data_type: 3DSecure`
* `device_manufacturer_identifier`
* `cryptogram`
* `transaction_id`
* `payment_method` details if provided in the request

#### Example response

```json
{
	"data": {
		"id": "CRDKfukrUmMsUdotydKS4euZ1v2exoN617mWi7avaehqkYh2J5JP",
		"type": "cards",
		"attributes": {
			"pan": "5100260000019206",
			"exp_month": 12,
			"exp_year": 99,
			"cardholder": {
				"name": "John Q. Public",
				"company": "VGS",
				"phone": "+18881112222",
				"address": {
					"address1": "301 Test Loop",
					"city": "San Francisco",
					"region": "California",
					"postal_code": "11111",
					"country": "US"
				}
			},
			"token_type": "dpan",
			"wallet_type": "apple_pay",
			"pan_alias": "tok_sandbox_QfJDZdyBR6pygJ13xPXrkB",
			"bin": "510026",
			"first8": "51002600",
			"last4": "9206",
			"card_fingerprint": "fjLdCHgcSJmnSqzpSQafJvmuPep5vSdV5w2nJC1sWuFp",
			"created_at": "2025-08-01T00:00:00",
			"updated_at": "2025-08-01T00:00:00",
			"wallet_details": {
				"currency_code": "USD",
				"amount": 2500,
				"device_manufacturer_identifier": "040010030273",
				"payment_data_type": "3DSecure",
				"cryptogram": {
					"type": "TAVV",
					"value": "Ab2c/XwBBB/EknV76pyc2NBBCCC=",
					"eci": "7"
				},
				"payment_method": {
					"display_name": "Visa 0121",
					"network": "Visa",
					"type": "credit"
				},
				"transaction_id": "9a0650018c263c03fb34618407fb00a3026aee366b230e013605a12e5201574b"
			}
		}
	},
	"metadata": {
		"observability": {
			"trace_id": "c2a171cff919032f17515338db2527fe",
			"client_id": "ACwmzJCti-3DS_Account-dFbIj",
			"vault_id": "tntfn3pqdcf",
			"account_id": "ACT3Wjs6gwrcHxzjcro4H9G8W",
			"fingerprint": "4GqVMtYY8uohfuZ5zhrAZfs5VexAbihfrL8qyTfudEBpEgWiXCPuEAJtC91"
		}
	}
}
```

### Mock Testing – MPAN

Use the following encrypted Apple Pay payload to simulate decryption of an **MPAN** token.

```json
{
  "data": {
    "attributes": {
      "encrypted_payment_data": {
        "digital_signature": "TUlBR0NTcUdTSWIzRFFFSEFxQ0FNSUFDQVFFeERUQUxCZ2xnaGtnQlpRTUVBZ0V3Z0FZSktvWklodmNOQVFjQkFBQ2c=",
        "encrypted_payload_text": "JFk4RJoiod18IQmwcjtU88ZimrS543kxzoXw2vQjTl08ud6MV9kzf6NiSJ1Ev7HZ8IcrtzUXb69sbO/W/PcV13h+WRtYvmD7GTCSypimqcitvE78zCDRUpV6g2zsapFm2/R3jFcdDlmvP4L5/mkKU/pWx0hA/MiUe7XoGc+2jEUI7tAB8XZebV7lPlSFLBA2Q46JKsmsigkvmY3wfuYKJDg/niD6yL4LgIA0KAnh8YjU/88UjLbvi6mkII7MjJri6RiTqQ3EDGBZX84SlPus1NYVe1yMwqjG8e7Pza8kDZ6C4Wyz/5SksMpEnUxanWAfKnc37nJGkn9KiCktLwXGRLT7hEHszsvs/yu6ZUY3E8SJ9LYb2fAn3IXqJEyDXWZgRdF1tVrW0hqYrWRvUfcJ7gqRCL8/0k9nRGHhw4+r4hiVOz2hadd4T5cxjfWsfCSg4UEFv2rCZ8K7qkS1XQsZmbuqjDNnzS+vPd/Hk7xDJ+cSiySD/KcE8g==",
        "key_hash": "MPAN/3FruspO6vAy8AQ3UKiJeF14wgTUYmGAPwlbiqk=",
        "public_key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE0mrNoedmyYa/Qfp+1GlUIa8x0Fu1tgTattp0678fEUTPEcVfqsizY/8LP/4T34wNGbvLPV8zTEICHaoFWxpeig==",
        "version": "EC_v1",
        "wallet_type": "apple_pay",
        "wallet_transaction_id": "9f0f709cc538c7207169cf9f44e668b8e3cadf73c2d84b0c1b1e2b6caf7f07a1",
        "payment_method": {
          "display_name": "Visa 0121",
          "network": "Visa",
          "type": "credit"
        }
      }
    }
  }
}
```

### Expected MPAN Mock Response

A successful mock MPAN request returns a card with:

* `token_type: mpan`
* `wallet_type: apple_pay`
* `payment_data_type: MerchantToken`
* `device_manufacturer_identifier`
* `merchant_token_identifier`
* `transaction_id`
* `payment_method` details if provided in the request

#### Example response

```json
{
	"data": {
		"id": "CRDqL55P51GVUMbZMDgYakHQTJSoFP2e8NoMXzhQpVPgLh91ZEQo",
		"type": "cards",
		"attributes": {
			"pan": "5100260000009207",
			"exp_month": 12,
			"exp_year": 99,
			"cardholder": {
				"name": "John Q. Public",
				"company": "VGS",
				"phone": "+18881112222",
				"address": {
					"address1": "301 Test Loop",
					"city": "San Francisco",
					"region": "California",
					"postal_code": "11111",
					"country": "US"
				}
			},
			"token_type": "mpan",
			"wallet_type": "apple_pay",
			"pan_alias": "tok_sandbox_oO3YeAP3eDJhPclNtEPcJI",
			"bin": "510026",
			"first8": "51002600",
			"last4": "9207",
			"card_fingerprint": "2kPZBjQpaX6PnxrbvPTYzAC2ckcVNqNTxCAkdAn3tnTn",
			"created_at": "2025-08-01T00:00:00",
			"updated_at": "2025-08-01T00:00:00",
			"wallet_details": {
				"currency_code": "USD",
				"amount": 2500,
				"device_manufacturer_identifier": "040010030273",
				"payment_data_type": "MerchantToken",
				"merchant_token_identifier": "DNITHE302308980001844",
				"payment_method": {
					"display_name": "Visa 0121",
					"network": "Visa",
					"type": "credit"
				},
				"transaction_id": "9a0650018c263c03fb34618407fb00a3026aee366b230e013605a12e5201574b"
			}
		}
	},
	"metadata": {
		"observability": {
			"trace_id": "250631059828f5a07e92f202fde52fa6",
			"client_id": "ACwmzJCti-3DS_Account-dFbIj",
			"vault_id": "tntfn3pqdcf",
			"account_id": "ACT3Wjs6gwrcHxzjcro4H9G8W",
			"fingerprint": "4GqVMtYY8uohfuZ5zhrB2MNc1fKeqyK8VaZ7AqS8oBtqrehfoHhAFsztc3Q"
		}
	}
}
```

### Mock Testing – 5xx Error&#x20;

Use the following encrypted Apple Pay payload to simulate a 5xx error response.

```json
{
  "data": {
    "attributes": {
      "encrypted_payment_data": {
        "digital_signature": "TUlBR0NTcUdTSWIzRFFFSEFxQ0FNSUFDQVFFeERUQUxCZ2xnaGtnQlpRTUVBZ0V3Z0FZSktvWklodmNOQVFjQkFBQ2c=",
        "encrypted_payload_text": "OzF2HRdPNYZPixxpyZ3GzTxm/qXSLP65bZ+yM8I0XFjuB72B+dtRPZKjNwNV13Yy2TD+6LInN8LzvZXk9Q0WW+gms+tacfDKsdIR1vidJhsKSZF9yZ5BwyKN3Nv0J7RQsGi8hjILxVBNxnA5vdTHCMOGcy/9cwBDLyU1boTRrxd8gBbu4UWzdDy+8KhCxMpADBbTF0J9DEaa6Iz/uCLlQgv26xxvBSSdDcn1ZhsaHJN+YJlnkcyckPj1zf2F+2EfqOdEvxAWQNAGd2d5zi+tl3LVwVes1xorl7M8qC+LFqo9MNCefhmSsLT8P3RTEkrn2SoZ5qEv0uBXapQWJMnLlkBCpZF0fkTKEzC67i7wiz4qnDaBogaiY/qsaccgJ5xHk2Il2Wgt6Y2+gdk9wBqaRu0kKgEThth6mU/NCOYKoIPzJm6KWa0o3gJ9bhq/SJaVlsVrov81Ps7i03/sHmq/Sve/5uRJys0d0BUHzDrasQH35973JMpxaZ0TdiwHnHU5VWNbV2FKxh6k9e0YqmMZ//DX36h5EOa7iSinfRGQdF6IQ/8e7nazYwtX0iV8IQ4n8P/cwIn9Gn5xmeTSdfOEO1o=",
        "key_hash": "DPAN/RGVjcnlwdGlvbkVycm9yVGVzdEtleUZvck1vY2=",
        "public_key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE0eamXz+Xza8La9eOAIYf307qxJOVRRf9oTLlm61o0dLPvpXtPiEno2QzvzX/ucbugivotW2+gi5x/Ff8c7adfg==",
        "version": "EC_v1",
        "wallet_type": "apple_pay",
        "wallet_transaction_id": "6e21f9bf4aea3f767c5e48eeae92d8af9b8919c3ad9854fd1320b7867499c6fe",
        "payment_method": {
          "display_name": "Visa 0121",
          "network": "Visa",
          "type": "credit"
        }
      }
    }
  }
}
```

### Expected Error Mock Response

A failed mock request returns an error response with:

* `errors[].detail`
* `errors[].error_code`
* `meta.observability.trace_id`
* `meta.observability.client_id`
* `meta.observability.vault_id`
* `meta.observability.account_id`
* `meta.observability.fingerprint`

#### Example response

```json
{
	"errors": [
		{
			"detail": "Decryption failed due to an internal error",
			"error_code": "INTERNAL"
		}
	],
	"meta": {
		"observability": {
			"trace_id": "ff058f978b58bee834ba2b806a8b0aed",
			"client_id": "ACsPTgxhw-AutoTest5-vP8pD",
			"vault_id": "tntefvvq6tt",
			"account_id": "ACTgSbmT2R7a6pjgi4cCrTkoj",
			"fingerprint": "4GqVMtYY8uohfBxjwFF4PF4ANEYCgGFMrpWzHmgU5zvHBsjXdR78yrY3YJC"
		}
	}
}
```

### Get Card by ID After Mock Creation

You can call **GET /cards/{id}** using the `card_id` returned from either the DPAN or MPAN mock response.

This allows you to verify what wallet metadata is persisted after card creation.

**Static mock CardIDs**

The following static CardIDs can be used with the **Get Card by ID** request for mock test payloads:

* **MPAN:** `CRDifkUMiwjdcZTA6USirUsC7xoN617mWi7avaehqkYhMPAN1JP`
* **DPAN:** `CRDifkUMiwjdcZTA6USirUsC7xoN617mWi7avaehqkYhDPAN1JP`

### Important GET Behavior

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

* `currency_code`
* `amount`
* `cryptogram`

For DPAN cards, the GET response will still include persisted wallet details such as:

* `device_manufacturer_identifier`
* `payment_data_type`
* `payment_method` details if provided in the request

For MPAN cards, the GET response will still include persisted wallet details such as:

* `device_manufacturer_identifier`
* `payment_data_type`
* `merchant_token_identifier`
* `payment_method` details if provided in the request

#### Example GET Response – DPAN

```json
{
  "data": {
    "id": "CRDoEYk47qUtndEHR9w8kGKra",
    "type": "cards",
    "attributes": {
      "pan": "4111111111111444",
      "cvc_status": "not-set",
      "exp_month": 8,
      "exp_year": 28,
      "cardholder": {},
      "token_type": "dpan",
      "wallet_type": "apple_pay",
      "pan_alias": "tok_sandbox_kAYsfM1wyRwbJEesrnqFFi",
      "bin": "411111",
      "first8": "41111111",
      "last4": "1444",
      "card_fingerprint": "Qg3rYRJd4gjHYefhxpwfS2XkUovBwF2uVNhUPXgCj2H",
      "created_at": "2026-03-11T01:47:32.601715",
      "updated_at": "2026-03-11T01:47:32.601716",
      "wallet_details": {
        "device_manufacturer_identifier": "040010030400",
        "payment_data_type": "3DSecure",
        "payment_method": {
          "display_name": "Visa 0121",
          "network": "Visa",
          "type": "credit"
        }
      }
    }
  },
  "metadata": {
    "observability": {
      "trace_id": "707a927ca06a9db1d6ac0cc6705cdf11",
      "client_id": "AChkBQQGH-3DS-scope-61fC0",
      "vault_id": "tntiugemxfd",
      "account_id": "ACT9eeBkBsxXe9wWJkQdpG2kC",
      "fingerprint": "4GqVMtYY8uohftF2NdrQjH4TApUbjScwsB5oXACgvq8ATZkzALLtZSGYwo5"
    }
  }
}
```

#### Example GET Response – MPAN

```json
{
  "data": {
    "id": "CRDm3dzAeDCnfkwfqTEufFtz6",
    "type": "cards",
    "attributes": {
      "pan": "4111111111111222",
      "cvc_status": "not-set",
      "exp_month": 11,
      "exp_year": 27,
      "cardholder": {},
      "token_type": "mpan",
      "wallet_type": "apple_pay",
      "pan_alias": "tok_sandbox_kQy6qwjCP2NGGExD81dRpa",
      "bin": "411111",
      "first8": "41111111",
      "last4": "1222",
      "card_fingerprint": "b3p67ZCV6FcVnx9WtyKH2EQtfeax7yyq9cdvSm7k7rRX",
      "created_at": "2026-03-11T01:52:11.803918",
      "updated_at": "2026-03-11T01:52:11.803919",
      "wallet_details": {
        "device_manufacturer_identifier": "040010030299",
        "payment_data_type": "MerchantToken",
        "merchant_token_identifier": "DNITHE302308980001846",
        "payment_method": {
          "display_name": "Visa 0121",
          "network": "Visa",
          "type": "credit"
        }
      }
    }
  },
  "metadata": {
    "observability": {
      "trace_id": "d88aa1542357f9ae5be8b3f53df79762",
      "client_id": "AChkBQQGH-3DS-scope-61fC0",
      "vault_id": "tntiugemxfd",
      "account_id": "ACT9eeBkBsxXe9wWJkQdpG2kC",
      "fingerprint": "4GqVMtYY8uohftF2NdrQjFSG6JsmX1gTaVFegV9uF4zsdjEdKCP7CUyc1tA"
    }
  }
}
```

## Sandbox Testing

### Test Apple Pay decryption in sandbox

Before running sandbox tests, make sure Apple Pay Wallet Decryption is enabled for your CMP account and that your Apple Pay setup is complete, including the required certificate configuration and upload of the signed certificates in VGS. For setup instructions, see [Setting Up Your Apple Certificates](https://docs.verygoodsecurity.com/cmp/payment-credentials/apple-pay#setting-up-your-apple-certificates). VGS uses the configured Apple Pay payment processing certificate to decrypt Apple Pay payment tokens.

For **Apple Pay on the web**, your integration must also be fully configured to support merchant validation and domain verification. For **app-based integrations**, make sure your Apple Pay entitlement and sandbox test setup are complete.

To test Apple Pay decryption, generate an encrypted Apple Pay payload by completing a **real Apple Pay test transaction** in Apple’s sandbox environment. Apple Pay returns the encrypted payment token as part of the payment authorization response, and that token can be sent to VGS for decryption testing. Apple’s sandbox supports testing Apple Pay transactions with sandbox accounts and test cards. ([Apple Developer](https://developer.apple.com/apple-pay/sandbox-testing)).

#### Steps

1. **Set up Apple Pay for your app or website**\
   Make sure your Apple Pay integration is configured in your Apple Developer account. Apple’s implementation guide is here. ([Apple Developer](https://developer.apple.com/apple-pay/implementation))
2. **Create a Sandbox Apple Account**\
   In App Store Connect, create a sandbox tester account to use for Apple Pay sandbox transactions. ([Apple Developer](https://developer.apple.com/help/app-store-connect/test-in-app-purchases/create-a-sandbox-apple-account))
3. **Add a sandbox test card to Wallet**\
   Sign in to your test device with the sandbox account and add one of Apple’s sandbox test cards to Wallet. Apple’s sandbox testing guide covers this setup. ([Apple Developer](https://developer.apple.com/apple-pay/sandbox-testing/))
4. **Run a test Apple Pay checkout**\
   Start an Apple Pay payment from your app or Safari website on a supported Apple device and complete the authorization using the sandbox card. Apple Pay will return an encrypted payment token in the authorization response. ([Apple Developer](https://developer.apple.com/apple-pay/sandbox-testing/))
5. **Send the encrypted payload to VGS**\
   Use the encrypted Apple Pay token returned by Apple Pay as the Create Card API payload for VGS decryption testing.

Apple Pay sandbox requires a real card in Apple Wallet.&#x20;

#### Important Sandbox Testing Notes

* Apple Pay sandbox testing requires a **sandbox tester account** and an **Apple Pay sandbox test card** added to Wallet.
* For **web integrations**, Apple Pay sandbox testing also requires successful **domain verification** and **merchant validation**.
* This guide focuses on testing VGS decryption with a real Apple Pay sandbox token. **Customers building the full Apple Pay flow from scratch will also need to complete the surrounding Apple Pay integration, including:**
  * merchant validation for web integrations
  * domain verification for Apple Pay on the web
  * Apple Pay session setup in the app or website
  * extraction of the encrypted Apple Pay token from the payment authorization response
  * mapping the Apple Pay token fields into the VGS Create Card request
  * any required hosted test environment needed for Apple Pay validation flows
* **This guide assumes your Apple Pay integration is already set up and functioning in Apple’s sandbox environment.**

## What to Validate During Testing

For both Mock testing, validate the following:

### DPAN Validation

Confirm that the response includes:

* `token_type: dpan`
* `wallet_type: apple_pay`
* `wallet_details.payment_data_type: 3DSecure`
* `wallet_details.device_manufacturer_identifier`
* `wallet_details.transaction_id`
* `wallet_details.cryptogram`
* `wallet_details.payment_method` if it was provided in the request

### MPAN Validation

Confirm that the response includes:

* `token_type: mpan`
* `wallet_type: apple_pay`
* `wallet_details.payment_data_type: MerchantToken`
* `wallet_details.device_manufacturer_identifier`
* `wallet_details.transaction_id`
* `wallet_details.merchant_token_identifier`
* `wallet_details.payment_method` if it was provided in the request

### GET Validation

After card creation, call **GET /cards/{id}** and confirm that:

* the card is retrievable
* persisted wallet metadata is returned
* `currency_code` is not returned
* `amount` is not returned
* `cryptogram` is not returned

## Important Notes

* Apple Pay Wallet Decryption mock testing does **not** require Wallet Decryption to be enabled on the account
* Apple Pay Wallet Decryption sandbox testing **does** require Wallet Decryption to be enabled on the account
* A new `card_id` is generated for each successful request
* `payment_method` is returned in the response only if it is provided in the request
* Wallet transaction artifacts are not persisted and therefore are not included in GET responses