Online Payments

Tokenization

Tokenization is the process of replacing sensitive card data with a unique value that retains all the essential information without compromising security. This minimizes the amount of card data you need to keep on hand, significantly reduces your Payment Card Industry (PCI) compliance scope, and reduces exposure in the event of a data intrusion.

Network tokens are created and detokenized by the payment network (for example, Visa, Mastercard, American Express, and Discover). When account changes such as expiration date and PAN updates occur, issuers may elect to provide these changes to the payment network to apply to the network token. The value of the network token will remain the same, while the network will adjust the mapping to point to the new credential.

Tokenization process flow for network tokens

J.P. Morgan tokens include Safetech tokens and Consumer Profiles, and are detokenized prior to being sent to the payment network. These tokens provide the value of removing the credential from Payment Card Industry Data Security Standards (PCI DSS) Compliance scope.

Tokenization process flow for J.P. Morgan tokens

J.P. Morgan Online Payments API supports many forms of tokenization, as shown in the following table:

Supported types of tokenization
Token category	Token type	How does it work	Supported use cases
Network tokens	Client-Managed Card-on-File Network Tokens	Merchant sends a network token and cryptogram (if required for use case) to the Online Payments API. Tokens can be obtained from: J.P. Morgan Client-Managed Network Tokens Direct integrations with the payment networks Third-party network token service providers	Cardholder-initiated stored transactions, for example cardholder previously agreed to store their card on file and that card is used for subsequent orders. Merchant-initiated transactions, for example recurring billing. For more information, refer to Cardholder vs merchant-initiated transactions.
	J.P. Morgan-Managed Card-on-File Network Tokens	Clients continue to process with a PAN, Safetech token, or consumer profile and we provision tokens in the background. During the authorization flow, we fetch the network token and use it for the authorization, increasing authorization rates and potentially reducing interchange rates.
	Unbundled wallet tokens	Merchant unbundles an encrypted digital wallet token received during a transaction with the wallet provider, e.g. Apple Pay	In-app wallet transaction in which cardholder authenticated on their mobile phone or other device. Subsequent merchant-initiated transactions, e.g. reauthorization when original authorization expires.
	Bundled wallet tokens	Encrypted bundle is sent directly to the Online Payments API. We decrypt it using decryption keys previously provided by the merchant.
J.P. Morgan tokens	Consumer profiles	When you create a consumer profile, we generate a unique profile ID and payment method ID for future transactions. Please see detailed instructions for creating and using consumer profiles.	Cardholder-initiated stored transactions, e.g. cardholder previously agreed to store their card on file and that card is used for subsequent orders. Merchant-initiated transactions, e.g. recurring billing. For more information, refer to Cardholder vs merchant-initiated transactions.
J.P. Morgan tokens	Safetech tokens	The PAN is replaced with a token value, which can maintain the same BIN and last 4 digits as the actual card. Merchants must store the expiry date.

Client-managed card-on-file network token and unbundled wallet transactions

This section applies to:

Client-managed network token transactions in which a merchant already has a network token and a cryptogram or ability to obtain a cryptogram.
An unencrypted wallet token and cryptogram.

Network tokens (NWTs) are secured using a cryptogram and are issued with a unique value obtained from the networks prior to each transaction. This value is used by the network to match the cryptogram generated for the authenticated token requester to the cryptogram being sent for transaction processing. For merchant-initiated transactions such as recurring payments, NWT transactions can be submitted without a cryptogram, as long as the fields referenced on the recurring payment are used correctly.

Tip

For additional information regarding token provisioning, as well as requesting and using cryptograms, refer to the Tokenization API.

Because NWTs are issued by the payment network, you can use them with any payment provider as long as the cryptogram and other required fields are used correctly.

Cryptogram

Network token transactions with the initiatorType = CARDHOLDER require a cryptogram. When submitting a cardholder-initiated transaction (CIT) with a NWT:

Use the accountNumber field for the token value, and expiry.month and expiry.year fields for token expiry month and year respectively.
Send the Electronic Commerce Indicator (ECI) value in the electronicCommerceIndicator field.
- If your service provider did not provide an ECI, you must set the electronicCommerceIndicator field value to 7 for Visa, and 5 for Mastercard NWTs.

Note

