For AI agents: the complete documentation index is at /llms.txt, and the full text of every page is at /llms-full.txt. Most pages are also available as Markdown by adding .md to the URL.

Decrypted Digital Wallets

Set up payload decryption to preview card data

Decrypted digital wallets allow you to view the card data before submitting the transaction. This option gives full control of your payment journey. For example, you can block specific cards or make informed decisions for subsequent payment actions.

PCI Compliance Notice: Decrypted wallet data — including the Device Primary Account Number (DPAN), expiration date, and cryptogram — must be treated as sensitive cardholder data under PCI DSS. Ensure your system is compliant before handling decrypted values.

For official requirements, see:

Key definitions

FPAN (Funding Primary Account Number): The actual card number printed on a physical card.
DPAN (Device Primary Account Number): A tokenized card number issued by a wallet provider, representing the FPAN and used in transactions.

Supported tokens

Use the TOKENIZED_CARD source type when processing decrypted tokens from Apple Pay or Google Pay. Set the provider field to apple-pay or pay-with-google, and provide the DPAN, expiration, and cryptographic values.

Decryption requirements

Each wallet provider has distinct setup steps:

Apple Pay: Upload a CSR and public key to the Apple Pay developer portal. Apple Pay Token Format
Google Pay: Follow Google’s encryption/decryption guide. Google Pay Cryptography Guide

Step 1: Decrypt and map fields

Example of a decrypted wallet payload

{
  "applicationPrimaryAccountNumber": "4895370012003478",
  "applicationExpirationDate": "1226",
  "currencyCode": "840",
  "transactionAmount": "1999",
  "cardholderName": "James Mason",
  "onlinePaymentCryptogram": "Af9x83xkzKJ3Jidv4xj2AwAAABk=",
  "eciIndicator": "5"
}

Important: Only DPANs are returned, along with accompanying transaction fields. FPANs are never returned in decrypted wallets.

You’ll typically receive:

applicationPrimaryAccountNumber (DPAN)
applicationExpirationDate (MMYY)
onlinePaymentCryptogram
eciIndicator
currencyCode, transactionAmount
cardholderName (optional, often not included)

Required fields:

DPAN
Expiry
Currency
Amount
Cryptogram (recommended)
ECI (recommended)

Wallet Field	API Field	Notes
`applicationPrimaryAccountNumber`	`token`	Use DPAN here.
`currencyCode`	`currency`	ISO 4217 format
`applicationExpirationDate`	`expiry`	Format MMYY
`transactionAmount`	`amount`
`cardholderName`	`name`	Optional
`onlinePaymentCryptogram`	`cryptogram`
`eciIndicator`	`eci`

Step 2: Process request

Change the item type field to the appropriate wallet provider: apple-pay or pay-with-google. If the response does not include the cryptogram and Electronic Commerce Indicator (ECI), these can be removed and sent without the values. However we strongly advise against that as the two values are typically expected for the best acceptance rates.

DPAN - Including ECI and cryptogram

In this scenario, the customer’s DPAN is used, along with the ECI and cryptogram.

Sample request

{
  "account_name": "Transaction_Processing",
  "type": "SALE",
  "channel": "CNP",
  "capture_mode": "AUTO",
  "amount": "1999",
  "currency": "USD",
  "reference": "93459c78-f3f9-427c-84df-ca0584bb55bf",
  "country": "US",
  "payment_method": {
    "name": "James Mason",
    "entry_mode": "ECOM",
    "digital_wallet": {
      "token": "5167300431085507",
      "token_format": "CARD_TOKEN",
      "expiry_month": "12",
      "expiry_year": "20",
      "cryptogram": "234234234",
      "provider": "APPLEPAY OR PAY_BY_GOOGLE",
      "eci": "5"
    }
  }
}

FPAN - Google Pay web flows

Some Google Pay web flows return CARD_NUMBER — the FPAN — instead of a token (DPAN). These transactions:

Are not decrypted wallet transactions
Require full PCI DSS compliance
Must use 3D Secure if applicable

Use this only when the customer selects a saved card that isn’t tokenized.

Sample request (for information only)

{
  "account_name": "Transaction_Processing",
  "type": "SALE",
  "channel": "CNP",
  "capture_mode": "AUTO",
  "amount": "1999",
  "currency": "USD",
  "reference": "93459c78-f3f9-427c-84df-ca0584bb55bf",
  "country": "US",
  "payment_method": {
    "name": "James Mason",
    "entry_mode": "ECOM",
    "digital_wallet": {
      "token": "5167300431085507",
      "token_format": "CARD_NUMBER",
      "expiry_month": "12",
      "expiry_year": "20",
      "cryptogram": "234234234",
      "provider": "PAY_BY_GOOGLE",
      "eci": "5"
    }
  }
}

Sample response

{
    "id": "TRN_noXZxzpagCCMyJT08Sz2tGkPji8WXN",
    "time_created": "2021-03-20T13:44:14.327Z",
    "type": "SALE",
    "status": "CAPTURED",                      
    "channel": "CP",
    "capture_mode": "AUTO",
    "amount": "20045",
    "currency": "CAD",
    "merchant_id": "MER_8096479c606f4deb93dfab49e7bfea28",
    "merchant_name": "SANDBOX_MERCHANT",
    "account_id": "TRA_0b1fcc7cceea48dea38d044bae4295c2",
    "account_name": "Termiinal_55",
    "reference": "03559571",
    "payment_method": {
        "result": "00",                                 
        "message": "APPROVAL",                  
        "entry_mode": "MANUAL",
        "card": {
            "brand": "VISA",
            "masked_number_last4": "XXXXXXXXXXXX4242",
            "authcode": "351404",
            "brand_reference": "772201652998701",
            "tag_response": "",
            "cvv_result": "MATCHED",
            "avs_address_result": "0",
            "avs_postal_code_result": "0",
            "avs_action": ""
        }
    },
    "batch_id": "BAT_353445",
    "action": {
        "id": "ACT_noXZxzpagCCMyJT08Sz2tGkPji8WXN",
        "type": "AUTHORIZE",
        "time_created": "2021-03-20T13:44:14.327Z",
        "result_code": "SUCCESS",               
        "app_id": "APP_MN500Q8lk5jp0rEmB5LGvTo27gdQgZln",
        "app_name": "my_sandbox_app"
    }
}

Repeat MIT payments

With a decrypted setup, you can process repeat Merchant-Initiated Transactions (MITs) for both Google Pay and Apple Pay. Repeat MITs include the following payment types:

Recurring
Installment
Unscheduled

To process a recurring payment, the first payment must originate from a successful customer-initiated transaction. Only the brand_reference from the initial transaction may be stored. Do not retain decrypted fields like DPAN, ECI, or cryptogram.

Recurring payments for Apple Pay will require use of Merchant Tokens (MPANs). For more information, see their Apple Merchant Token Guide.

You’ll need to comply with the stored credential mandate of card brands like Visa or Mastercard. For more information, see our Recurring Payments - Credential on File guide.

Wallet Provider Field	Our API Field	Notes
`applicationPrimaryAccountNumber`	`token`
`currencyCode`	`currency`	3 digit ISO 4217 code, i.e., “GBP”
`applicationExpirationDate`	`expiry_month` & `expiry_year`
`transactionAmount`	`amount`
`cardholderName`	Not applicable
`Model`	`model`	`recurring`: Use for payments with no fixed duration that continues until the customer cancels. `installment`: Use for payments of an agreed amount on the same day each month until the fixed duration ends. `oneoff`: Use for unscheduled payments with no fixed duration.
`Initiator`	`initiator`	Set to `merchant` for MIT transactions.
`Sequence`	`sequence`	Set to `subsequent` for MIT transactions.

Policies

Connect

Additional Resources