openapi: 3.2.0 info: title: Product Configuration Merchant 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 description: Merchant entity information paths: /merchant-accounts/{merchantAccountId}: get: summary: Retrieve merchant details operationId: getMerchantAccount tags: - Merchant description: Use this endpoint to retrieve the current configurations and processing status for a given merchant account. parameters: - name: merchantAccountId in: path required: true schema: type: string examples: Success: value: '101128635403' description: This is the merchant Id for which the data will be fetched. responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/merchantResponse' '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' merchantResponse: description: This is used for specifying an attribute used on a model for object that will contain one or more attributes type: object title: MerchantResponse properties: merchantAccountId: description: Identifier for the merchant. type: string merchantCategoryCode: description: Indicates a merchant's primary goods or services sold, this is a four-digit number associated with a business by a credit/debit card merchant acquirer or merchant transaction processor (e.g., 5411 = "GROCERY STORES, SUPERMARKETS", 5812 = "EATING PLACES, RESTAURANTS", 4121 = "TAXICABS AND LIMOUSINES"). 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/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' enterprisePlatformIdentifier: $ref: '#/components/schemas/enterprisePlatformIdentifier' onboardRequestId: description: Unique identifier for the Onboard Request type: string merchantAccountStatus: description: 'Indicates the status of a Merchant Account as set up for the merchant. | Merchant Status | Description | |:-----------------------------------|:----------------------------------------------------------------------| | `BOARDING_IN_PROGRESS` | Boarding has been initiated and is in Progress | | `BOARDING_DECLINED` | Boarding of the merchant has been declined | | `ACTIVE` | Merchant has been boarded successfully and is in Active status | | `SUSPENDED` | Merchant is in suspended status | | `CLOSED` | Merchant is in closed status | ' type: string enum: - BOARDING_IN_PROGRESS - BOARDING_DECLINED - ACTIVE - SUSPENDED - CLOSED 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 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 accountAlias: description: The alias chosen by the customer to identify the account. type: string pattern: ^[ -~ -ÿ]{1,25}$ minLength: 1 maxLength: 25 title: AccountAlias 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 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._\-#@ ]+$ pricingTemplate: description: The alternate label for a pre-defined format for a pricing configuration. type: string pattern: ^[A-Za-z0-9!#$%&'()*+,./:;<=>?@$$$$ ^_`{|}~-]{0,50}$ minLength: 1 maxLength: 50 title: PricingTemplate payoutTemplate: description: The label given to the Funds Transfer Instructions (FTI) provided on reports to the merchant. type: string pattern: ^[A-Za-z0-9!#$%&'()*+,./:;<=>?@$$$$ ^_`{|}~-]{0,50}$ minLength: 1 maxLength: 50 title: PayoutTemplate contactInfo: description: This is used for specifying an attribute used on a model for object that will contain one or more attributes type: object title: ContactInfo 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' terminalSales: description: This is used for specifying an attribute used on a model for object that will contain one or more attributes type: object title: TerminalSales properties: usage: description: Indicates the point of sale device is enabled to process payment transactions for the merchant with the Firm's payment transaction processing platform. type: boolean merchantManualKeyedTransactionsPercentage: $ref: '#/components/schemas/merchantManualKeyedTransactionsPercentage' deviceLanguageCode: $ref: '#/components/schemas/deviceLanguageCode' locationAddress: description: This is used for specifying an attribute used on a model for object that will contain one or more attributes type: object title: LocationAddress 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 third 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}$ securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT x-jpmc-securityDefinitions: JPMC-OAuth2: jpmc-claims: jpmc-roles: - Reader: Reader - Editor: Writer x-jpmc-security: JPMC-OAuth2: jpmc-claims: jpmc-roles: - Reader: Reader - Editor: Writer