When the initiatorType = MERCHANT, a network token transaction does not require a cryptogram. Instead, provide the network transaction ID from the original cardholder-initiated transaction (CIT) in the originalNetworkTransactionId field.
For Mastercard, a cryptogram is required for the first token transaction, even if it is merchant-initiated transaction (MIT). (originalNetworkTransactionId is still required for MIT)
- For example, if the first transaction was a CIT on PAN and then you got a token prior to the MIT, then the first usage of the token on the MIT would require a cryptogram.

The following table shows the fields you must populate based on the type of cryptogram you receive:

Cryptogram scenarios for NWT
Scenario	Requirement	Comments
If the cryptogram is greater than 4 characters (long cryptogram)	You must send the cryptogram in the `tokenAuthenticationValue` field.	Examples of long cryptograms: Token Authentication Verification Value (TAVV) Universal Cardholder Authentication Field (UCAF)
If the cryptogram is less than 5 characters (short cryptogram)	You must send the value in either the `paymentMethodType.card.cvv` or `tokenAuthenticationValue` field	The cryptogram is intended to be passed to the payment networks in the `cvv` field. If you submit it in the `tokenAuthenticationValue` field, we will identify it as a short cryptogram and pass it to the payment networks in the appropriate fields. Examples of short cryptograms: Discover Card Identification Number (DCID) Dynamic Card Security Code (DCSC) Dynamic Token Verification Code (DTVC) Dynamic Token Verification Value (DTVV)
If you have both a short cryptogram and the actual cvv value	You must send only the cryptogram value in either the `cvv` or `tokenAuthenticationValue` field.	We will drop the cvv value and only pass the short cryptogram to the payment networks. As a result, you will not receive a match response for the cvv value submitted.

HTTP method: POST
Endpoints: /payments, /verifications, and /refundsScenario: Sending a network token transaction with a cryptogram for Visa.

The following is a sample request using a network token:

Json

{
    "captureMethod": "NOW",
    "amount": 10000,
    "currency": "USD",
    "isAmountFinal": true,
    "initiatorType": "CARDHOLDER",
    "accountOnFile": "STORED",
    "paymentMethodType": {
        "card": {
            "accountNumber": "4112344112344113",
            "expiry": {
                "month": 12,
                "year": 2027
            },
            "authentication": {
                "electronicCommerceIndicator": "7",
                "tokenAuthenticationValue": "AAABAIcJIo7DIzAgVAkiAAAAAAA="
            }
        }
    },
    "merchant": {
        "merchantSoftware": {
            "companyName": "J.P. Morgan Chase",
            "productName": "Helix Connect",
            "version": "1.0"
        }
    }
}

Response:

Json

{
    "transactionId": "3fa2aa4d-7a93-48ec-b5b9-3f03300a2d17",
    "requestId": "793b2a2b-7577-4efa-8b73-ccb46623e521",
    "transactionState": "CLOSED",
    "responseStatus": "SUCCESS",
    "responseCode": "APPROVED",
    "responseMessage": "Transaction approved by Issuer",
    "paymentMethodType": {
        "card": {
            "cardType": "VI",
            "cardTypeName": "VISA",
            "maskedAccountNumber": "411234XXXXXX4113",
            "networkResponse": {
                "addressVerificationResult": "NOT_REQUESTED",
                "paymentAccountReference": "Q1J4Z28RKA1EBL470G9XYG90R5D3E",
                "networkResponseCode": "00"
            },
            "authentication": {
                "electronicCommerceIndicator": "7",
                "authenticationValueResponse": {
                    "code": "2",
                    "message": "CAVV passed verification—authentication"
                }
            }
        }
    }
}

Payment Account Reference (PAR)

The Payment Account Reference (PAR) is an identifier created by the payment networks to map the underlying cardholder account across all associated tokens and PAN.

It lets you de-duplicate multiple tokens (for example, Apple Pay token, stored credential, re-issued card) to a single consumer.
You receive it in the payments response and store it for reconciliation, loyalty, or fraud purposes. It is never sent as a payment credential and has no functional use outside of providing account transparency to merchants.
We provide PAR in the payment response whenever we receive it from the networks in the paymentMethodType.card.networkResponse.paymentAccountReference field.

Cardholder-initiated network token transactions

