--- title: Payment token format reference framework: PassKit (Apple Pay and Wallet) role: collectionGroup platforms: [] path: passkit_apple_pay_and_wallet/apple_pay/payment_token_format_reference --- # Payment token format reference Verify an Apple Pay payment token and validate a transaction. ## Overview Apple Pay is available on all iOS devices with a Secure Element — an industry-standard, certified chip designed to store payment information safely. In macOS, users must have an iPhone or Apple Watch that supports Apple Pay to authorize the payment, or have a Mac with Touch ID. The Secure Element creates a payment object when an app or website that uses Apple Pay sends a payment request. The payment object has a nested structure that contains a payment token with encrypted payment data, as shown in the figure below. ![]() The Secure Element encrypts the token’s payment data using either elliptic curve cryptography (ECC) or RSA encryption. The Secure Element selects the encryption algorithm based on the merchant capabilities that the payment request indicates. Most regions use ECC encryption. Other regions use RSA encryption if ECC encryption is unavailable due to regulatory concerns. ### Verify the signature and decrypt the payment data The following steps describe the process of validating a transaction by verifying the signature, decrypting the payment data, and verifying additional transaction details. Refer to the reference tables to identify keys and values. Step 1: Verify the signature as follows: - Ensure that the certificates contain the correct custom OIDs: 1.2.840.113635.100.6.29 for the leaf certificate and 1.2.840.113635.100.6.2.14 for the intermediate CA. The value for these marker OIDs doesn’t matter, only their presence. - Ensure that the root CA is the Apple Root CA - G3. This certificate is available from `www.apple.com/certificateauthority`. - Ensure that there’s a valid X.509 chain of trust from the signature to the root CA. Specifically, ensure that the signature was created using the private key that corresponds to the leaf certificate, that the leaf certificate is signed by the intermediate CA, and that the intermediate CA is signed by the Apple Root CA - G3. - Validate the token’s signature. For ECC (EC_v1), ensure that the signature is a valid Ellyptical Curve Digital Signature Algorithm (ECDSA) signature (ecdsa-with-SHA256 1.2.840.10045.4.3.2) of the concatenated values of the `ephemeralPublicKey`, `data`, `transactionId`, and `applicationData` keys. For RSA (RSA_v1), ensure that the signature is a valid RSA signature (RSA-with-SHA256 1.2.840.113549.1.1.11) of the concatenated values of the `wrappedKey`, `data`, `transactionId`, and `applicationData` keys. - Inspect the Cryptographic Message Syntax (CMS) signing time of the signature, as defined by section 11.3 of RFC 5652. If the time signature and the transaction time differ by more than 5 minutes, the token may be a replay attack. > **important:** The signature is valid if all the signature verification steps above succeed. If the signature is invalid or any of the hash values don’t match, ignore the transaction. Step 2: Use the value of the `publicKeyHash` key to determine which merchant public key Apple used, and then retrieve the corresponding merchant public key certificate and private key. Step 3: Restore the symmetric key. For instructions, see [Restoring the symmetric key](../../passkit/restoring-the-symmetric-key.md). Step 4: Use the symmetric key to decrypt the value of the `data` key: - For ECC (EC_v1), decrypt the data key using AES–256 (id-aes256-GCM 2.16.840.1.101.3.4.1.46), with an initialization vector of 16 null bytes and no associated authentication data. - For RSA (RSA_v1), decrypt the data key using AES–128 (id-aes128-GCM 2.16.840.1.101.3.4.1.6), with an initialization vector of 16 null bytes and no associated authentication data. After you complete Step 4, the payment data in the `data` value of the payment token structure is decrypted. Use the decrypted payment data and information you have about the transaction to validate that transaction. Step 5: Confirm that you haven’t already credited this payment by verifying that no payment with the same `transactionId` shows as processed. For efficiency, consider only those payments with a transaction time that’s within the 5-minute time window of the current `transactionId`, as explained in the last bullet point of Step 1. Step 6: Verify the transaction details using information from the merchant about the Apple Pay payment request and other transaction information: - Check that the `currencyCode` matches the currency code in the original Apple Pay payment request. - Check that the `transactionAmount` is correct, as compared with the total charge of the transaction. - Check that the `applicationData` field matches the hash of the data the original payment request used, and that the data is correct. For example, check that an order number in the data from the original payment request is the order number to which you, the payment processor, are applying this payment. For more information, see [applicationData](../../passkit/pkpaymentrequest/applicationdata.md) in [PKPaymentRequest](../../passkit/pkpaymentrequest.md). For transactions that initiate in Apple Pay on the Web, see [applicationData](../../applepayontheweb/applepaypaymentrequest/applicationdata.md) in [ApplePayPaymentRequest](../../applepayontheweb/applepaypaymentrequest.md) and [applicationData](../../applepayontheweb/applepayrequest/applicationdata.md) in [ApplePayRequest](../../applepayontheweb/applepayrequest.md). Step 7: If the signature is valid, the hash values match, and your transaction validation passes, use the decrypted payment data to process the payment. Otherwise, ignore the transaction. ### Payment token format reference The following tables describe the keys and values of the payment token structure. #### Payment token structure The [paymentData](../../passkit/pkpaymenttoken/paymentdata.md) property of [PKPaymentToken](../../passkit/pkpaymenttoken.md) (or the [paymentData](../../applepayontheweb/applepaypaymenttoken/paymentdata.md) property of [ApplePayPaymentToken](../../applepayontheweb/applepaypaymenttoken.md), for Apple Pay on the Web) contains a UTF-8 serialization of a plaintext JSON dictionary with the following keys and values: | | | | | --- | --- | --- | | | | | | | | | | | | | | | | | #### Header keys and values The `header` contains the following keys and values: | | | | | --- | --- | --- | | | | | | | | | | | | | | | | | For more information about the application data and the original payment request, see [applicationData](../../passkit/pkpaymentrequest/applicationdata.md) and [PKPaymentRequest](../../passkit/pkpaymentrequest.md). For transactions using Apple Pay on the Web, see [applicationData](../../applepayontheweb/applepayrequest/applicationdata.md) and [ApplePayRequest](../../applepayontheweb/applepayrequest.md), and [applicationData](../../applepayontheweb/applepaypaymentrequest/applicationdata.md) and [ApplePayPaymentRequest](../../applepayontheweb/applepaypaymentrequest.md). #### Payment data keys The decrypted payment data in the `data` value contains the following keys and values: | | | | | --- | --- | --- | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | #### Detailed payment data keys (3D Secure) If the `paymentDataType` value is `"3DSecure"` in the Payment Data Keys information, the payment data dictionary in `paymentData` contains the following keys and values: | | | | | --- | --- | --- | | | | | | | | | #### Detailed payment data keys (EMV) If the `paymentDataType` value is `“EMV”` in the Payment Data Keys information, the payment data dictionary in `paymentData` contains the following keys and values: | | | | | --- | --- | --- | | | | | | | | | #### Authentication response The dictionary for the `authenticationResponses` in the Payment Data Keys information contains the following keys and values: | | | | | --- | --- | --- | | | | | | | | | | | | | ## Topics ### Symmetric keys - [Restoring the symmetric key](../../passkit/restoring-the-symmetric-key.md)