Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Product Configuration Merchant Onboarding API
description: Product configuration APIs that can be used to create, configure and maintain Commerce platform accounts.
version: 1.0.3
servers:
- url: https://api.payments.jpmorgan.com/commerce/configuration/v1
description: PRODUCTION - OAUTH
- url: https://api-cat.payments.jpmorgan.com/commerce/configuration/v1
description: CLIENT TESTING - OAUTH
- url: https://api-mock.payments.jpmorgan.com/commerce/configuration/v1
description: MOCK
security:
- BearerAuth: []
tags:
- name: Merchant Onboarding
paths:
/merchant-boarding-requests:
post:
summary: Create a merchant onboarding request
operationId: createMerchantOnboardingReq
tags:
- Merchant Onboarding
description: Use this endpoint to initiate a merchant onboarding request. If you have all necessary data upfront, you can submit this request simultaneously.
requestBody:
description: Enterprise Profile Information
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/merchantOnboardingRequest'
examples:
Success:
value:
enterprisePlatformIdentifier: '6019573573'
onboardRequestStatus: DRAFT
clientId: '3002035472'
accountName: Dannys Donuts Downtown Location
locationAddress:
city: Plano
countryCode: USA
line1: 123 ABI Street
postalCode: 71301-7610
state: TX
pricingTemplate: STANDARD_PRICING
processingTemplate: ACH_PROCESSING_SETUP
businessProfile:
digitalSales:
usage: false
terminalSales:
usage: true
merchantManualKeyedTransactionsPercentage: 10
businessDescription: Donut shop with exotic pastries
projectedSalesInfo:
averageTicketSize: 7
annualSalesTotal: 500000
annualCreditSales: 400000
currency: CAD
payoutAccount:
financialInstitutionName: JP Morgan Chase
accountOwnerName: Leigh Dennis
routingNumber: '122199983'
accountNumber: '3990188838'
countryCode: USA
merchantMetadataList:
- metadataAttributeName: BackBookMigration
metadataAttributeValueText: Y
contactInfo:
email: customersupport@dannysdonuts.com
phone:
phoneNumber: '7894561551'
countryCode: '+1'
payoutTemplate: GROSS_PURCHASE_FUNDING
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/merchantOnboardingResponse'
'400':
description: Badly formatted request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/merchant-boarding-requests/{onboardRequestId}:
patch:
summary: Update a merchant onboarding request
operationId: updateMerchantOnboardingReq
tags:
- Merchant Onboarding
description: Use this endpoint to append additional client data to their merchant onboarding request, or submit the request to create a merchant account.
parameters:
- name: onboardRequestId
in: path
required: true
schema:
type: string
examples:
Success:
value: '10011033'
description: This is used for specifying individual parameters under API endpoint methods.
requestBody:
description: Updates a merchant onboarding request
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/merchantOnboardingPatchRequest'
examples:
Success:
value:
enterprisePlatformIdentifier: '6019573573'
onboardRequestStatus: SUBMITTED
clientId: '3002035472'
accountName: Dannys Donuts Downtown Location
accountAlias: Dannys Donuts
locationAddress:
city: Plano
countryCode: USA
line1: 123 ABI Street
postalCode: 71301-7610
state: TX
pricingTemplate: STANDARD_PRICING
processingTemplate: ACH_PROCESSING_SETUP
businessProfile:
digitalSales:
usage: false
website: www.google.com
terminalSales:
usage: true
merchantManualKeyedTransactionsPercentage: 10
businessDescription: Donut shop with exotic pastries
projectedSalesInfo:
averageTicketSize: 7
annualSalesTotal: 500000
annualCreditSales: 400000
currency: CAD
payoutAccount:
financialInstitutionName: JP Morgan Chase
accountOwnerName: Leigh Dennis
routingNumber: '122199983'
accountNumber: '3990188838'
countryCode: USA
merchantMetadataList:
- metadataAttributeName: BackBookMigration
metadataAttributeValueText: Y
contactInfo:
email: customersupport@dannysdonuts.com
phone:
phoneNumber: '7894561551'
countryCode: '+1'
payoutTemplate: GROSS_PURCHASE_FUNDING
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/merchantOnboardingResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
get:
summary: Retrieve merchant onboarding request details
operationId: getMerchantOnboardingReq
tags:
- Merchant Onboarding
description: Use this endpoint to retrieve the full set of data collected for a merchant onboarding request.
parameters:
- name: onboardRequestId
in: path
required: true
schema:
type: string
examples:
Success:
value: '10011033'
description: This is used for specifying individual parameters for the merchant account under API endpoint methods.
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/merchantOnboardingResponse'
'400':
description: Badly formatted request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
phoneNumber:
description: 'A locator whose value identifies the formatted numeric address for routing voice or data communications via telephony, to reach a party. NOTE: Telephone number formats may vary; this field can include domestic and international telephone numbers. This is the telephone number of the person to contact within the merchant''s business.'
type: string
pattern: ^[0-9]{10,10}$
maxLength: 10
title: PhoneNumber
digitalSales:
description: This is used for specifying an attribute used on a model for object that will contain one or more attributes
type: object
title: DigitalSales
properties:
usage:
description: Indicates a merchant sells goods or services online and can process a payment transaction (card not present) over the internet between the cardholder and the merchant
type: boolean
website:
$ref: '#/components/schemas/website'
ProcessingTemplate:
description: The alternate label for a pre-defined format for a processing entity configuration.
type: string
title: ProcessingTemplate
pattern: ^[A-Za-z0-9!#$%&'()*+,./:;<=>?@$$$$ ^_`{|}~-]{0,50}$
minLength: 1
maxLength: 50
ErrorContext:
properties:
code:
type: string
maxLength: 5
minLength: 5
pattern: ^[0-9]+$
title: Code
description: JPMC Short code that identifies the error - publicly cataloged and documented
message:
type: string
maxLength: 99
minLength: 1
pattern: ^[\x20-\x7E\xA0-\uFFFF\r\n]+$
title: Message
description: Human readable textual description of the error
location:
$ref: '#/components/schemas/LocationType'
description: The location of the error occurred in the request.
field:
type: string
maxLength: 99
minLength: 1
pattern: ^\$?[0-9a-zA-Z-_.()\[\]{}]+$
title: Field
description: The field which caused the error. Where the location of the error occurred is BODY, the field would contain the JSON Path expression
type: object
required:
- message
title: ErrorContext
description: Error Context model
example:
code: '10001'
field: notificationId
location: BODY
message: Required field missing - ensure the path, body and headers matches the specification
businessProfile:
description: This is used for specifying an attribute used on a model for object that will contain one or more attributes
type: object
title: BusinessProfile
properties:
digitalSales:
$ref: '#/components/schemas/digitalSales'
terminalSales:
$ref: '#/components/schemas/terminalSales'
businessDescription:
description: The detailed description of an item or service offered for sale by the Merchant.
type: string
minLength: 0
maxLength: 100
countryCode:
description: The telephone dialing prefix for a member country in the International Telecommunication Union (ITU) that is defined by the ITU-T E.164 standard. The code is a combination of one, two or three digits identifying a specific country, countries in an integrated numbering plan, or a specific geographic area.
type: string
minLength: 0
maxLength: 4
pattern: ^\+\d{1,3}$
title: CountryCode
merchantManualKeyedTransactionsPercentage:
description: Percentage of transactions which will be keyed into the terminal with the card not present (i.e. Mail or Phone Order). User can manually type in the credit card number themselves with a keypad such as if the card stripe is damaged or if they take an order over the phone.
type: integer
pattern: ^(100|[1-9][0-9]?)$
minimum: 1
maximum: 100
title: MerchantManualKeyedTransactionsPercentage
clientId:
description: A unique internal identifier created by the Firm's small medium business (SMB) unit for referencing a merchant.
type: string
pattern: ^[0-9]*$
minLength: 10
maxLength: 10
title: ClientId
merchantOnboardingPatchRequest:
description: This is used for specifying an attribute used on a model for object that will contain one or more attributes
type: object
title: MerchantOnboardingUpdate
properties:
onboardRequestStatus:
$ref: '#/components/schemas/onboardRequestStatus'
clientId:
$ref: '#/components/schemas/clientId'
accountName:
$ref: '#/components/schemas/accountName'
accountAlias:
$ref: '#/components/schemas/accountAlias'
locationAddress:
$ref: '#/components/schemas/locationAddressPatch'
pricingTemplate:
$ref: '#/components/schemas/pricingTemplate'
processingTemplate:
$ref: '#/components/schemas/ProcessingTemplate'
businessProfile:
$ref: '#/components/schemas/businessProfile'
projectedSalesInfo:
$ref: '#/components/schemas/projectedSalesInfo'
payoutAccount:
$ref: '#/components/schemas/payoutAccount'
merchantMetadataList:
$ref: '#/components/schemas/merchantMetadataList'
contactInfo:
$ref: '#/components/schemas/contactInfoPatch'
payoutTemplate:
$ref: '#/components/schemas/payoutTemplate'
enterprisePlatformIdentifier:
$ref: '#/components/schemas/enterprisePlatformIdentifier'
merchantOnboardingRequest:
description: This is used for specifying an attribute used on a model for object that will contain one or more attributes
title: MerchantOnboardingRequest
type: object
required:
- enterprisePlatformIdentifier
- clientId
- accountName
properties:
enterprisePlatformIdentifier:
$ref: '#/components/schemas/enterprisePlatformIdentifier'
onboardRequestStatus:
$ref: '#/components/schemas/onboardRequestStatus'
clientId:
$ref: '#/components/schemas/clientId'
accountName:
$ref: '#/components/schemas/accountName'
accountAlias:
$ref: '#/components/schemas/accountAlias'
locationAddress:
$ref: '#/components/schemas/locationAddress'
pricingTemplate:
$ref: '#/components/schemas/pricingTemplate'
processingTemplate:
$ref: '#/components/schemas/ProcessingTemplate'
businessProfile:
$ref: '#/components/schemas/businessProfile'
projectedSalesInfo:
$ref: '#/components/schemas/projectedSalesInfo'
payoutAccount:
$ref: '#/components/schemas/payoutAccount'
merchantMetadataList:
$ref: '#/components/schemas/merchantMetadataList'
contactInfo:
$ref: '#/components/schemas/contactInfo'
payoutTemplate:
$ref: '#/components/schemas/payoutTemplate'
Error:
properties:
title:
type: string
maxLength: 100
minLength: 1
pattern: ^[\x20-\x7E\xA0-\uFFFF]+$
title: Title
description: Short humanly-readable title of the error.
httpStatus:
type: integer
title: Httpstatus
description: HTTP Status Code
default: 400
min: 100
max: 599
traceId:
type: string
pattern: ^[\x21-\x7E\xA1-\uFFFF]+$
title: Traceid
description: JPMC Assigned traced identifier
requestId:
type: string
pattern: ^[\x21-\x7E\xA1-\uFFFF]+$
title: Requestid
description: The 'client originated' requestId
context:
items:
$ref: '#/components/schemas/ErrorContext'
type: array
maxItems: 100
minItems: 0
title: Context
description: Provides additional context and detail on the validation errors
additionalProperties: false
type: object
required:
- title
title: Error
description: Common Error Model matching the api-template schema
example:
context:
- code: '10001'
field: notificationId
location: BODY
message: Required field missing - ensure the path, body and headers matches the specification
httpStatus: 400
requestId: trace-123456
title: Invaliddata
traceId: 0eca2e1a-74b7-44b7-9e66-4a6ec8336eb9
deviceLanguageCode:
description: Indicates the method of communication, either spoken or written, consisting of the use of words in a structured and conventional way. The master set of values is defined by the International Organization for Standardization (ISO) standard 639-3.
type: string
pattern: ^[a-z]{2}-[A-Z]{2}$
maxLength: 5
title: DeviceLanguageCode
contactInfoPatch:
description: This is used for specifying an attribute used on a model for object that will contain one or more attributes
type: object
title: ContactInfoPatch
properties:
email:
description: A mail system that allows a party to send and receive messages electronically. An email address is composed of a local part and a domain part. The local part is unique to the individual while the domain or host name must meet specific standards required by the host that administers the email service.
type: string
minLength: 6
maxLength: 60
phone:
description: This is used for specifying an attribute used on a model for object that will contain one or more attributes
type: object
title: phone
properties:
phoneNumber:
$ref: '#/components/schemas/phoneNumber'
countryCode:
$ref: '#/components/schemas/countryCode'
accountAlias:
description: The alias chosen by the customer to identify the account.
type: string
pattern: ^[ -~ -ÿ]{1,25}$
minLength: 1
maxLength: 25
title: AccountAlias
onboardRequestStatus:
title: OnboardRequestStatus
description: "Indicates the onboarding status of the Enterprise Platform or Merchant Account for payment processing.\n | Status | Description |\n |:-------------------------|:-----------------------------------------------------------------------|\n | `DRAFT` | Create the request in draft status |\n | `SUBMITTED` | Update the request in Submit Status for further processing |\n"
type: string
enum:
- DRAFT
- SUBMITTED
merchantMetadataList:
title: MerchantMetadataList
type: array
minItems: 0
description: This is used for specifying an attribute used on a model for collection object that will contain one or more attributes
items:
$ref: '#/components/schemas/merchantMetadata'
accountName:
description: The alias name given to a Merchant Account, labeled as D.B.A., that is different from the legal name.
type: string
title: AccountName
pattern: ^[ -~ -ÿ]{1,40}$
minLength: 1
maxLength: 40
LocationType:
type: string
enum:
- BODY
- PATH
- QUERY
- HEADER
title: LocationType
description: Location where the error occurred in the request
projectedSalesInfo:
description: This is used for specifying an attribute used on a model for object that will contain one or more attributes
type: object
title: ProjectedSalesInfo
properties:
averageTicketSize:
description: Average price of a sale for the business.
type: integer
maximum: 999999999
annualSalesTotal:
description: Specifies the Borrower's Annual Sales provided at time of application.
type: integer
maximum: 999999999
annualCreditSales:
description: Specifies the monetary value of fiscal year credit card transactions as stated by a party who is either self-employed or a business owner from which the party receives a percentage of net profit.
type: integer
maximum: 999999999
currency:
description: Represents a unique identifier for currencies, as assigned by the ISO 4217 specification. Alternatively, a currency code may also be a custom firm assigned value created where an ISO code does not exist.
type: string
maxLength: 3
pattern: ^[A-Z]{3}$
website:
description: Provides textual information about data for the protocol for specifying addresses on the Internet (Universal Resource Locator - URL) for the merchant's organization.
type: string
minLength: 0
maxLength: 120
title: Website
enterprisePlatformIdentifier:
description: A unique identifier representing the profile (configuration) for an external client or internal service of the Firm that facilitates how it interacts with the Firm's services such as onboarding, transaction processing, embedded banking, etc.
type: string
title: EnterprisePlatformIdentifier
pattern: ^[0-9]*$
minLength: 10
maxLength: 10
locationAddressPatch:
description: This is used for specifying an attribute used on a model for object that will contain one or more attributes
type: object
title: LocationAddressPatch
properties:
city:
description: A portion of a party's address which is the geographic area that is a municipality with legal power granted by a state/province charter. In this context, it is the City Name of the merchant's postal address as it would appear on a mailing label.
type: string
minLength: 1
maxLength: 34
pattern: ^(?=.*\S{1}).{1,34}$
countryCode:
description: 'A code that identifies the Country, a Geographic Area, that is recognized as an independent political unit in world affairs. Note: This data element is a child of the Country Code CDE and valid values are based on ISO standards. In this context, it is the merchant''s mailing address country code as it would appear on an international mailing label.'
type: string
minLength: 1
maxLength: 3
pattern: ^[A-Z]{3}$
line1:
description: 'The portion of a party''s address that is the line of the unstructured (unparsed) geographic street address, containing any of the following: house number, street name, street direction, street type, dwelling type and number, post office box number, rural delivery route number, In Care Of. In this context, this is the first line of a merchant''s postal address as it would appear on a mailing label.'
type: string
minLength: 1
maxLength: 60
pattern: ^(?=.*\S{1}).{1,60}$
line2:
description: 'The portion of a party''s address that is the line of the unstructured (unparsed) geographic street address, containing any of the following: house number, street name, street direction, street type, dwelling type and number, post office box number, rural delivery route number, In Care Of. In this context, this is the second line of a merchant''s postal address as it would appear on a mailing label.'
type: string
minLength: 0
maxLength: 60
pattern: ^(?=.*\S{1}).{1,60}$
postalCode:
description: The portion of a party’s address that is the encoded representation of a geographic area to facilitate mail delivery services. In this context, it is the merchant's postal code as it would appear on a mailing label.
type: string
minLength: 1
maxLength: 10
pattern: ^[a-zA-Z0-9 -–]{1,10}$
state:
description: Classifies a geographic area that represents a first level, legal and political subdivision of a country; for example, Virginia, Bavaria. In this context, it is the merchant's state or province code, as it would appear on a mailing label.
type: string
minLength: 2
maxLength: 3
pattern: ^[a-zA-Z]{2,3}$
line3:
description: 'The portion of a party''s address that is the line of the unstructured (unparsed) geographic street address, containing any of the following: house number, street name, street direction, street type, dwelling type and number, post office box number, rural delivery route number, In Care Of. In this context, this is the second line of a merchant''s postal address as it would appear on a mailing label.'
type: string
minLength: 0
maxLength: 60
pattern: ^(?=.*\S{1}).{1,60}$
payoutAccount:
description: This is used for specifying an attribute used on a model for object that will contain one or more attributes
type: object
title: PayoutAccount
properties:
financialInstitutionName:
description: The party's name as provided at the time the party is onboarded or updated based on firm policies and business rules that allow for such updates. For an individual this field includes the first, middle, and last name. The full name can also include prefixes such as Dr. or Hon. and suffixes such as Jr or III. For non carbon entities, the field reflects the complete legal name by which an entity is registered with a state, local or federal government. Within this context, it is the label given to the financial institution where the client’s bank account is.
type: string
minLength: 1
maxLength: 100
pattern: (.){1,100}
accountOwnerName:
description: The party's name as provided at the time the party is onboarded or updated based on firm policies and business rules that allow for such updates. For an individual this field includes the first, middle, and last name. The full name can also include prefixes such as Dr. or Hon. and suffixes such as Jr or III. For non carbon entities, the field reflects the complete legal name by which an entity is registered with a state, local or federal government.
type: string
minLength: 1
maxLength: 60
pattern: (.){1,60}
accountType:
description: "Indicates the type of representation used for a monetary instrument (such as a Card, Direct Debit Account(DDA) or other payment account provided for alternative method of payment or local payment solution) sent to the merchant acquirer to facilitate payment for the exchange of goods and services in a financial transaction. These payment accounts can be a secure placeholder such as a Device Primary Account Number(DPAN) or a token or the actual account.\n\n | Account Type | Description |\n |:-------------------------|:----------------------------------------------------------------------|\n | `CHECKING` | Checking Account |\n | `SAVINGS` | Savings Account |\n | `CORPORATE_CHECKING` | Corporate Checking Account |\n| `CORPORATE_SAVINGS` | Corporate Savings Account |\n"
type: string
enum:
- CHECKING
- SAVINGS
- CORPORATE_CHECKING
- CORPORATE_SAVINGS
routingNumber:
description: Identifies the routing and transit number assigned by an administrative body to formally identify a chartered financial institution (bank) within a given country or common financial market for performing domestic transfers of funds to or from that institution's client accounts. Within the United States, this is known as the American Bankers Association Routing Number, and within Australia, this is known as a Bank State Branch Number. This common data element will house those two examples, along with the equivalent for any other country or financial market. For Canadian banks, it refers transitNumber.
type: string
minLength: 9
maxLength: 9
pattern: ^[0-9]{9}$
accountNumber:
description: The number assigned to a monetary instrument (such as a Card, Direct Debit Account(DDA) or other payment account identifier provided for alternative method of payment or local payment solution) sent to the merchant acquirer to facilitate payment for the exchange of goods and services in a financial transaction. These payment account identifiers can be a secure placeholder such as a Device Primary Account Number(DPAN) or a token or the actual account identifier.
type: string
minLength: 5
maxLength: 17
pattern: ^[0-9]{5,17}$
countryCode:
description: Uniquely represents a firm-recognized geopolitical area, including the ISO 3166 alpha 2-character country codes and other firm-created country codes.
type: string
maxLength: 3
pattern: ^[A-Z]{3}$
merchantMetadata:
description: This is used for specifying an attribute used on a model for object that will contain one or more attributes
type: object
title: MerchantMetaData
properties:
metadataAttributeName:
description: Specifies the label of the attribute associated with a data element when used in a key-value pair.
type: string
minLength: 0
maxLength: 60
pattern: ^[A-Za-z0-9\s]+$
metadataAttributeValueText:
description: Provides textual information about the value assigned to a data element when used in a key-value pair.
type: string
minLength: 0
maxLength: 60
pattern: ^[a-zA-Z0-9._\-#@ ]+$
merchantOnboardingResponse:
description: This is used for specifying an attribute used on a model for object that will contain one or more attributes
title: MerchantOnboardingResponse
type: object
properties:
onboardRequestId:
description: Unique identifier for the Onboard Request
type: string
minLength: 8
maxLength: 12
onboardRequestStatus:
$ref: '#/components/schemas/onboardRequestStatus'
merchantId:
description: Identifier for the merchant.
type: string
clientId:
$ref: '#/components/schemas/clientId'
accountName:
$ref: '#/components/schemas/accountName'
accountAlias:
$ref: '#/components/schemas/accountAlias'
locationAddress:
$ref: '#/components/schemas/locationAddress'
pricingTemplate:
$ref: '#/components/schemas/pricingTemplate'
processingTemplate:
$ref: '#/components/sche
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/jp-morgan-chase/refs/heads/main/openapi/jp-morgan-chase-merchant-onboarding-api-openapi.yml