The rules governing network token transactions are different depending on whether a transaction was initiated by the cardholder or a merchant. Cardholder-initiated transactions must contain a cryptogram, while merchant-initiated transactions must reference a previous cardholder-initiated transaction.

A transaction is generally considered cardholder-initiated when the cardholder played an active role in creating the transaction. Examples include entering their card info to sign up for a service or using a previously stored card to initiate a purchase.

Key request fields:

Key request fields for CIT
Field name	Value to be sent
`accountOnFile`	`TO_BE_STORED` - If the cardholder is storing their card for the first time. `STORED` - If it is already on file.
`paymentMethodType.card.accountNumber`	The network token value.
`paymentMethodType.card.expiry`	The network token expiry.
`paymentMethodType.card.authentication.electronicCommerceIndicator`	The Electronic Commerce Indicator (ECI) that you received from your token service provider.
`paymentMethodType.card.authentication.tokenAuthenticationValue`	The cryptogram.

Key response field:

Key response fields for CIT
Field name	Action to perform
`paymentMethodType.card.networkResponse.networkTransactionId`	Store this value. This is required for subsequent merchant-initiated transactions (MIT) with the token or PAN.

The following sample code block shows the token-specific fields that are required for transactions with initiatorType = CARDHOLDER. For the list of fields for various CIT & MIT use cases, refer to Cardholder vs merchant-initiated transactions - field details.

HTTP method: POSTEndpoint: /payments

Json

