3-D Secure API
Standalone authentication API for processing consumer payments
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%2F3-d-secure%2F3-d-secure-1.md
# generated: '2026-07-28'
openapi: 3.0.1
info:
title: 3-D Secure API
description: Standalone authentication API for processing consumer payments
version: 2.5.1
contact:
name: 3-D Secure API Support
url: https://developer.payments.jpmorgan.com/contact/support
email: ms.pit.team@jpmorgan.com
servers:
- url: https://api-ms.payments.jpmorgan.com/api/v2
description: PRODUCTION - OAUTH
- url: https://api-ms-test.payments.jpmorgan.com/api/v2
description: CLIENT TESTING - OAUTH
- url: https://api-mock.payments.jpmorgan.com/api/v2
description: MOCK
security:
- BearerAuth: []
tags:
- name: Authentication
description: Authentication
paths:
/authentications:
post:
summary: Prepare a 3DS authentication
operationId: V2SuthenticationPost
tags:
- Authentication
description: Prepare a 3DS authentication
parameters:
- name: request-id
in: header
required: true
schema:
type: string
example: 10cc0270-7bed-11e9-a188-1763956dd7f6
maxLength: 40
description: Merchant identifier for the request. The value must be unique.
examples:
3DS Frictionless Preparation:
value: 252f0171-9512-4f54-94e5-5c046dc55eab
3DS Challenge Preparation:
value: f9c75448-0764-4eee-b67f-d6e9d2fb167f
3DS CB Challenge Preparation:
value: 029b59c4-c266-477c-b8d2-882c22b664b7
- name: merchant-id
in: header
required: true
schema:
type: string
example: '991234567890'
minLength: 8
maxLength: 12
description: Identifier for the merchant account
examples:
3DS Frictionless Preparation:
value: 000017904371
3DS Challenge Preparation:
value: 000017904372
3DS CB Challenge Preparation:
value: 000017904373
- name: platform-id
in: header
schema:
type: string
description: Identifies the platform used to facilitate the transaction request
requestBody:
description: Authentication Request
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/authenticationRequest'
examples:
3DS Frictionless Preparation:
value:
authenticationPaymentMethodType:
card:
expiry:
month: 5
year: 2031
accountNumber: '5112345112345114'
amount: 25000
currency: EUR
authenticationAccount:
email: example@example.com
firstName: FirstName
lastName: LastName
middleName: MiddleName
phone:
countryCode: 1
phoneNumber: '8131112222'
billingAddress:
line1: 123 Main Street
line2: Apartment 3b
city: Tampa
state: FL
postalCode: '33602'
countryCode: USA
addressTypeCode: Doing Business As Address
shippingAddress:
line1: 123 Main Street
line2: Apartment 3b
city: Tampa
state: FL
postalCode: '33602'
countryCode: USA
addressTypeCode: Doing Business As Address
threeDSMethodMerchantNotificationUrl: https://returnurl.com
authenticationType: DEFAULT
3DS Challenge Preparation:
value:
authenticationPaymentMethodType:
card:
expiry:
month: 5
year: 2031
accountNumber: '4916994064252017'
amount: 25000
currency: EUR
authenticationAccount:
email: example@example.com
firstName: FirstName
lastName: LastName
middleName: MiddleName
phone:
countryCode: 1
phoneNumber: '8131112222'
billingAddress:
line1: 123 Main Street
line2: Apartment 3b
city: Tampa
state: FL
postalCode: '33602'
countryCode: USA
addressTypeCode: Doing Business As Address
shippingAddress:
line1: 123 Main Street
line2: Apartment 3b
city: Tampa
state: FL
postalCode: '33602'
countryCode: USA
addressTypeCode: Doing Business As Address
threeDSMethodMerchantNotificationUrl: https://returnurl.com
authenticationType: DEFAULT
3DS CB Challenge Preparation:
value:
authenticationPaymentMethodType:
card:
expiry:
month: 5
year: 2031
accountNumber: '4561953200000001'
amount: 25000
currency: EUR
authenticationAccount:
email: example@example.com
firstName: first_name
lastName: last_name
middleName: middle_name
phone:
countryCode: 1
phoneNumber: '8131112222'
billingAddress:
line1: 123 Main Street
line2: Apartment 3b
city: Tampa
state: FL
postalCode: '33602'
countryCode: USA
addressTypeCode: Doing Business As Address
shippingAddress:
line1: 123 Main Street
line2: Apartment 3b
city: Tampa
state: FL
postalCode: '33602'
countryCode: USA
addressTypeCode: Doing Business As Address
threeDSMethodMerchantNotificationUrl: https://returnurl.com
authenticationType: DEFAULT
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/authenticationResponse'
'400':
description: Badly formatted request
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'412':
description: Precondition failed
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'504':
description: Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
/authentications/{authentication-id}:
post:
summary: Perform a 3DS authentication
operationId: V2SuthenticationByIdPost
tags:
- Authentication
description: Perform a 3DS authentication after completing preparation
parameters:
- name: request-id
in: header
required: true
schema:
type: string
example: 10cc0270-7bed-11e9-a188-1763956dd7f6
maxLength: 40
description: Merchant identifier for the request. The value must be unique.
examples:
3DS Frictionless Completion:
value: 252f0171-9512-4f54-94e5-5c046dc55eab
3DS Challenge Completion:
value: f9c75448-0764-4eee-b67f-d6e9d2fb167f
3DS CB Challenge Completion:
value: f47ac10b-58cc-4372-a567-0e02b2c3d479
- name: merchant-id
in: header
required: true
schema:
type: string
example: '991234567890'
minLength: 8
maxLength: 12
description: Identifier for the merchant account
examples:
3DS Frictionless Completion:
value: 000017904371
3DS Challenge Completion:
value: 000017904372
3DS CB Challenge Completion:
value: 000017904373
- name: authentication-id
in: path
required: true
schema:
type: string
description: Unique identifier for the card owner authentication provided by global authentication
solution designed to make eCommerce transactions more secure and reduce fraud.
examples:
3DS Frictionless Completion:
value: 78d6c37b-42a4-4fd8-bcfb-fa2e830b629e
3DS Challenge Completion:
value: 2de369a8-6288-4e6a-9414-9973a5be2032
3DS CB Challenge Completion:
value: f5b3d6ad-550c-48ca-b2bb-798e798cc0c9
- name: platform-id
in: header
schema:
type: string
description: Identifies the platform used to facilitate the transaction request
requestBody:
description: Perform a 3DS authentication
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/authenticationByIdRequest'
examples:
3DS Frictionless Completion:
value:
channelType: BROWSER
accountType: CREDIT
threeDSRequestorAuthenticationInfo:
threeDSAuthenticationTimestamp: '2023-08-21T15:12:12Z'
threeDSChallengeType: NO_CHALLENGE
authenticationPurpose: PAYMENT_TRANSACTION
threeDSPurchaseInfo:
purchaseDate: '2023-08-21T15:12:12Z'
threeDomainSecureTransactionType: GOODS_SERVICES
browserInfo:
browserAcceptHeader: application/json
deviceIPAddress: 192.168.1.11
browserLanguage: EN
browserColorDepth: '8'
browserScreenHeight: '480'
browserScreenWidth: '640'
deviceLocalTimeZone: '1'
browserUserAgent: Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101
Firefox/47.0
javaEnabled: true
javaScriptEnabled: true
threeDSChallengeMerchantNotificationUrl: https://returnurl.com
authenticationAccount:
email: example@example.com
firstName: FirstName
lastName: LastName
middleName: MiddleName
phone:
countryCode: 1
phoneNumber: '8131112222'
billingAddress:
line1: 123 Main Street
line2: Apartment 3b
city: Tampa
state: FL
postalCode: '33602'
countryCode: USA
addressTypeCode: Doing Business As Address
shippingAddress:
line1: 123 Main Street
line2: Apartment 3b
city: Tampa
state: FL
postalCode: '33602'
countryCode: USA
addressTypeCode: Doing Business As Address
authenticationSupportUrl: https://merchantsupporturl.com
messageType: PAYMENT_AUTHENTICATION
3DS Challenge Completion:
value:
channelType: BROWSER
accountType: CREDIT
threeDSRequestorAuthenticationInfo:
threeDSAuthenticationTimestamp: '2023-08-21T15:12:12Z'
threeDSChallengeType: CHALLENGE_REQUESTED
authenticationPurpose: PAYMENT_TRANSACTION
threeDSPurchaseInfo:
purchaseDate: '2023-08-21T15:12:12Z'
threeDomainSecureTransactionType: GOODS_SERVICES
browserInfo:
browserAcceptHeader: application/json
deviceIPAddress: 192.168.1.11
browserLanguage: EN
browserColorDepth: '8'
browserScreenHeight: '480'
browserScreenWidth: '640'
deviceLocalTimeZone: '1'
browserUserAgent: Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101
Firefox/47.0
javaEnabled: true
javaScriptEnabled: true
threeDSChallengeMerchantNotificationUrl: https://returnurl.com
authenticationAccount:
email: example@example.com
firstName: FirstName
lastName: LastName
middleName: MiddleName
phone:
countryCode: 1
phoneNumber: '8131112222'
billingAddress:
line1: 123 Main Street
line2: Apartment 3b
city: Tampa
state: FL
postalCode: '33602'
countryCode: USA
addressTypeCode: Doing Business As Address
shippingAddress:
line1: 123 Main Street
line2: Apartment 3b
city: Tampa
state: FL
postalCode: '33602'
countryCode: USA
addressTypeCode: Doing Business As Address
authenticationSupportUrl: https://merchantsupporturl.com
messageType: PAYMENT_AUTHENTICATION
3DS CB Challenge Completion:
value:
channelType: BROWSER
accountType: CREDIT
threeDSRequestorAuthenticationInfo:
threeDSAuthenticationTimestamp: '2022-10-31T17:07:14.91Z'
threeDSChallengeType: CHALLENGE_REQUESTED
authenticationPurpose: PAYMENT_TRANSACTION
authenticationUseCase: SINGLE_PAYMENT
threeDSPurchaseInfo:
purchaseDate: '2022-10-31T17:07:14.91Z'
threeDomainSecureTransactionType: GOODS_SERVICES
purchasedItemCount: 0
threeDSPurchaseRisk:
shipmentType: CARDHOLDER_ADDRESS
deliveryTimeframe: SAME_DAY
productAvailabilityCode: AVAILABLE
requestorEstimatedTransactionFraudRiskScore: '0001'
browserInfo:
browserAcceptHeader: application/json
deviceIPAddress: 192.168.1.11
browserLanguage: en
browserColorDepth: '8'
browserScreenHeight: '480'
browserScreenWidth: '640'
deviceLocalTimeZone: '1'
browserUserAgent: Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101
Firefox/47.0
javaEnabled: true
javaScriptEnabled: true
threeDSChallengeMerchantNotificationUrl: https://returnurl.com
authenticationAccount:
email: example@example.com
firstName: FirstName
lastName: LastName
middleName: MiddleName
phone:
countryCode: 1
phoneNumber: '8131112222'
billingAddress:
line1: 123 Main Street
line2: Apartment 3b
city: Tampa
state: FL
postalCode: '33602'
countryCode: USA
addressTypeCode: Doing Business As Address
shippingAddress:
line1: 123 Main Street
line2: Apartment 3b
city: Tampa
state: FL
postalCode: '33602'
countryCode: USA
addressTypeCode: Doing Business As Address
authenticationSupportUrl: https://merchantsupporturl.com
messageType: PAYMENT_AUTHENTICATION
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/authenticationByIdResponse'
'400':
description: Badly formatted request
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'412':
description: Precondition failed
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'504':
description: Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
get:
summary: Retrieve an authentication request
operationId: V2SuthenticationByIdGet
tags:
- Authentication
description: Retrieve an authentication request
parameters:
- name: request-id
in: header
required: true
schema:
type: string
example: 10cc0270-7bed-11e9-a188-1763956dd7f6
maxLength: 40
description: Merchant identifier for the request. The value must be unique.
examples:
3DS Frictionless Completion:
value: 252f0171-9512-4f54-94e5-5c046dc55eab
3DS Challenge Completion:
value: 4b7632d6-4898-4c0a-b9f6-0d50c57aa124
3DS CB Challenge Completion:
value: a3d8e1b2-7f4c-4e9a-b6d1-8c5f2a9e0d73
404 - Not Found:
value: 7b14d406-7a99-48b5-a5d9-44a32f34b5de
- name: merchant-id
in: header
required: true
schema:
type: string
example: '991234567890'
minLength: 8
maxLength: 12
description: Identifier for the merchant account
examples:
3DS Frictionless Completion:
value: 000017904371
3DS Challenge Completion:
value: 000017904372
3DS CB Challenge Completion:
value: 000017904373
404 - Not Found:
value: 000017904100
- name: authentication-id
in: path
required: true
schema:
type: string
description: Unique identifier for the card owner authentication provided by global authentication
solution designed to make eCommerce transactions more secure and reduce fraud.
examples:
3DS Frictionless Completion:
value: 78d6c37b-42a4-4fd8-bcfb-fa2e830b629e
3DS Challenge Completion:
value: 2de369a8-6288-4e6a-9414-9973a5be2032
3DS CB Challenge Completion:
value: f5b3d6ad-550c-48ca-b2bb-798e798cc0c9
404 - Not Found:
value: not-found
- name: platform-id
in: header
schema:
type: string
description: Identifies the platform used to facilitate the transaction request
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/authenticationByIdResponse'
'400':
description: Badly formatted request
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'412':
description: Precondition failed
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
'504':
description: Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
authenticationRequest:
description: Authentication Request information
type: object
required:
- amount
- currency
properties:
authenticationPaymentMethodType:
$ref: '#/components/schemas/authenticationPaymentMethodType'
amount:
$ref: '#/components/schemas/amount'
currency:
$ref: '#/components/schemas/currency'
authenticationAccount:
$ref: '#/components/schemas/authenticationAccount'
shippingAddress:
$ref: '#/components/schemas/address'
threeDSMethodMerchantNotificationUrl:
description: A reference to a web resource on the internet specifying its location on a computer
network and a mechanism for retrieving. In this context, this is the notification URL from
Three Domain Secure to merchant after initial authentication request is complete.
type: string
authenticationType:
$ref: '#/components/schemas/authenticationType'
softMerchant:
$ref: '#/components/schemas/softMerchant'
merchantCategoryCode:
$ref: '#/components/schemas/merchantCategoryCode'
authenticationResponse:
description: Authentication Response Information
type: object
properties:
requestId:
$ref: '#/components/schemas/requestId'
authenticationId:
$ref: '#/components/schemas/authenticationId'
authenticationPaymentMethodType:
$ref: '#/components/schemas/authenticationPaymentMethodType'
responseCode:
$ref: '#/components/schemas/responseCode'
responseStatus:
$ref: '#/components/schemas/responseStatus'
responseMessage:
$ref: '#/components/schemas/responseMessage'
authenticationResult:
$ref: '#/components/schemas/authenticationResult'
threeDSMethodMerchantNotificationUrl:
description: A reference to a web resource on the internet specifying its location on a computer
network and a mechanism for retrieving. In this context, this is the notification URL from
Three Domain Secure to merchant after initial authentication request is complete.
type: string
authenticationType:
$ref: '#/components/schemas/authenticationType'
threeDSSchemeId:
$ref: '#/components/schemas/threeDSSchemeId'
information:
$ref: '#/components/schemas/information'
softMerchant:
$ref: '#/components/schemas/softMerchant'
merchantCategoryCode:
$ref: '#/components/schemas/merchantCategoryCode'
authenticationPaymentMethodType:
description: Authentication Payment Method Type
type: object
properties:
card:
$ref: '#/components/schemas/authenticationCard'
consumerProfile:
$ref: '#/components/schemas/authenticationConsumerProfile'
authenticationCard:
description: card information used for authentication purpose.
type: object
required:
- accountNumber
properties:
expiry:
$ref: '#/components/schemas/expiry'
accountNumber:
$ref: '#/components/schemas/accountNumber'
maskedAccountNumber:
$ref: '#/components/schemas/maskedAccountNumber'
accountNumberType:
description: Specifies the type of payment method used by the account number in payment transaction.
type: string
enum:
- PAN
- NETWORK_TOKEN
- SAFETECH_TOKEN
- SAFETECH_PAGE_ENCRYPTION
cardTypeName:
$ref: '#/components/schemas/cardTypeName'
cardType:
description: Abbreviation of card name
type: string
enum:
- VI
- MC
- AX
- DI
- JC
- DC
- CC
- CZ
- CR
- IM
- SP
- PP
- EP
- AP
- NP
- VR
- MR
- CB
example: VI
paymentTokens:
type: array
readOnly: true
description: List of payment tokens for the transaction
minItems: 0
items:
$ref: '#/components/schemas/paymentToken'
cvv:
$ref: '#/components/schemas/cvv'
encryptionIntegrityCheck:
$ref: '#/components/schemas/encryptionIntegrityCheck'
paymentToken:
description: Token Information for the payment transaction
type: object
properties:
tokenProvider:
$ref: '#/components/schemas/tokenProvider'
tokenNumber:
$ref: '#/components/schemas/tokenNumber'
responseStatus:
$ref: '#/components/schemas/responseStatus'
tokenServiceResponseMessage:
$ref: '#/components/schemas/tokenServiceResponseMessage'
tokenServiceResponseCode:
$ref: '#/components/schemas/tokenServiceResponseCode'
tokenProvider:
description: The label given to a provider who creates the digital token for cards.
type: string
readOnly: true
enum:
- NETWORK
- SAFETECH
- WALLET
tokenServiceResponseMessage:
description: Long explanation of response Message received from token service
type: string
readOnly: true
tokenServiceResponseCode:
description: Short explanation of response Code
type: string
readOnly: true
tokenNumber:
description: The token number is a secure surrogate value generated for an account number in a payment
transaction. The token is substituted for the card number or primary account number (PAN), Demand
Deposit Account (DDA) Number or other payment account and is used to process and identify transactions
originating from that account.
type: string
readOnly: true
cvv:
description: Card verification value (CVV/CV2)
type: string
pattern: ^[A-Za-z0-9]{3,6}$
minLength: 3
maxLength: 6
writeOnly: true
encryptionIntegrityCheck:
description: The alphanumeric string generated by voltage to verify the soundness of the encrypted
key used by merchant and payment process. The merchant passed this in the API call. The backend
process validates the subscriber id and format matches - between the merchant request for a key
and the UPG request
type: string
writeOnly: true
authenticationConsumerProfile:
description: Consumer Profile information used for authentication purpose.
type: object
required:
- consumerProfileId
- paymentMethodId
properties:
consumerProfileId:
$ref: '#/components/schemas/consumerProfileId'
paymentMethodId:
$ref: '#/components/schemas/paymentMethodId'
consumerProfileId:
description: Identifies a unique occurrence of a consumer maintained in the firm as requested by
merchant. Consumer profile contains information relevant to processing transactions such as name,
address, account and payment methods information.
type: string
paymentMethodId:
description: Identifies a unique occurrence of the type of payment accepted by a level of the hierarchy
of the merchant acquiring account.
type: string
expiry:
description: Expiration date
type: object
writeOnly: true
required:
- month
- year
properties:
month:
$ref: '#/components/schemas/month'
year:
$ref: '#/components/schemas/year'
accountNumber:
description: The card or token number.
type: string
writeOnly: true
maskedAccountNumber:
description: Identifies a concealed number associated with the card number recognized by various
payment systems. This is typically concealed by storing only the first 6 and/or last 4 digits
of the payment account number or some variation.
type: string
readOnly: true
example: 123456XXXXXX9876
cardType:
description: Abbreviation of card name
type: string
readOnly: true
maxLength: 10
example: VI
enum:
- VI
- MC
- AX
- DI
- JC
- DC
- CC
- CZ
- CR
- IM
- SP
- PP
- EP
- AP
- NP
- VR
- MR
- CB
cardTypeName:
description: Name of the payment network
type: string
readOnly: true
maxLength: 40
example: VISA
enum:
- VISA
- MASTERCARD
- AMERICAN_EXPRESS
- DISCOVER
- JCB
- DINERS_CLUB
- CHINA_UNION_PAY
- CHASENET_CREDIT
- CHASENET_SIGNATURE_DEBIT
- INTERNATIONAL_MAESTRO
- STAR_PINLESS
- PULSE_PINLESS
- EFTPOS_PINLESS
- ACCEL_PINLESS
- NYCE_PINLESS
- VISA_RESTRICTED_DEBIT
- MASTERCARD_RESTRICTED_DEBIT
- CARTES_BANCAIRES
currency:
description: Describes the currency type of the transaction
type: string
enum:
- USD
- EU
# --- truncated at 32 KB (76 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/jp-morgan-chase/refs/heads/main/openapi/jp-morgan-chase-3-d-secure-api-openapi.yml