Skip to main content
Beta version available

Discover the Global Payments 2 API, now available in beta!

Global Payments

The Global Payments API is a product that allows for the initiation of multiple payment types across global markets through a single unified API.

For more information, refer to the Global Payments guides.

Versioning

The Global Payments API supports versioning using a prefix in the endpoint URL. This prefix has the following format: vXX, where XX is the version number.  

For example: https://api.payments.jpmorgan.com/payment/v2 

Note

The Payments Developer Portal offers both Global Payments (current) and Global Payments 2 (Beta), available via the left navigation menu.

Production endpoints

Global Payments 2 (Beta)

The Global Payments 2 API has a single point of entry: https://api.payments.jpmorgan.com/payment/v2

Global Payments

The Global Payments API has two endpoints. One is for PCI transactions and the other is for all other types of transactions.

For the security of credit card transactions, anything that uses the Push to Card payment scheme must use the https://api-mtls.merchant.jpmorgan.com/ endpoint. 

For example:

https://api-mtls.merchant.jpmorgan.com/tsapi/v1/payments 

All other Global Payment transactions payment schemes (e.g., Real-Time Payments) will use the https://apigateway.jpmorgan.com/ endpoint.

For example:

https://apigateway.jpmorgan.com/tsapi/v1/payments

Idempotency

Global Payments 2 (Beta)

Idempotency Logic

The Global Payments 2 API supports idempotent processing to safely retry payment requests. Retries can happen for many reasons, such as network failures and connection timeouts. When an acknowledgement for an initiated payment isn't received, the Global Payments 2 API allows for safe resubmissions without the fear of processing the same payment twice. 

In this version, a unique idempotency key can be generated by the user and inserted into a standard HTTP request header used in the API. This optional key allows for a payment request to be safely retried. Idempotency keys are short-lived and valid for up to 24 hours to allow reuse. We recommend the Universally Unique Identifiers (UUIDs) as the standard for idempotency key generation.

If the same idempotency key is used for different payloads, the Global Payments 2 API will respond with the error code HTTP 422 Unprocessable Content. If the same idempotency key is used for the same payload, but sent twice, the API would process only one request and reject the other one, responding with the error code HTTP 409 Conflict. 

Business duplicate checks

Separately from the idempotency key, the endToEndId is used for business duplicate checks. When the same endToEndId is used for different payments, the API callback will respond with a successful HTTP 202 response, which is the status of the original transaction; payment identifiers (endToEndId and paymentId) of the original transaction; and a flag called duplicateRequest.

The following table provides an example sequence of the typical events and API status:

Typical transaction flow

Typical transaction flow
Event API response
After the original transaction is sent 202 (returned by API) with a unique paymentId
After the original transaction is completed Status: Completed or Rejected
After the duplicate transaction is sent 202 (returned by API) with the same paymentId and endToEndId and duplicateRequest flag

Atypical behavior

In rare occurrences, where transactions with the same endToEndId are submitted within a few milliseconds of each other, the following behavior may occur:

Atypical transaction flow
Event API response
After the original transaction is sent 202 (returned by API) with a unique paymentId
After the original transaction is completed Status: Completed or Rejected
After the duplicate transaction is sent 202 (returned by API) with different paymentId
After the duplicate transaction is completed (rejected) Rejected with error code
Tip

  • Wait for a response or timeout prior to resubmission.

  • In the event that no response is provided or there is uncertainty that the payment is a duplicate, execute the GET /payments inquiry to confirm the transaction was received by the bank. 

Global Payments

Duplicate logic

The Global Payments API supports the ability for idempotent calls. This is useful in various scenarios, such as initiating payments or attempting to retry a failed request (for instance, due to network issues). When a payment request is initiated, a successful 202 HTTP response is returned with two fields:

  • endToEndId (client-generated ID)
  • firmRootId (J.P. Morgan-generated ID)

When a duplicate payment is made with the same endToEndId, they will get the same response found in the original payment request.

Error response codes

The Global Payments API uses standard HTTP response codes, and provides additional detail through the error response payload. Further details are provided in: .