{
    "captureMethod": "NOW",
    "amount": 10000,
    "currency": "USD",
    "initiatorType": "CARDHOLDER",
    "accountOnFile": "TO_BE_STORED",
    "merchant": {
        "merchantSoftware": {
            "companyName": "Payment Company",
            "productName": "Application Name"
        },
        "merchantCategoryCode": "4899"
    },
    "paymentMethodType": {
        "card": {
            "accountNumber": "4761220000000237",
            "expiry": {
                "month": 12,
                "year": 2027
            },
            "authentication": {
                "electronicCommerceIndicator": "07",
                "tokenAuthenticationValue": "AAABAIcJIo7DIzAgVAkiAAAAAAA="
            }
        }
}

Subsequent merchant-initiated transactions

A transaction is considered merchant-initiated when the transaction is automated by the merchant based on a previous agreement with the cardholder. Examples include subscription payments and delayed charges from a hotel for minibar items.

Merchant-initiated transactions don't require a cryptogram when using a card-on-file network token or a wallet token.

Attention

You must include a cryptogram on the first subsequent Mastercard transaction on a card-on-file token when all earlier transactions were processed on the PAN.

Key request fields:

Key request fields for MIT
Field name	Value to be sent
`initiatorType`	Set to `MERCHANT`
`paymentMethodType.card.accountNumber`	The network token value.
`paymentMethodType.card.expiry`	The network token expiry.
`paymentMethodType.card.originalNetworkTransactionId`	Populated with the `networkTransactionId` from the initial cardholder-initiated transaction (CIT).

The following sample code block shows the token-specific fields that are required for transactions with initiatorType = MERCHANT. For the list of fields for various CIT and MIT use cases, refer to Cardholder vs merchant-initiated transactions - field details.

HTTP method: POSTEndpoint: /payments

Json

{
    "captureMethod": "NOW",
    "amount": 10000,
    "currency": "USD",
    "initiatorType": "MERCHANT",
    "accountOnFile": "STORED",
    "merchant": {
        "merchantSoftware": {
            "companyName": "Payment Company",
            "productName": "Application Name"
        },
        "merchantCategoryCode": "4899"
    },
    "paymentMethodType": {
        "card": {
            "accountNumber": "4012000033330026",
            "originalNetworkTransactionId": "012125692162451",
            "expiry": {
                "month": 10,
                "year": 2040
            }
        }
    },
    "recurring": {
        "recurringSequence": "SUBSEQUENT"
    }
}

Managed Card-on-File network tokens

When you use the managed network token service, we obtain a cryptogram on your behalf. You only need to use the credentials you have, which could be PAN, Safetech tokens, or Consumer Profiles, and we will map it to a network token. Fields in the response will indicate whether or not there was a token used. We provision the token asynchronously the first time you use a credential, so you won’t realize the benefit of network tokens until the second transaction.

Tip

To ensure optimized token provisioning and successful tokenized authorization, submit transactions as described on the CIT & MIT stored credentials page.

Initial cardholder-initiated transaction

To send an initial cardholder-initiated transaction, follow the guidance provided on Cardholder vs merchant-initiated transactions.

Key response fields:

Key response fields for CIT
Field name	Description
`card.paymentTokens.tokenProvider`	Contains the value `NETWORK` or `SAFETECH`, with `NETWORK` indicating that the token in `tokenNumber` field is a network token.
`card.paymentTokens.tokenNumber`	The actual token number.
`card.paymentTokens.responseStatus`	Indicates whether or not the token vault interaction was successful.
`card.paymentTokens.tokenServiceResponseCode`	The possible values returned are: `TOKEN_CRYPTO_PROCESSING` – Token was processed with a cryptogram. `TOKEN_PROCESSING` – Token was processed without a cryptogram. `PAN_PROCESSING` – Transaction was processed on PAN, due to the token not being provisioned yet or the authorization request on the token was declined.

The following code block is a sample response of the paymentTokens object from initial cardholder-initiated transaction:

Json

{...
  "paymentTokens": [
     {
       "tokenProvider": "NETWORK",
       "tokenNumber": "xxxxxxxxxxxx1002",
       "responseStatus": "SUCCESS",
       "tokenServiceResponseCode": "TOKEN_PROCESSING"
     }
  ...
  ]
}

Visa Digital Commerce Authentication Program (DCAP)

Visa DCAP is a global program that helps in mitigating fraud and improving authorization approval rates without adding friction to the payment experience. This promotes effective data sharing between merchants and issuers, while minimizing friction to the cardholder checkout experience.

Additional information is provided while obtaining the cryptogram. Since the Managed Tokenization service obtains the cryptogram for you, you must send this information in the payments request if you want to benefit from DCAP rates.

The following table shows the minimum requirements to qualify for Visa DCAP based on your region:

Visa DCAP minimum requirements
Data element	CA, AP, CEMEA, LAC	EU	US
Device ID	Yes	Optional for domestic and intra-European Economic Area (EEA) transactions. Mandatory for inter-regional and intra non-EEA transactions.	Yes
IP address	Yes	Yes	Yes
Email or phone number	Yes (either one or both)	Yes (either one or both)	Yes (email only)
Billing address	Optional	Optional	Yes

Attention

Visa reserves the right to exclude merchants from DCAP if they repeatedly fail to comply with enhanced risk data sharing standards over a number of consecutive months.

The following table shows the required fields you must send in your payment request to qualify for Visa DCAP:

Visa DCAP required fields
Field name	Description	Comments
accountHolder.`digitalDeviceIdentifier`	Unique identifier for the account holder’s device, either hardware-based or a derived device fingerprint.
accountHolder.`IPAddress`	IP Address from where the transaction is originating.
accountHolder.`email`	Email address of the account holder.	Required for US. Non-US countries can provide either email, phone number, or both.
accountHolder.`phone.phoneNumber`	Phone number of the account holder in ITU-T E.164 format.	Non-US countries can provide either email, phone number, or both.
accountHolder.`billingAddress.line1`	First line of the account holder's street address.
accountHolder.`billingAddress.city`	Name of account holder's municipality.
accountHolder.`billingAddress.state`	Name of account holder's state or province.
accountHolder.`billingAddress.postalCode`	The encoded representation of the account holder's geographic area to facilitate mail delivery services.

Note

If the transaction qualifies for Visa DCAP, the payment response will contain the field paymentMethodType.card.networkResponse.additionalData.vdcapCode with a value of 1.

Bundled wallet token transactions

We provide the service of accepting an encrypted bundle as a paymentMethod for Google Pay, Apple Pay, and Paze. If you unencrypt the credentials yourself, refer to Client-Managed Card-on-File Network Token and unencrypted Wallet transactions.

For more information on wallet services, refer to:

J.P. Morgan token transactions

J.P. Morgan offers two types of tokens:

Safetech tokens – Our simplest option where the underlying card account is mapped to a J.P. Morgan-created token, which you use to process transactions. You must continue to send the expiration date of the underlying PAN.
Consumer profiles – Create, store, update, and maintain consumer profiles, including payment card information. Comply with payment card industry data security standards and simplify the payment process for returning consumers and recurring transactions. For more information on consumer profiles, refer to Consumer profile management.

Safetech tokenization

Safetech tokenization is an optional service that converts PAN and bank account information (such as account and routing numbers) to J.P. Morgan-issued acquirer tokens. These tokens are safely stored in your system instead of the full PAN or bank account information.

When a Safetech token is used within a transaction, we replace the token with the account number for authorization. The response contains the Safetech token and masked account number. To enroll in the Safetech tokenization service, contact your relationship manager.

HTTP method: POST
Endpoints: /payments, /verifications, /refunds, and /fraudcheck

The following payment example requests a Safetech token:

Json

{
    "amount": 1234,
    "currency": "USD",
    "initiatorType": "CARDHOLDER",
    "accountOnFile": "TO_BE_STORED",
    "merchant": {
        "merchantSoftware": {
            "companyName": "Shipping UAT",
            "productName": "Application Name",
            "version": 1.235
        },
        "merchantCategoryCode": 4899
    },
    "paymentMethodType": {
        "card": {
            "accountNumber": 4112344112344113,
            "expiry": {
                "month": 5,
                "year": 2022
            }
        }
    }
}

Response:

Json

{
    "transactionId": "4751d11a-c194-4f7e-a433-774fa4ff36ef",
    "requestId": "7bda0564-a5f6-4b4a-91f3-f71f92955a32",
    "transactionState": "CLOSED",
    "responseStatus": "SUCCESS",
    "responseCode": "APPROVED",
    "responseMessage": "Transaction approved by Issuer",
    "paymentMethodType": {
        "card": {
            "cardType": "VI",
            "cardTypeName": "VISA",
            "maskedAccountNumber": "411234XXXXXX4113",
            "networkResponse": {
                "addressVerificationResult": "NOT_REQUESTED",
                "networkTransactionId": "013291692163387",
                "paymentAccountReference": "Q1J4Z28RKA1EBL470G9XYG90R5D3E",
                "networkResponseCode": "00"
            },
            "paymentTokens": [
                {
                    "tokenProvider": "SAFETECH",
                    "tokenNumber": "4112340803104113",
                    "responseStatus": "SUCCESS"
                }
            ]
        }
    }
}

The following payment example uses a Safetech token:

Json

{
    "amount": 1234,
    "currency": "USD",
    "initiatorType": "CARDHOLDER",
    "accountOnFile": "TO_BE_STORED",
    "merchant": {
        "merchantSoftware": {
            "companyName": "Shipping UAT",
            "productName": "Application Name",
            "version": 1.235
        },
        "merchantCategoryCode": 4899
    },
    "paymentMethodType": {
        "card": {
            "accountNumberType": "SAFETECH_TOKEN",
            "accountNumber": 4112340803104113,
            "expiry": {
                "month": 5,
                "year": 2022
            }
        }
    }
}

Response:

Json

{
    "transactionId": "f9b9a1ec-8842-4a07-952f-21dad4364183",
    "requestId": "274ab31c-55c7-4388-a65c-83c82b20e949",
    "transactionState": "CLOSED",
    "responseStatus": "SUCCESS",
    "responseCode": "APPROVED",
    "responseMessage": "Transaction approved by Issuer",
    "paymentMethodType": {
        "card": {
            "accountNumberType": "SAFETECH_TOKEN",
            "cardType": "VI",
            "cardTypeName": "VISA",
            "maskedAccountNumber": "411234XXXXXX4113",
            "networkResponse": {
                "addressVerificationResult": "NOT_REQUESTED",
                "networkTransactionId": "013291692160631",
                "paymentAccountReference": "Q1J4Z28RKA1EBL470G9XYG90R5D3E",
                "networkResponseCode": "00"
            }
        }
    }
}

The following payment example requests a Safetech token for the bank account payment method ACH:

Json

{
    "paymentMethodType": {
        "ach": {
            "accountNumber": "12345678925",
            "financialInstitutionRoutingNumber": "123456789",
            "paymentType": "WEB",
            "accountType": "SAVING"
        }
    }
}

Response:

Json

{
    "transactionId": "da289e65-3bb2-47c3-ba89-d0545a084b16",
    "requestId": "d0630cbe-3bb4-4448-8406-f0f266d2ec5f",
    "transactionState": "CLOSED",
    "responseStatus": "SUCCESS",
    "responseCode": "ACCEPTED",
    "responseMessage": "Request successfully completed",
    "paymentMethodType": {
        "ach": {
            "financialInstitutionRoutingNumber": "123456789",
            "paymentType": "WEB",
            "accountType": "SAVING",
            "maskedAccountNumber": "XXXXXXX8925",
            "ecpProgramName": "STD",
            "paymentTokens": [
                {
                    "tokenNumber": "BTKNSTDPRIUP9PHTQKA",
                    "responseStatus": "SUCCESS",
                    "tokenServiceResponseCode": "ACCEPTED"
                }
            ]
        }
    }
}

The following payment example uses a Safetech token as the account number in the bank account payment method ACH:

Json

{
    "paymentMethodType": {
        "ach": {
            "accountNumber": "BTKNSTDPRIUP9PHTQKA",
            "paymentType": "WEB",
            "accountType": "SAVING"
        }
    }
}

Response:

Json

{
    "transactionId": "f2ae4dd2-ded8-424f-a910-f3d34bb6b936",
    "requestId": "0a327188-f385-41ea-b4b9-5c6545ea5a7a",
    "transactionState": "CLOSED",
    "responseStatus": "SUCCESS",
    "responseCode": "ACCEPTED",
    "responseMessage": "Request successfully completed",
    "paymentMethodType": {
        "ach": {
            "financialInstitutionRoutingNumber": "123456789",
            "paymentType": "WEB",
            "accountType": "SAVING",
            "maskedAccountNumber": "XXXXXXX8925",
            "ecpProgramName": "STD"
        }
    }
}

Safetech token format

You can tokenize MOD 10 (Luhn) and non-MOD 10 account numbers as a standalone request or as part of a transaction using Safetech Secure Stateless Tokenization (SST2) formats. Contact your account representative or relationship manager to set up this feature.

A few things to keep in mind.

The token format is set as transaction division by default during a one-time setup.
- It cannot be changed dynamically in the transaction message.
- If you wish to change it, contact your account representative or relationship manager.
MOD 10 shows the computed check digit value using Luhn algorithm.

The following table shows what the SST2 formats mean:

SST2 format meaning
SST2 format	Description
NI	Numeric, Ignore
NP	Numeric, Preserve
NC	Numeric, Change
AI	Alphanumeric, Ignore

The following table lists the various SST2 tokenization formats, along with examples:

SST2 Token formats
PAN digits to preserve	Alpha token indicator	MOD 10 checksum	SST2 format	Example token
First 6 and Last 4	None	Ignore MOD 10	NI64	5454541002111234
First 6	None	Ignore MOD 10	NI60	5454541002112001
Last 4	None	Ignore MOD 10	NI04	1806551002111234
None	None	Ignore MOD 10	NI00	1806551002112001
First 6 and Last 4	None	Preserve MOD 10	NP64	545454******1234
First 6	None	Preserve MOD 10	NP60	545454******2001
Last 4	None	Preserve MOD 10	NP04	1806551001011234
None	None	Preserve MOD 10	NP00	1806551004312001
First 6 and Last 4	None	Change MOD 10	NC64	545454******1234
First 6	None	Change MOD 10	NC60	545454******2001
Last 4	None	Change MOD 10	NC04	1806551002671234
None	None	Change MOD 10	NC00	1806551008782001
First 6 and Last 4	Alpha Token	Ignore MOD 10	AI64	5454541wrtp11234
First 6	Alpha Token	Ignore MOD 10	AI60	5454541wrtp12001
Last 4	Alpha Token	Ignore MOD 10	AI04	1806551wrtp11234
None	Alpha Token	Ignore MOD 10	AI00	1806551wrtp12001

Cardholder vs Merchant-initiated transactions
Online Payments API
Real-time account updater
Recurring payments
Stored Payments
Tokenization API

Tokenization

Client-managed card-on-file network token and unbundled wallet transactions

Cryptogram

Payment Account Reference (PAR)

Cardholder-initiated network token transactions

Subsequent merchant-initiated transactions

Managed Card-on-File network tokens

Initial cardholder-initiated transaction

Visa Digital Commerce Authentication Program (DCAP)

Bundled wallet token transactions

J.P. Morgan token transactions

Safetech tokenization

Safetech token format

Related