Decrypted digital wallets allow you to view the card data before submitting the transaction. This option gives you full control of your payment journey. For example, you can block specific cards or make informed decisions for subsequent payment actions.
First, let’s explain a few terms related to this feature.
- Funding Primary Account Number (FPAN) — The identifiable cardholder’s card number on the front of a physical credit or debit card.
- Device Primary Account Number (DPAN) — A device-specific token from the wallet provider to identify the underlying card that is associated with a cardholder’s FPAN.
We also support the ability to make payments using Apple Pay or Google Pay tokens that you have decrypted. To use this feature, use the CARD_TOKEN source type and specify the provider type as APPLEPAY or PAY_BY_GOOGLE. With this, you'll be able to provide the DPAN, expiry, and authentication information to make a payment.
Apple Pay / Google Pay processes
To decrypt the payload, each mobile wallet provider requires you to follow its process. For example, Apple Pay requires you to generate your public/private key pair and your Certificate Signing Request (CSR) to upload to the Apple Pay developer website. You can find the details on their respective developer sites:
Step 1: Decrypt and map the request
Once you've successfully decrypted the payload, you'll have the raw message content. Use this table to map the mobile wallet provider's fields to the API request.
| 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 | N/A | |
| onlinePaymentCryptogram | cryptogram | |
| eciIndicator | eci |
Step 2: Process request
Change the Provider field to the appropriate wallet provider: APPLEPAY or PAY_BY_GOOGLE. If the response from Apple or Google does not include the cryptogram and Electronic Commerce Indicator (ECI), these can be removed. However, 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.
{
"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"
}
}
}PAN - Google Pay Web - ECI and cryptogram
In the scenario where a FPAN is provided for Google Pay, you should specify the token_format as CARD_NUMBER rather than CARD_TOKEN. The use case for this is when “Google Pay on the Web” is used and the customer doesn’t have Google Pay on their mobile device to provide a DPAN rather than FPAN. Note that in the case of CARD_NUMBER transactions, we process these transactions as regular card transactions for which 3D Secure applies as well.
{
"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"
}
}
}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. You can then store the returned brand_reference value for all subsequent MIT transactions.
You’ll need to comply with the stored credential mandate of card brands like Visa or Mastercard. For more information, see our Credential on File article.
Apple Pay supports specific merchant tokens for repeat payments. For more information, see their Apple Merchant Token Guide.
The following table shows the corresponding API field for each wallet provider field.
| 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 | N/A | |
| Model | model |
recurring - Payment with no fixed duration that continues until the customer cancels. |
| Initiator | initiator | Set to merchant for MIT transactions. |
| Sequence | sequence | Set to subsequent for MIT transactions. |
| Brand Reference | brand_reference |
Also referred to as Scheme Reference Data (SRD). Unique identifier provided by a card brand like Visa or Mastercard that links to the payment history between the customer and merchant. Also referred to as Transaction ID or Trace ID, depending on the card brand. This will appear in the response message of an initial transaction. |