Tokenization API
Merchant Services Tokenization APIs enable merchants to secure their cards on file by replacing the sensitive Primary Account Number (PAN) with a token. Currently supports network tokenization via Mastercard, Visa & Amex.
OpenAPI Specification
# Harvested verbatim from the J.P. Morgan Payments Developer Portal.
# method: searched
# source: https://developer.payments.jpmorgan.com/api/llm-content?path=en%2Fapi%2Fcommerce%2Foptimization-protection%2Ftokenization%2Ftokenization-oas.md
# generated: '2026-07-28'
openapi: 3.0.1
info:
title: Tokenization API
description: Merchant Services Tokenization APIs enable merchants to secure their cards on file by replacing
the sensitive Primary Account Number (PAN) with a token. Currently supports network tokenization via
Mastercard, Visa & Amex.
version: 1.5.0
contact:
name: Tokenization API Support
url: https://developer.payments.jpmorgan.com/contact
servers:
- url: https://api.merchant.jpmorgan.com/payments/v1/
description: PRODUCTION - OAUTH
- url: https://api-test.merchant.jpmorgan.com/payments/v1/
description: CLIENT TESTING - OAUTH
- url: https://api-mock.payments.jpmorgan.com/payments/v1
description: MOCK
security:
- BearerAuth: []
tags:
- name: Token Processing
description: Manage or request tokens and cryptograms.
- name: Cryptograms Request
description: Request cryptograms for a token.
- name: Token Lifecycle Management
description: Manage or request token state information.
- name: Bulk Operation
description: Bulk Token Operation.
- name: Bulk Key Management
description: Bulk Key Management
- name: Bank Account Tokenization
description: Bank Account Tokenization Management
- name: Health Check
description: Validate the health of the service.
paths:
/healthcheck:
get:
summary: Health check for the Tokenization service
security: []
operationId: v1GetHealth
tags:
- Health Check
description: Healthcheck endpoint to validate that the service is running.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/healthCheckResource'
examples:
Success:
value:
status: UP
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
/tokens:
post:
summary: Token provisioning request
operationId: v1ProvisionToken
tags:
- Token Processing
description: Provision a token for a payment instrument.
parameters:
- name: merchantId
in: header
required: true
schema:
type: string
minLength: 8
maxLength: 12
description: Identifier for the merchant account.
examples:
Visa card tokenization:
value: '991234567890'
MasterCard tokenization:
value: '991234567891'
Amex tokenization:
value: '991234567892'
Visa Token for Token:
value: '991234567893'
Mastercard Token for Token:
value: '991234567894'
- name: requestId
in: header
required: true
schema:
type: string
format: uuid
description: Merchant identifier for the request. The value must be unique.
examples:
Visa card tokenization:
value: 10cc0270-7bed-11e9-a188-1763956dd7f6
MasterCard tokenization:
value: 11cc0270-7bed-11e9-a188-1763956dd7f6
Amex tokenization:
value: 12cc0270-7bed-11e9-a188-1763956dd7f6
Visa Token for Token:
value: 13cc0270-7bed-11e9-a188-1763956dd7f6
Mastercard Token for Token:
value: 14cc0270-7bed-11e9-a188-1763956dd7f6
requestBody:
description: Token Provision request
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/tokenProvisionRequest'
examples:
Visa card tokenization:
value:
device:
deviceType: PHONE
deviceIPAddress: 127.0.0.1
deviceLocale: en-US
deviceLatLong: 40, -73
deviceMake: Samsung
deviceOS: ANDROID
deviceOsVersion: '12'
digitalDeviceIdentifier: ahd896384d
deviceGeoLocationCaptureTimestamp: '2021-09-08T21:01:20.945Z'
deviceName: Samsung_Android
walletId: '123'
accountInformation:
accountholderName: John Doe
accountholderEmail: test@test.com
accountType: GUEST
accountHolderReference: e5ad0fd0-4f92-4df
cardNumber: '4111111111111111'
billingAddress:
addressLine1: 7825 N MacArthur Blvd
addressLine2: Lewisville Mall
city: Irving
stateProvince: TX
postalCode: '72638'
countryCode: US
cardExpiry:
month: 11
year: 2022
cardSource: KEY_ENTERED
cardVerificationNumber: '325'
riskInformation:
walletRisk:
walletScore: 15
walletUsageLength: 94
walletTransactions: 35
walletNameMatch: true
cardRisk:
cardScore: 23
cardUsageLength: 249
deviceRisk:
deviceScore: 19
deviceUsageLength: 193
deviceTokenCount: 2
deviceCountry: US
userRisk:
userScore: 38
userUsageLength: 49
userTokenCount: 2
userWalletCount: 1
userCountry: US
newUserAccount: false
onFileTime: 37
presentationModes:
- ECOM
recommendationPath: APPROVED
MasterCard tokenization:
value:
device:
deviceType: PHONE
deviceIPAddress: 127.0.0.1
deviceLocale: en-US
deviceLatLong: 40, -73
deviceMake: Samsung
deviceOS: ANDROID
deviceOsVersion: '12'
digitalDeviceIdentifier: ahd896384d
deviceGeoLocationCaptureTimestamp: '2021-09-08T21:01:20.945Z'
deviceName: Samsung_Android
walletId: '123'
accountInformation:
accountholderName: John Doe
accountholderEmail: test@test.com
accountType: GUEST
accountHolderReference: e5ad0fd0-4f92-4df
cardNumber: '5204740000001002'
billingAddress:
addressLine1: 7825 N MacArthur Blvd
addressLine2: Lewisville Mall
city: Irving
stateProvince: TX
postalCode: '72638'
countryCode: US
cardExpiry:
month: 11
year: 2022
cardSource: KEY_ENTERED
cardVerificationNumber: '325'
riskInformation:
walletRisk:
walletScore: 15
walletUsageLength: 94
walletTransactions: 35
walletNameMatch: true
cardRisk:
cardScore: 23
cardUsageLength: 249
deviceRisk:
deviceScore: 19
deviceUsageLength: 193
deviceTokenCount: 2
deviceCountry: US
userRisk:
userScore: 38
userUsageLength: 49
userTokenCount: 2
userWalletCount: 1
userCountry: US
newUserAccount: false
onFileTime: 37
presentationModes:
- ECOM
recommendationPath: APPROVED
Amex tokenization:
value:
device:
deviceType: PHONE
deviceIPAddress: 127.0.0.1
deviceLocale: en-US
deviceLatLong: 40, -73
deviceMake: Samsung
deviceOS: ANDROID
deviceOsVersion: '12'
digitalDeviceIdentifier: ahd896384d
deviceGeoLocationCaptureTimestamp: '2021-09-08T21:01:20.945Z'
deviceName: Samsung_Android
walletId: '123'
accountInformation:
accountholderName: John Doe
accountholderEmail: test@test.com
accountType: GUEST
accountHolderReference: e5ad0fd0-4f92-4df
cardNumber: '340000000000001'
billingAddress:
addressLine1: 7825 N MacArthur Blvd
addressLine2: Lewisville Mall
city: Irving
stateProvince: TX
postalCode: '72638'
countryCode: US
cardExpiry:
month: 11
year: 2022
cardSource: KEY_ENTERED
cardVerificationNumber: '3251'
riskInformation:
walletRisk:
walletScore: 15
walletUsageLength: 94
walletTransactions: 35
walletNameMatch: true
cardRisk:
cardScore: 23
cardUsageLength: 249
deviceRisk:
deviceScore: 19
deviceUsageLength: 193
deviceTokenCount: 2
deviceCountry: US
userRisk:
userScore: 38
userUsageLength: 49
userTokenCount: 2
userWalletCount: 1
userCountry: US
newUserAccount: false
onFileTime: 37
presentationModes:
- ECOM
recommendationPath: APPROVED
Visa Token for Token:
value:
device:
deviceType: PHONE
deviceIPAddress: 127.0.0.1
deviceLocale: en-US
deviceLatLong: 40, -73
deviceMake: Samsung
deviceOS: ANDROID
deviceOsVersion: '12'
digitalDeviceIdentifier: ahd896384d
deviceGeoLocationCaptureTimestamp: '2025-09-15T21:01:20.945Z'
deviceName: Samsung_Android
walletId: '123'
accountInformation:
accountholderName: John Doe
accountholderEmail: test@test.com
accountType: GUEST
accountHolderReference: e5ad0fd0-4f92-4df
cardNumber: '4846011467670267'
billingAddress:
addressLine1: 7825 N MacArthur Blvd
addressLine2: Lewisville Mall
city: Irving
stateProvince: TX
postalCode: '72638'
countryCode: US
cardExpiry:
month: 12
year: 2027
cardSource: KEY_ENTERED
cardVerificationNumber: '325'
riskInformation:
walletRisk:
walletScore: 15
walletUsageLength: 94
walletTransactions: 35
walletNameMatch: true
cardRisk:
cardScore: 23
cardUsageLength: 249
deviceRisk:
deviceScore: 19
deviceUsageLength: 193
deviceTokenCount: 2
deviceCountry: US
userRisk:
userScore: 38
userUsageLength: 49
userTokenCount: 2
userWalletCount: 1
userCountry: US
newUserAccount: false
onFileTime: 37
presentationModes:
- ECOM
recommendationPath: APPROVED
Mastercard Token for Token:
value:
device:
deviceType: PHONE
deviceIPAddress: 127.0.0.1
deviceLocale: en-US
deviceLatLong: 40, -73
deviceMake: Samsung
deviceOS: ANDROID
deviceOsVersion: '12'
digitalDeviceIdentifier: ahd896384d
deviceGeoLocationCaptureTimestamp: '2025-09-15T21:01:20.945Z'
deviceName: Samsung_Android
walletId: '123'
accountInformation:
accountholderName: John Doe
accountholderEmail: test@test.com
accountType: GUEST
accountHolderReference: e5ad0fd0-4f92-4df
cardNumber: '5204731600012812'
billingAddress:
addressLine1: 7825 N MacArthur Blvd
addressLine2: Lewisville Mall
city: Irving
stateProvince: TX
postalCode: '72638'
countryCode: US
cardExpiry:
month: 12
year: 2027
cardSource: KEY_ENTERED
cardVerificationNumber: '325'
tokenProvisioningVerificationValue: '654'
riskInformation:
walletRisk:
walletScore: 15
walletUsageLength: 94
walletTransactions: 35
walletNameMatch: true
cardRisk:
cardScore: 23
cardUsageLength: 249
deviceRisk:
deviceScore: 19
deviceUsageLength: 193
deviceTokenCount: 2
deviceCountry: US
userRisk:
userScore: 38
userUsageLength: 49
userTokenCount: 2
userWalletCount: 1
userCountry: US
newUserAccount: false
onFileTime: 37
presentationModes:
- ECOM
recommendationPath: APPROVED
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/tokenProvisionResponse'
examples:
Visa card tokenization:
value:
identifier: fb0dabc0-da2c-46b6-b3a3-8fc6d3185e08
timestamp: '2021-09-15T19:08:19.097Z'
tokenInformation:
tokenNumber: '4761340000000019'
expiry:
month: 11
year: 2022
tokenReferenceIdentifier: af0a77c2-3810-457f-8d47-807bab406df8
tokenizationApprovalStatus: APPROVED
cardReferenceNumber: 73ebcc62-56c0-41d2-b70a-4ede8cd700ff
cardTokenStatus: ACTIVE
cardLast4Digits: '1111'
cardBrand: VISA
cardMetaData:
cardArtUrl: http://cardArtUrl.com
backgroundCardGraphicsColor: '#000000'
foregroundCardGraphicsColor: '#FFFFFF'
labelCardGraphicsColor: '#C0C0C0'
cardDescription: The Bank Chase Card
issuerInformation:
cardIssuer: Bank Example
cardIssuerEmailAddress: bank@example.com
issuerWebsiteURL: bank.com
cardIssuerCustomerServiceTelephone: '400800393'
issuerOnlineBankingURL: onlinebanking.com
issuerIconURL: http://logo.png
issuerPrivacyURLText: privacypolicybank.com
issuerLogoURLText: banklogo.com
issuerApplicationOS: IOS
issuerAppName: bankmobileapp
issuerAppAddress: com.bank.appname
cardShortDescription: The Bank Card
cardTermsAndConditionsIdentifier: 37629726-58cf-4fbb-a2bd-457614704be4
cardTermsAndConditionsURL: http://termsAndConditionsUrl.com
cardAssetData:
- assetReferenceIdentifier: 3801a454c0b84de883f5432815ded5f5
assetType: ICON_ISSUER
mimeType: IMAGE/PNG
pixelHeight: 100
pixelWidth: 100
requestIdentifier: 276ac797-8754-4ab8-a0b7-87da568e4d6d
responseStatus: SUCCESS
responseCode: APPROVED
responseMessage: The request is well received
MasterCard tokenization:
value:
identifier: fb0dabc0-da2c-46b6-b3a3-8fc6d3185e08
timestamp: '2021-09-15T19:08:19.097Z'
tokenInformation:
tokenNumber: '5000010000000019'
expiry:
month: 11
year: 2022
tokenReferenceIdentifier: af0a77c2-3810-457f-8d47-807bab406df8
tokenizationApprovalStatus: APPROVED
cardReferenceNumber: 73ebcc62-56c0-41d2-b70a-4ede8cd700ff
cardTokenStatus: ACTIVE
cardLast4Digits: '1002'
cardBrand: MASTERCARD
cardMetaData:
cardArtUrl: http://cardArtUrl.com
backgroundCardGraphicsColor: '#000000'
foregroundCardGraphicsColor: '#FFFFFF'
labelCardGraphicsColor: '#C0C0C0'
cardDescription: The Bank Chase Card
issuerInformation:
cardIssuer: Bank Example
cardIssuerEmailAddress: bank@example.com
issuerWebsiteURL: bank.com
cardIssuerCustomerServiceTelephone: '400800393'
issuerOnlineBankingURL: onlinebanking.com
issuerIconURL: http://logo.png
issuerPrivacyURLText: privacypolicybank.com
issuerLogoURLText: banklogo.com
issuerApplicationOS: IOS
issuerAppName: bankmobileapp
issuerAppAddress: com.bank.appname
cardShortDescription: The Bank Card
cardTermsAndConditionsIdentifier: 37629726-58cf-4fbb-a2bd-457614704be4
cardTermsAndConditionsURL: http://termsAndConditionsUrl.com
cardAssetData:
- assetReferenceIdentifier: 3801a454c0b84de883f5432815ded5f5
assetType: ICON_ISSUER
mimeType: IMAGE/PNG
pixelHeight: 100
pixelWidth: 100
requestIdentifier: 276ac797-8754-4ab8-a0b7-87da568e4d6d
responseStatus: SUCCESS
responseCode: APPROVED
responseMessage: The request is well received
Amex tokenization:
value:
identifier: fb0dabc0-da2c-46b6-b3a3-8fc6d3185e08
timestamp: '2022-09-09T19:08:19.097Z'
tokenInformation:
tokenNumber: '340000000001000'
expiry:
month: 11
year: 2022
tokenReferenceIdentifier: af0a77c2-3810-457f-8d47-807bab406df8
tokenizationApprovalStatus: APPROVED
cardReferenceNumber: 73ebcc62-56c0-41d2-b70a-4ede8cd700ff
cardTokenStatus: ACTIVE
cardLast4Digits: '0001'
cardBrand: AMEX
cardMetaData:
cardArtUrl: http://cardArtUrl.com
backgroundCardGraphicsColor: '#000000'
foregroundCardGraphicsColor: '#FFFFFF'
labelCardGraphicsColor: '#C0C0C0'
cardDescription: The Bank Chase Card
issuerInformation:
cardIssuer: Bank Example
cardIssuerEmailAddress: bank@example.com
issuerWebsiteURL: bank.com
cardIssuerCustomerServiceTelephone: '400800393'
issuerOnlineBankingURL: onlinebanking.com
issuerIconURL: http://logo.png
issuerPrivacyURLText: privacypolicybank.com
issuerLogoURLText: banklogo.com
issuerApplicationOS: IOS
issuerAppName: bankmobileapp
issuerAppAddress: com.bank.appname
cardShortDescription: The Bank Card
cardTermsAndConditionsIdentifier: 37629726-58cf-4fbb-a2bd-457614704be4
cardTermsAndConditionsURL: http://termsAndConditionsUrl.com
cardAssetData:
- assetReferenceIdentifier: 3801a454c0b84de883f5432815ded5f5
assetType: ICON_ISSUER
mimeType: IMAGE/PNG
pixelHeight: 100
pixelWidth: 100
requestIdentifier: 276ac797-8754-4ab8-a0b7-87da568e4d6d
responseStatus: SUCCESS
responseCode: APPROVED
responseMessage: The request is well received
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/adfsError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/tokenProvisionDuplicateResponse'
examples:
Resource Not Found:
value:
responseCode: DUPLICATE
responseMessage: This request has already been processed
payload:
identifier: fb0dabc0-da2c-46b6-b3a3-8fc6d3190e98
requestIdentifier: fb0dabc0-da2c-46b6-b3a3-8fc6d3185e08
tokenReferenceIdentifier: fb0dabc0-da2c-46b6-b3a3-8fc6d3185e09
cardMetaData:
cardArtUrl: http://cardArtUrl.com
backgroundCardGraphicsColor: '#000000'
foregroundCardGraphicsColor: '#FFFFFF'
labelCardGraphicsColor: '#C0C0C0'
cardDescription: The Bank Chase Card
issuerInformation:
cardIssuer: Bank Example
cardIssuerEmailAddress: bank@example.com
issuerWebsiteURL: bank.com
cardIssuerCustomerServiceTelephone: '400800393'
issuerOnlineBankingURL: onlinebanking.com
issuerIconURL: http://logo.png
issuerPrivacyURLText: privacypolicybank.com
issuerLogoURLText: banklogo.com
issuerApplicationOS: IOS
issuerAppName: bankmobileapp
issuerAppAddress: com.bank.appname
cardShortDescription: The Bank Card
cardTermsAndConditionsIdentifier: 37629726-58cf-4fbb-a2bd-457614704be4
cardTermsAndConditionsURL: http://termsAndConditionsUrl.com
cardAssetData:
- assetReferenceIdentifier: 3801a454c0b84de883f5432815ded5f5
assetType: ICON_ISSUER
mimeType: IMAGE/PNG
pixelHeight: 100
pixelWidth: 100
'412':
description: Precondition Failed
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
/cryptograms:
post:
summary: Token cryptogram request
operationId: v1CreateCryptogram
tags:
- Cryptograms Request
description: Request a cryptogram for a network token. The request can be initiated using either
the tokenNumber or tokenReferenceIdentifier field.
parameters:
- name: merchantId
in: header
required: true
schema:
type: string
minLength: 8
maxLength: 12
description: Identifier for the merchant account.
examples:
Visa cryptogram request:
value: '991234567890'
MasterCard cryptogram request:
value: '991234567891'
Amex cryptogram request:
value: '991234567892'
- name: requestId
in: header
required: true
schema:
type: string
format: uuid
description: Merchant identifier for the request. The value must be unique.
examples:
Visa cryptogram request:
value: 10cc0270-7bed-11e9-a188-1763956dd7f6
MasterCard cryptogram request:
value: 11cc0270-7bed-11e9-a188-1763956dd7f6
Amex cryptogram request:
value: 12cc0270-7bed-11e9-a188-1763956dd7f6
requestBody:
description: Request a cryptogram for a token for payment processing.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/tokenCryptogramRequest'
examples:
Visa cryptogram request:
value:
paymentOrder:
amounts:
amount: 1234
currency: USD
device:
deviceType: PHONE
deviceIPAddress: 192.168.1.78
deviceLocale: en-US
deviceLatLong: 40, -73
deviceMake: Samsung
deviceOS: ANDROID
deviceOsVersion: '12.0'
digitalDeviceIdentifier: ahd896384d
deviceGeoLocationCaptureTimestamp: '2021-09-08T21:01:20.945Z'
deviceName: Samsung_Android
walletId: '123'
initiatedBy: CARDHOLDER
transactionType: ECOMMERCE
paymentInstrument:
accountholderName: Jane Doe
tokenReferenceIdentifier: 205c9a37-ae4a-4cb5-8c9a-75de746500b5
tokenNumber: '4111111111111111'
electronicCommerceIndicator: '02'
expiry:
month: 12
year: 2022
tokenAuthenticationValue: AgAAABBBBq1IZrIDlcLmQD4AAAA=
tokenCryptogramType: TAVV
MasterCard cryptogram request:
value:
paymentOrder:
amounts:
amount: 1234
currency: USD
device:
deviceType: PHONE
deviceIPAddress: 192.168.1.78
deviceLocale: en-US
deviceLatLong: 40, -73
deviceMake: Samsung
deviceOS: ANDROID
deviceOsVersion: '12.0'
digitalDeviceIdentifier: ahd896384d
deviceGeoLocationCaptureTimestamp: '2021-09-08T21:01:20.945Z'
deviceName: Samsung_Android
walletId: '123'
initiatedBy: CARDHOLDER
transactionType: ECOMMERCE
paymentInstrument:
accountholderName: Jane Doe
tokenReferenceIdentifier: 205c9a37-ae4a-4cb5-8c9a-75de746500b5
tokenNumber: '5011111111111111'
electronicCommerceIndicator: '02'
expiry:
month: 12
year: 2022
tokenAuthenticationValue: AgAAABBBBq1IZrIDlcLmQD4AAAA=
tokenCryptogramType: UCAF
randomNumber: '19283765'
Amex cryptogram request:
value:
paymentOrder:
amounts:
amount: 1234
currency: USD
device:
deviceType: PHONE
deviceIPAddress: 192.168.1.78
deviceLocale: en-US
deviceLatLong: 40, -73
deviceMake: Samsung
deviceOS: ANDROID
deviceOsVersion: '12.0'
digitalDeviceIdentifier: ahd896384d
deviceGeoLocationCaptureTimestamp: '2021-09-08T21:01:20.945Z'
deviceName: Samsung_Android
walletId: '123'
initiatedBy: CARDHOLDER
transactionType: ECOMMERCE
paymentInstrument:
accountholderName: Jane Doe
tokenReferenceIdentifier: 205c9a37-ae4a-4cb5-8c9a-75de746500b5
tokenNumber: '340000000001000'
electronicCommerceIndicator: '07'
expiry:
# --- truncated at 32 KB (148 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/jp-morgan-chase/refs/heads/main/openapi/jp-morgan-chase-tokenization-api-openapi.yml