Bulk tokenization
Bulk tokenization provides you with the ability to migrate and provision a large batch of primary account numbers (PANs) or card numbers to create network tokens (NWTs) or Safetech tokens (SFTs).
Here’s a diagram of the bulk tokenization process:
Delivery formats
There are two ways you can send a bulk tokenization file:
- API Support
- Large file support utilizing Managed File Transfer Support (MFTS)
| PAN to Network token | PAN to Safetech token | Safetech token to Network token | |
|---|---|---|---|
| API Support | Yes | Yes | |
| Large file support (MFTS) | Yes | Yes |
API support
The API support uploads a batch tokenization file size of up to 6 megabytes, or approximately 32,000 records.
Bulk tokenization support is available for the following tokenization services:
- PAN to Network token
- PAN to Safetech token
To initiate the bulk tokenization process via API:
- Prepare a bulk tokenization file in the comma-separated value (CSV) format below.
- Include the bulk tokenization file in a request to the Tokenization API via the POST /bulk-tokens endpoint.
- Check the status of a specific bulk tokenization file by sending a GET call to the /bulk-tokens/{merchant-file-identifier} endpoint.
- Download the response file via a GET /bulk-tokens/{merchant-file-identifier}/download request.
Encryption for API support
Bulk tokenization via API support meets the payment card industry (PCI) standards by using the HTTPS over transport layer security (TLS) 1.2 communication protocol. As an added security measure, bulk tokenization supports pretty good privacy (PGP) encryption for the request file.
The encryption is based on a GNU privacy guard (GPG) asymmetric key pair, and is driven by a boolean flag (isEncrypted) in the header.
To send an encrypted file:
- Use the PGP encryption with a J.P. Morgan public key.
- Set the isEncrypted flag to true.
Once the file is received successfully, the service decrypts the file before processing it further
If you do not wish to encrypt the file, set the isEncrypted flag to false.
Large file support
The MFTS is available for uploading a large bulk file (with a size of up to 1 gigabyte) and can include up to 1 million token requests.
Large file support is currently available for:
- PAN to network token
- PAN to Safetech token
- Safetech token to network token
Before you start the process of sending the request file, ensure that the filename is in the right format, or it will be rejected.
- The request filename must be in the format MerchantId-MerchantFileIdentifier-YYYYMMDD.csv.gpg
- The response filename will be in the format MerchantId-MerchantFileIdentifier-YYYYMMDD_ResponseFileType(S/D).csv.gpg
Perform the following steps to initiate the bulk tokenization process with the MFTS service:
- Contact your relationship manager to begin the onboarding process for the MFTS. You will receive your folder link and credentials.
- Request a J.P. Morgan public key by sending a GET call to the /bulk-tokens/encryption-key endpoint.
- Submit your public key by sending a POST call to the /bulk-tokens/encryption-key endpoint.
- Place the file (created per the format below and encrypted using the J.P. Morgan public key) into the provided MFTS folder. Ensure that the filename is in this format: MerchantId-MerchantFileIdentifier-YYYYMMDD.csv.gpg
- Tokenization picks up the file from MFTS.
- Bulk tokenization performs the following actions:
- Decrypts the file
- Tokenizes the records
- Creates a token response file
- Encrypts the file using a client key
- Places the file in the client's folder
- Decrypts the file
- Check the status of a specific bulk tokenization file by sending a GET call to the /bulk-tokens/{merchant-file-identifier} endpoint.
- Download the file from the provided MFTS folder. The response filename will be in this format: MerchantId-MerchantFileIdentifier-YYYYMMDD_ResponseFileType(S/D).csv.gpg.
File formats
PAN to Network token
Here's an example of a bulk tokenization batch request in CSV format for PAN to network token (PAN2NWT):
Request file specification
Plaintext
0,123456789012,20220124,D,PAN2NWT
1,1234567890000001,1222,ECOM,213-555-2621,example1@example.com, 123.456.78.90,302e20dc-c3ac-4a,,0123456789
1,1234567890000002,1222,ECOM,816-555-3142,example2@example.com, 123.456.78.90,302e20dc-c3ac-4b,,0123456789
1,1234567890000003,1222,ECOM,443-555-4873,example3@example.com, 123.456.78.90,302e20dc-c3ac-4c,,0123456789
1,1234567890000004,1222,ECOM,827-555-5924,example4@example.com, 123.456.78.90,302e20dc-c3ac-4d,,0123456789
1,1234567890000005,1222,ECOM,425-555-6184,example5@example.com, 123.456.78.90,302e20dc-c3ac-4e,,0123456789
1,1234567890000006,1222,ECOM,231-555-7665,example6@example.com, 123.456.78.90,302e20dc-c3ac-4f,,0123456789
1,1234567890000007,1222,ECOM,772-555-8136,example7@example.com, 123.456.78.90,302e20dc-c3ac-4g,,0123456789
1,1234567890000008,1222,ECOM,407-555-9497,example8@example.com, 123.456.78.90,302e20dc-c3ac-4h,,0123456789
9,8 | Field number | Data | Description | Maximum length | Format | Required (R), Conditional (C), or Optional (O) |
|---|---|---|---|---|---|
| 1 | Indicator | Indicates that the record is a header record (value is fixed as 0) | String(1) | Numeric | R |
| 2 | Processing entity/merchant ID | Identifier for the client's account (e.g., 991234567890) | String(12) | Numeric | R |
| 3 | Date | Indicates the date (e.g., YYYYMMDD) of the file being generated (e.g., 20211025) | String(8) | Numeric | R |
| 4 | Response file type | Indicates if a summary or detailed response is expected
|
String(1) | Alphabetic | R |
| 5 | Request type | Indicates the type of request being made. For example, PAN2NWT indicates a request from an account number to a network token. | String | Alphanumeric | R |
| Field number | Data | Description | Maximum length | Format | Required (R), Conditional (C), or Optional (O) |
|---|---|---|---|---|---|
| 1 | Indicator | Indicates that the record is a detail record (value is fixed as 1) | String(1) | Numeric | R |
| 2 | Account number | The account number to be tokenized | String(16) | Numeric | R |
| 3 | Expiry date | Date of expiration of the payment card (e.g., MMYY) | String(4) | Numeric | R |
| 4 | Presentation modes | Supported presentation modes for the token (e.g., ECOM) | String(6) | Alphabetic | R |
| 5 | Accountholder telephone | The telephone number of the accountholder (e.g., X-XXX-XXX-XXXX) | String(14) | Numeric | R — For American Express (AMEX) if accountholderEmail is not provided |
| 6 | Accountholder email | The email address of the accountholder | String | Alphanumeric | R — For AMEX if accountholderTelephone is not provided R – For Visa. |
| 7 | Internet protocol (IP) address | IP address of the consumer's device used during token transactions (e.g., XXX.XXX.XX.XX). | String(16) | Numeric | R — For AMEX, the IP address is required in IPv4 format. Also, required if cardSource is MOBILEBANKINGAPP, KEYENTERED, CAMERACAPTURED, or MANUALUNKNOWN. |
| 8 | Accountholder reference ID | A unique reference identifier for a consumer within the cardholder. Note: The Visa token maxLength is 24 characters. | String(24) | Alphanumeric | R — For Visa token service O — For AMEX and Mastercard |
| 9 | Sub-merchant ID | The sub-merchant identifier for independent software vendor (ISV) and aggregator support | String | Alphanumeric | O |
| 10 | Token requestor ID | Identifier for the client given by the payment networks or token provider | String(36) | Numeric | R |
| Field number | Data | Description | Maximum length | Format | Required (R), Conditional (C), or Optional (O) |
|---|---|---|---|---|---|
| 1 | Indicator | Indicates that the record is a trailer record (value is fixed as 9) | String(1) | Numeric | R |
| 2 | Record count | Indicates the number of detailed records (e.g., 00000009) | String(8) | Numeric | R |
Response file specification
Depending on the specified value for the responseFileType in the batch request, the response will be one of the following types:
- Summary (S)
- Detailed (D)
The following is an example of a batch summary response in CSV format:
Plaintext
0,123456789001,01/25/2022,123456732432,6906b003-bd62-4344-8365-c76082209e40
2,5,Duplicate Request
9,8,8,1The following is an example of a batch detailed response in CSV format:
Plaintext
0,1234567890252,01/25/2022,123456732432,d8333f94-86e6-41ee-9cac-71dcc4840701
1,302e20dc-c3ac-4g,0123456789,4895379990001111,ACTIVE,,b2192azk-403d-4bd8-a781-6f426b86b202
1,302e20dc-c3ac-4h,0123456789,4895379990001112,ACTIVE,,b2192azk-403d-4bd8-a781-6f426b86b202
1,302e20dc-c3ac-4b,0123456789,4895379990001113,ACTIVE,,b2192azk-403d-4bd8-a781-6f426b86b202
1,302e20dc-c3ac-4f,0123456789,4895379990001114,ACTIVE,,b2192azk-403d-4bd8-a781-6f426b86b202
1,302e20dc-c3ac-4c,0123456789,4895379990001115,ACTIVE,,b2192azk-403d-4bd8-a781-6f426b86b202
1,302e20dc-c3ac-4a,0123456789,4895379990001116,ACTIVE,,b2192azk-403d-4bd8-a781-6f426b86b202
1,302e20dc-c3ac-4d,0123456789,4895379990001117,ACTIVE,,b2192azk-403d-4bd8-a781-6f426b86b202
2,5,Duplicate Request
9,8,8,1| Field number | Data | Description | Maximum length | Format |
|---|---|---|---|---|
| 1 | Indicator | Indicates that the record is a header record (value is fixed as 0) | String(1) | Numeric |
| 2 | Processing entity/merchant ID | Identifier for the client's account | String(12) | Numeric |
| 3 | Date | The date of the file being generated (e.g., MM/DD/YYYY) | String(8) | Numeric |
| 4 | File identifier | A unique number assigned to a data file containing one or more records that have been processed or transmitted | String(36) | Alphanumeric |
| 5 | Batch ID | J.P. Morgan-generated identifier for status tracking using universally unique identifiers (UUIDs) | String(8) | Alphanumeric |
| Field number | Data | Description | Maximum length | Format |
|---|---|---|---|---|
| 1 | Indicator | Indicates that the record is a detail record (value is fixed as either 1, 2, or 3)
|
String(1) | Numeric |
| 2 | Row count | Specifies the row number | String(5) | Numeric |
| 3 | Accountholder reference ID | Unique reference identifier for a consumer within the token requester | String(36) | Alphanumeric |
| 4 | Token requestor ID | Identifier for the client given by payment networks or token provider | String(36) | Alphanumeric |
| 5 | Token number | A secure surrogate value for the account number utilized during payment | String(19) | Numeric |
| 6 | Token state | Specifies whether the token is ACTIVE or INACTIVE | String | Alphabetic |
| 7 | Response message | Descriptive message of the processing result |
String | Alphabetic |
| 8 | token-reference-id (API path parameter) tokenReferenceIdentifier (API body field) |
Unique value that represents the token, and is used to retrieve information related to the token, including metadata for the underlying card account | String | Alphanumeric |
| Field number | Data | Description | Maximum length | Format |
|---|---|---|---|---|
| 1 | Indicator | Indicates that the record is a trailer record (value is fixed at 9) | String(1) | Numeric |
| 2 | Total count | The total count in the trailer of the request file | String(12) | Numeric |
| 3 | Processed count | The total count of records processed, including failures and rejections | String(12) | Numeric |
| 4 | Reject count | The total number of rejected detail rows | String(12) | Numeric |
PAN to SFT
The following is an example of a bulk tokenization batch request in CSV format for PAN to SFT (PAN2SFT) tokenization:
Request file specification
Plaintext
0,123456789012,20220124,D,PAN2SFT
1,1234567890000001,302e20dc-c3ac-4a
1,1234567890000002,302e20dc-c3ac-4b
1,1234567890000003,302e20dc-c3ac-4c
1,1234567890000004,302e20dc-c3ac-4d
1,1234567890000005,302e20dc-c3ac-4e
1,1234567890000006,302e20dc-c3ac-4f
1,1234567890000007,302e20dc-c3ac-4g
1,1234567890000008,302e20dc-c3ac-4h
9,8| Field number | Data | Description | Maximum length | Format | Required (R), Conditional (C), or Optional (O) |
|---|---|---|---|---|---|
| 1 | Indicator | Indicates that the record is a header record (value is fixed as 0) | String(1) | Numeric | R |
| 2 | Processing entity/merchant ID | Identifier for the client's account (e.g., 991234567890) | String(12) | Numeric | R |
| 3 | Date | Indicates the date (e.g., YYYYMMDD) of the file being generated (e.g., 20211025) | String(8) | Alphabetic | R |
| 4 | Response file type | Indicates if a summary or detailed response is expected
|
String(1) | Alphabetic | R |
| 5 | Request type | Indicates the type of request being made. For example, PAN2SFT indicates a request from an account number to a network token. | String | Alphanumeric | R |
| Field number | Data | Description | Maximum length | Format | Required (R), Conditional (C), or Optional (O) |
|---|---|---|---|---|---|
| 1 | Indicator | Indicates that the record is a detail record (value is fixed as 2) | String(1) | Numeric | R |
| 2 | Account number | The account number to be tokenized | String(16) | Numeric | R |
| 3 | Accountholder reference ID | A unique reference identifier for a consumer within the cardholder. Note: The Visa token maxLength is 24 characters. | String(24) | Alphanumeric | R — For Visa token service O — For AMEX and Mastercard |
| Field number | Data | Description | Maximum length | Format | Required (R), Conditional (C), or Optional (O) |
|---|---|---|---|---|---|
| 1 | Indicator | Indicates that the record is a trailer record (value is fixed as 9) | String(1) | Numeric | R |
| 2 | Record count | Indicates the number of detailed records (e.g., 00000009) | String(8) | Numeric | R |
Response file specification
Depending on the specified value for the responseFileType in the batch request, the response will be one of the following types:
- Summary (S)
- Detailed (D)
The following is an example of a batch summary response in CSV format:
Plaintext
0,123456789001,01/25/2022,123456732432,6906b003-bd62-4344-8365-c76082209e40
2,5,Duplicate Request
9,8,8,1The following is an example of a batch detailed response in CSV format:
Plaintext
0,1234567890252,01/25/2022,123456732432,d8333f94-86e6-41ee-9cac-71dcc4840701
1,302e20dc-c3ac-4g,4895379990001111
1,302e20dc-c3ac-4h,4895379990001112
1,302e20dc-c3ac-4b,4895379990001113
1,302e20dc-c3ac-4f,4895379990001114
1,302e20dc-c3ac-4c,4895379990001115
1,302e20dc-c3ac-4a,4895379990001116
1,302e20dc-c3ac-4d,4895379990001117
2,5,Duplicate Request
9,8,8,1| Field number | Data | Description | Maximum length | Format |
|---|---|---|---|---|
| 1 | Indicator | Indicates that the record is a header record (value is fixed as 0) | String(1) | Numeric |
| 2 | Merchant ID | Identifier for the client's account | String(12) | Numeric |
| 3 | Date | The date of the file being generated (e.g., MM/DD/YYYY) | String(8) | Numeric |
| 4 | File identifier | A unique number assigned to a data file containing one or more records that have been processed or transmitted | String(36) | Alphanumeric |
| 5 | Batch ID | J.P. Morgan-generated identifier for status tracking using UUIDs | String(8) | Alphanumeric |
| Field number | Data | Description | Maximum length | Format |
|---|---|---|---|---|
| 1 | Indicator | Indicates that the record is a detail record (value is fixed as either 1, 2, or 3)
|
String(1) | Numeric |
| 2 | Row count | Specifies the row number | String(5) | Numeric |
| 3 | Accountholder reference ID | Unique reference identifier for a consumer within the token requester | String(36) | Alphanumeric |
| 4 | Safetech token number | A secure surrogate value for the account number utilized during payment | String(19) | Numeric |
| 5 | Response message | Descriptive message of the processing result |
String | Alphabetic |
| Field number | Data | Description | Maximum length | Format |
|---|---|---|---|---|
| 1 | Indicator | Indicates that the record is a trailer record (value is fixed at 9) | String(1) | Numeric |
| 2 | Total count | The total count in the trailer of the request file | String(12) | Numeric |
| 3 | Processed count | The total count of records processed, including failures and rejections | String(12) | Numeric |
| 4 | Reject count | The total number of rejected detail rows | String(12) | Numeric |
SFT to NWT
The following is an example of a bulk tokenization batch request in CSV format for SFT to NWT (SFT2NWT) tokenization:
Request file specification
Plaintext
0,123456789012,20220124,D,SFT2NWT
1,1234567890000001,1222,ECOM,213-555-2621,example1@example.com, 123.456.78.90,302e20dc-c3ac-4a,,0123456789
1,1234567890000002,1222,ECOM,816-555-3142,example2@example.com, 123.456.78.90,302e20dc-c3ac-4b,,0123456789
1,1234567890000003,1222,ECOM,443-555-4873,example3@example.com, 123.456.78.90,302e20dc-c3ac-4c,,0123456789
1,1234567890000004,1222,ECOM,827-555-5924,example4@example.com, 123.456.78.90,302e20dc-c3ac-4d,,0123456789
1,1234567890000005,1222,ECOM,425-555-6184,example5@example.com, 123.456.78.90,302e20dc-c3ac-4e,,0123456789
1,1234567890000006,1222,ECOM,231-555-7665,example6@example.com, 123.456.78.90,302e20dc-c3ac-4f,,0123456789
1,1234567890000007,1222,ECOM,772-555-8136,example7@example.com, 123.456.78.90,302e20dc-c3ac-4g,,0123456789
1,1234567890000008,1222,ECOM,407-555-9497,example8@example.com, 123.456.78.90,302e20dc-c3ac-4h,,0123456789
9,8| Field number | Data | Description | Maximum length | Format | Required (R), Conditional (C), or Optional (O) |
|---|---|---|---|---|---|
| 1 | Indicator | Indicates that the record is a header record (value is fixed as 0) | String(1) | Numeric | R |
| 2 | Processing entity/merchant ID | Identifier for the client's account (e.g., 991234567890) | String(12) | Numeric | R |
| 3 | Date | Indicates the date (e.g., YYYYMMDD) of the file being generated (e.g., 20211025) | String(8) | Numeric | R |
| 4 | Response file type | Indicates if a summary or detailed response is expected
|
String(1) | Alphabetic | R |
| 5 | Request type | Indicates the type of request being made. For example, SFT2NWT indicates a request from an SFT to an NWT. | String | Alphanumeric | R |
| Field number | Data | Description | Maximum length | Format | Required (R), Conditional (C), or Optional (O) |
|---|---|---|---|---|---|
| 1 | Indicator | Indicates that the record is a detail record (value is fixed as 1) | String(1) | Numeric | R |
| 2 | Safetech token number | The Safetech number to be tokenized | String(16) | Numeric | R |
| 3 | Expiry date | Date of expiration of the payment card (e.g., MMYY) | String(4) | Numeric | R |
| 4 | Presentation modes | Supported presentation modes for the token (e.g., ECOM) | String(6) | Alphabetic | R |
| 5 | Accountholder telephone | The telephone number of the accountholder (e.g., X-XXX-XXX-XXXX) | String(14) | Numeric | R — For American Express (AMEX) if accountholderEmail is not provided |
| 6 | Accountholder email | The email address of the accountholder | String | Alphanumeric | R — For AMEX if accountholderTelephone is not provided R – For Visa. |
| 7 | IP address |
IP address of the consumer's device used during token transactions (e.g., XXX.XXX.XX.XX). | String(16) | Numeric | R — For AMEX, the IP address is required in IPv4 format. Also, required if cardSource is MOBILEBANKINGAPP, KEYENTERED, CAMERACAPTURED, or MANUALUNKNOWN. |
| 8 | Accountholder reference ID | A unique reference identifier for a consumer within the cardholder. Note: The Visa token maxLength is 24 characters. | String(24) | Alphanumeric | R — For Visa token service O — For AMEX and Mastercard |
| 9 | Sub-merchant ID | The sub-merchant identifier for ISV and aggregator support | String | Alphanumeric | O |
| 10 | Token requestor ID | Identifier for the client received during onboarding |
String(36) | Numeric | R |
| Field number | Data | Description | Maximum length | Format | Required (R), Conditional (C), or Optional (O) |
|---|---|---|---|---|---|
| 1 | Indicator | Indicates that the record is a trailer record (value is fixed as 9) | String(1) | Numeric | R |
| 2 | Record count | Indicates the number of detailed records (e.g., 00000009) | String(8) | Numeric | R |
Response file specification
Depending on the specified value for the responseFileType in the batch request, the response will be one of the following types:
- Summary (S)
- Detailed (D)
The following is an example of a batch summary response in CSV format:
Plaintext
0,123456789001,01/25/2022,123456732432,6906b003-bd62-4344-8365-c76082209e40
2,5,Duplicate Request
9,8,8,1The following is an example of a batch detailed response in CSV format:
Plaintext
0,1234567890252,01/25/2022,123456732432,d8333f94-86e6-41ee-9cac-71dcc4840701
1,302e20dc-c3ac-4g,0123456789,4895379990001111,ACTIVE,,b2192azk-403d-4bd8-a781-6f426b86b202
1,302e20dc-c3ac-4h,0123456789,4895379990001112,ACTIVE,,b2192azk-403d-4bd8-a781-6f426b86b202
1,302e20dc-c3ac-4b,0123456789,4895379990001113,ACTIVE,,b2192azk-403d-4bd8-a781-6f426b86b202
1,302e20dc-c3ac-4f,0123456789,4895379990001114,ACTIVE,,b2192azk-403d-4bd8-a781-6f426b86b202
1,302e20dc-c3ac-4c,0123456789,4895379990001115,ACTIVE,,b2192azk-403d-4bd8-a781-6f426b86b202
1,302e20dc-c3ac-4a,0123456789,4895379990001116,ACTIVE,,b2192azk-403d-4bd8-a781-6f426b86b202
1,302e20dc-c3ac-4d,0123456789,4895379990001117,ACTIVE,,b2192azk-403d-4bd8-a781-6f426b86b202
2,5,Duplicate Request
9,8,8,1| Field number | Data | Description | Maximum length | Format |
|---|---|---|---|---|
| 1 | Indicator | Indicates that the record is a header record (value is fixed as 0) | String(1) | Numeric |
| 2 | Processing entity/merchant ID | Identifier for the client's account (e.g., 991234567890) | String(12) | Numeric |
| 3 | Date | Indicates the date of the file being generated (e.g., MM/DD/YYYY) | String(8) | Numeric |
| 4 | File identifier | A unique number assigned to a data file containing one or more records that have been processed or transmitted | String(36) | Alphanumeric |
| 5 | Batch identifier | J.P. Morgan-generated identifier for status tracking using UUIDs | String(8) | Alphanumeric |
| Field number | Data | Description | Maximum length | Format |
|---|---|---|---|---|
| 1 | Indicator | Indicates that the record is a detail record (value is fixed as either 1, 2, or 3)
|
String(1) | Numeric |
| 2 | Row count | Specifies the row number | String(5) | Numeric |
| 3 | Accountholder reference ID | Unique reference identifier for a consumer within the token requester | String(36) | Alphanumeric |
| 4 | Token requestor ID | Identifier for the client given by payment networks or token provider | String(36) | Alphanumeric |
| 5 | Token number | A secure surrogate value for the account number utilized during payment | String(19) | Numeric |
| 6 | Token state | Specifies whether the token is ACTIVE or INACTIVE | String | Alphabetic |
| 7 | Response message | Descriptive message of the processing result |
String | Alphabetic |
| 8 | token-reference-id (API path parameter) tokenReferenceIdentifier (API body field) |
Unique value that represents the token, and is used to retrieve information related to the token, including metadata for the underlying card account | String | Alphanumeric |
| Field number | Data | Description | Maximum length | Format |
|---|---|---|---|---|
| 1 | Indicator | Indicates that the record is a trailer record (value is fixed at 9) | String(1) | Numeric |
| 2 | Total count | The total count in the trailer of the request file | String(12) | Numeric |
| 3 | Processed count | The total count of records processed, including failures and rejections | String(12) | Numeric |
| 4 | Reject count | The total number of rejected detail rows | String(12) | Numeric |