# JPMC-PDP Documentation from https://developer.payments.jpmorgan.com # 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](/docs/commerce/online-payments/capabilities/online-payments/payment-enhancements/recurring-payments) are used correctly. > For additional information regarding token provisioning, as well as requesting and using cryptograms, refer to the [Tokenization API](/docs/commerce/optimization-protection/capabilities/tokenization/index). > 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. > > - 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": "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" } } } } } ``` ## 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. - Use the [Wallet Decryption API](/docs/commerce/optimization-protection/capabilities/wallet-decryption/how-to/decrypt-paze) to get the tokenProvisioningVerificationValue. - 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. > To ensure optimized token provisioning and successful tokenized authorization, your managed network token requests to the [Online Payments API](/docs/commerce/online-payments/index) must also include [stored payments](/docs/commerce/online-payments/capabilities/online-payments/payment-enhancements/stored-payments) and [recurring payments](/docs/commerce/online-payments/capabilities/online-payments/payment-enhancements/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" } ] } } } ``` ### 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. 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 Entity 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 | > 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 tables 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. | | ## 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" } } } ``` ## Related [Online Payments API](/docs/commerce/online-payments/index) [Real-time account updater](/docs/commerce/online-payments/capabilities/online-payments/payment-enhancements/account-updater) [Recurring payments](/docs/commerce/online-payments/capabilities/online-payments/payment-enhancements/recurring-payments) [Stored Payments](/docs/commerce/online-payments/capabilities/online-payments/payment-enhancements/stored-payments) [Tokenization API](/docs/commerce/optimization-protection/capabilities/tokenization/index)