Skip to main content
Online Payments

Tokenization

Tokenization is the process of replacing sensitive card data with a unique identification token 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 minimizes impacts from potential data intrusion exposure.

J.P. Morgan currently offers a network tokenization solution for the following transactions:  

  • Recurring transactions
  • Card-on-file transactions
  • Subsequent transactions 

To better protect account numbers, we recommend storing tokens instead of primary account numbers (PANs) for cards-on-file used for recurring purchases or payments. You can create tokens using the following methods:

  • Network tokenization
  • Managed network tokenization
  • Safetech tokenization

Network tokenization

Network tokenization uses a token value assigned by a payment network. This allows you to use the existing token in the payment transactions without de-tokenizing it prior to payment processing. This same token is then used in any subsequent actions related to the initial payment, including clearing, settlement, refunds, and dispute processing.

Network tokens (NWTs) are secured using a cryptogram and given 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 in 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 Customer-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 Electronice 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:

Cryptogam 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 /refunds
Scenario: 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": "MERCHANT",
    "accountOnFile": "TO_BE_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"
                }
            }
        }
    }
}

Managed network tokenization

Managed network tokenization is an optional service that converts PANs to payment network NWTs, and re-tokenizes wallet tokens, browser tokens, and third-party NWTs into managed network tokens. This service requires minimal changes to your integration and additional fields are provided in the response to indicate the processing status. To enroll in the managed network tokenization service, contact your relationship manager.

A few things to keep in mind:

  • For Visa (VI), along with PANs, wallet tokens, browser token, and third-party NWT are converted into a managed network tokens.
  • For Mastercard (MC), only Paze wallet tokens are supported for a card on file token request. You must provide the following in your payment request:
    • tokenProvisioningVerificationValue in the paymentMethodType.card.authentication object.
    • In the paze.encryptedPaymentBundle object, you must provide an encryptedPayload that has the transaction type set as Purchase and Card-on-file.
  • You must be enrolled with VI/MC to obtain network tokens.
  • Apple Pay tokens are not re-tokenized.
Tip

To ensure optimized token provisioning and successful tokenized authorization, your managed network token requests to the Online Payments API must also include stored payments and recurring payments data field requirements. The sample request below shows an example of a cardholder initiated, stored payment scenario. You can use the sample payload message to generate a similar request for merchant initiated, recurring payment transactions.

HTTP method: POST

Endpoint: /payments

The following is a sample managed network tokenization request to receive a network token using the managed network tokenization service:

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": "NETWORK",
                    "tokenNumber": "xxxxxxxxxxxx1002",
                    "responseStatus": "SUCCESS",
                    "tokenServiceResponseCode": "TOKEN_PROCESSING"
                }
            ]
        }
    }
}

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, J.P. Morgan replaces 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"
        }
    }
}