Integration guide

Use this guide to onboard your organization and applications to J.P. Morgan Business Direct Connect.

To complete the onboarding process, follow these steps:

1. Onboard your organization in the UAT (test) environment
2. Onboard your application in the UAT environment
3. Establish connectivity and invoke APIs
4. Obtain user consent
5. Exchange the authorization code for access, refresh, and ID tokens
6. Manage the access and refresh token lifecycle

The lower environment used to test your integration is the UAT (pre-production or test). It is functionally equivalent to production. New functionality is introduced in UAT and promoted to production after validation. 

After onboarding is complete and you have valid access token, your application can connect to J.P. Morgan Digital Banking accounts.

Use these sections to initiate onboarding for your organization and applications. The process is the same for both UAT (test) and production environments. Submit separate requests for each environment.

1. Onboard your organization into the UAT environment

Register your organization as a partner with Business Direct Connect. This partner construct represents your company and serves as the parent entity for all registered applications.

Send the required information to your assigned J.P. Morgan integration team. After registration is complete, you can modify your registration request as needed.

Partner registration

To initiate onboarding, provide these details:

• A JSON-formatted registration request using the partner onboarding template:

  • Replace partnerName with your firm’s name in all caps with no spaces, as specified in the partnerName field.
  • Replace the date suffix with the date the file is generated. Refer to Partner onboarding template table for field descriptions.

• A 30x30 logo file in PNG format. This logo is displayed to the end user during the consent flow.

  • Name the file using this format: partner_partnerName_yyyymmdd.png.
  • partnerName should match the value used in the registration request.
  • The date suffix should be the date the file was generated in yyyymmdd format.

• A set of IP addresses to be allowlisted in Classless Inter-Domain Routing (CIDR) notation for access to the UAT environment only (Production IPs do not need to be allowlisted):

  • IP addresses used to access FDX APIs.
  • IP addresses used to request access tokens.
  • IP addresses for user machines initiating the consent workflow in a browser.

Modify an existing registration

To modify, delete, or reactivate an existing registration, submit a JSON-formatted request using the partner onboarding template.

• Specify the desired action in the action field.
• All fields must be specified, and partnerName must match the previously provided value.
• For a MODIFY request, the newly provided values will override the previous values. partnerName cannot be modified.
• The DELETE action will deactivate the partner record. All related application records are also deactivated.
• To reactivate a deleted partner, specify the action as REACTIVATE. The applications will need to be re-registered or reactivated, and the user must provide fresh consent.

Create a partner onboarding request

The partner onboarding table describes the fields included in the partner onboarding request. Save this template as a file and email it to your J.P. Morgan integration team at JPMorgan_Corporate_FDX_Support@jpmorgan.com.

• Name the file using this format: partner_<partnerName>_<yyyymmdd>.json.
• Update the attributes according to the partner onboarding instructions table.
• The date suffix should be the date the file was generated, in yyyymmdd format.

Use the partner onboarding template as a reference to construct your request.

Partner onboarding template

Partner onboarding instructions

2. Onboard your application in the UAT environment

To register your application, submit the required details to your integration team. You can update your registration after it is complete.

Application registration

To register an application, provide these details:

• A JSON-formatted registration request using the application onboarding template.

  • Replace partnerName with your firm’s name in all caps without spaces, as noted in the template.
  • Replace appName with the name of the application in all caps without spaces, as noted in the template.
  • Replace the date suffix with the date the file is generated in yyyymmdd format.
  • Populate all fields within the template.
  • clientId must be provided, except for a new registration.
  • Required permissions for an application must be a subset of those for the partner.

• A 30x30 logo file in PNG format.

  • This logo is displayed to the end user during the consent flow.
  • Name the file using this format: application_PartnerName-ApplicationName_yyyymmdd.png.
  • partnerName and appName should match the values used in onboarding.
  • Replace the date suffix with the date the file was generated in yyyymmdd format.

Upon successful onboarding, clientID is generated for the registered application and sent to the contact email in the partner registration record. Any errors, clarifications, or exceptions are also sent to the same email address.

Modify an existing application registration

To modify, delete, or reactivate a previously registered application, submit a JSON-formatted request using the application onboarding template. 

• Specify the desired action in the action field.
• All fields must be specified.·         
• PartnerName, ClientId, and ApplicationName must match the previously provided values.
• For a MODIFY request, the newly provided values will override the previous values. PartnerName, ApplicationName, and ClientId cannot be modified.
• DELETE action will deactivate the application's record along with all associated consent records.
• To reactivate a deleted application, specify the action as REACTIVATE. The user must provide fresh consent.
• If an application is modified to update the RequiredPermissions, the original permissions continue to apply to existing consents. Updated permissions apply only to new consents.

Create an application onboarding request

Use the application onboarding template as a reference to construct your request. Copy this to a file and email it to your J.P. Morgan integration support team.

Refer to the application onboarding template instructions to learn how to construct the request.

• Name the file using this format: application_PartnerName-ApplicationName_yyyymmdd.json.
• Update the attributes according to the instructions table.
• Replace the date suffix with the date the file was generated in yyyymmdd format.

Application onboarding template

Application onboarding template instructions

The application onboarding table describes the fields included in the application onboarding template:

3. Establish connectivity and invoke APIs

Use environment‑specific endpoints for consent (authorization), token operations (exchange, refresh, revoke), and the Data API. Align scope strings and JSON Web Token (JWT) audience values with the selected environment and include the required headers (authorization, x‑fapi‑interaction-id) in data calls .

Production and UAT URLs

This table describes the URLs and endpoints used for connectivity and API operations in both UAT (pre-production) and production environments:

4. Obtain user consent

To obtain user consent, construct the authorization URL using the appropriate environment endpoints. 

If the authorization URI is well formed and query parameters are valid, the user logs in, authenticates, and selects the accounts to share. After the user consents, the system sends the authorization code to the redirect URL:

<redirect-uri>?client_id=<client id>&code=<auth_code>&iss=<issuer>&state=<state>&traceId=<Trace id>

Authorization URL parameters

The authorization URL parameters table describes the parameters required to construct the authorization URL for user consent. It specifies which fields are mandatory and provides a brief description of each field.

5. Token exchange and management

Exchange authorization code for access, refresh, and ID tokens

Send a request to the token endpoint.

<token endpoint URL>?client_id:<CLIENT_ID>&grant_type=authorization_code&code=<code>&code_verifier=<code_verifier>&redirect_uri=<https://redirect_uri>&client_assertion=<client_assertion>&client_assertion_type=<client_assertion_type>

Header: Content-Type: application/x-www-form-urlencoded'

Token exchange parameters

This table describes the parameters required when exchanging an authorization token for access, refresh, and ID tokens. Each parameter must be included in the request to the token endpoint.

The response returns the access token as shown in the sample response:

Sample response

Client assertion token generation

This flow uses a signed JSON web Token (JWT) to request an OAuth access token by sending a request to the token endpoint. Use these steps to create a client assertion token:

1. Fetch the private key and certificate
   1. Obtain the private key and the corresponding certificate for the application (client).
   2. Refer to the certificate generation section for instructions on creating the certificate.
2. Create the JWT
   1. Construct a JWT with the header example parameters:

Header example

Payload example 

        3. Sign the JWT with the application's private key and the self-signed certificate using the RSA256 algorithm.

Example of an assertion token:

eyJraWQiOiJDQkVtYmVkZGVkQmFua2luZyIsInBpLmF0bSI6IjdpOW8iLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE3MjEzMzk0NDgsImV4cCI6MTcyMTM0MTI0OCwiYXVkIjoiaHR0cHM6Ly9wZi5zaXQuYXV0aGUuZGV2LmF3cy5qcG1jaGFzZS5uZXQiLCJpc3MiOiJDX0pQTUNfMTE0MzU1X0lOVFVJVDk4LVFVSUNLQk9PS1MxMDZfU0lUXzAwMDczIiwic3ViIjoiQ19KUE1DXzExNDM1NV9JTlRVSVQ5OC1RVUlDS0JPT0tTMTA2X1NJVF8wMDA3MyJ9.X71QFuTGa4_qAmy_jrehWRD98EWoT_RUOYX27m5X4Hy10HtD_1TUl6EysXtJVLF3DdNST6BRnohXI0L5JgLGhdAkR1WKOJBspAIUUttWj6_ref7wnOvQZY0o2KL_4IPL3np-0WlLCkksWJHm66OKAjOECJg1pYxSnH5byaCzgK0NAaEBSIyN_-nS_2Aaux2OQSXtyqcCKFtFYsg4HAz2AwtFxyokWfYLxxWYG9X6o3h9eV3BJBh8066Y65h99aUtaURWQbtwnWLxFQ_iHI5mvwqtWXwuptR8NVL6VsB6ahX90Leu7n-78U7TPThdsYkrnaFw2PsAAnnOefu85C_O7Q

Examples of parameters used in JWT generation

UAT environment example:

Header

Payload

Signature (encoded)

JPCq8ZRMywhMxEJf0B7UIr9XVNI7405csLymrG7ax0Qhypo-TzrlOViI-nZ_nvnZcZtR71_UEMCwsl4-UlYNZ20MBUZTA0rB7ypDK5g4DFsSxGQwAIJ00pb3-0LUt8poAdaKFWiPLT-mZmeIeBBpqiNGELRdW1-SxRRq2h_abJWRQ1uiRHz9k5RNXUIAtPaqn2b8Lal8tWvP-fftEjt1vM42yjMK1H2eksBfzxzGQ0qnN289C2Jc6QomxoAbm5kWcL9KsRBZwDIM6uJan56Zryaw1zx6pvy_ClkuWPCmh4OOWTjfL3DLiLbOtXMoW6sa4EBdsaDNblcemwQMeV_zXkw

Production environment example:

Header

Payload

Signature (encoded)

JPCq8ZRMywhMxEJf0B7UIr9XVNI7405csLymrG7ax0Qhypo-TzrlOViI-nZ_nvnZcZtR71_UE

6. Token lifecycle management

This section explains how to refresh and revoke tokens.

• Access token: Valid for 15 minutes. Refresh it before it expires.
• Refresh token: Valid for one year. The user must re-consent to renew.

Refresh the access token

Send a request to the token endpoint.

<token endpoint URL>?client_id=<CLIENT_ID>&grant_type=<refresh_token>&refresh_token=<refresh token>&client_assertion=<client_assertion_token>&client_assertion_type=<client_assertion_type>&code_verifier=<code_verifier>

Header: Content-Type: application/x-www-form-urlencoded

Refresh token parameters

The refresh token parameters table describes the parameters required to refresh the access token using the refresh token:

Revoke token

Send a request to the token revocation endpoint: https://login.test.jpmorgan.com/h2w-api/oauth2/token/revoke

Header: Content-Type: application/x-www-form-urlencoded'

Revoke access token parameters

The revoke access token parameters table describes the parameters required to revoke the access token:

Related

• See the FAQs page for answers to common questions and issues encountered during integration.
• Refer to the support page for support information and to report production issues.