Global Payments

The Global Payments API is a unified API solution for multiple payment types across global markets. This solution offers our clients a unified experience providing multiple payment types that can be initiated through a single API.

For more information refer to the Global Payments guides.

Versioning

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-mock.payments.jpmorgan.com/tsapi/v1/payments

Production endpoints

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

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. This reflects the idempotent nature of the Global Payments API.

Typical behavior

The normal behavior of a duplicate payment provides a 202 HTTP response, and includes the same J.P Morgan generated firmRootId. The webhook response will only send the final status of the original transaction. The following table provides an example sequence of the typical events and API status:

Typical transaction flow
Event	API response
After the original transaction is sent	202 (returned by API) with a unique firmRootId
After the original transaction is completed	Status: Completed or Rejected
After the duplicate transaction is sent	202 (returned by API) with the same firmRootId
After the duplicate transaction is completed	Same response as original transaction

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 firmRootId
After the original transaction is completed	Status: Completed or Rejected
After the duplicate transaction is sent	202 (returned by API) with different firmRootId
After the duplicate transaction is completed (rejected)	Rejected with error code 11000

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/status inquiry to confirm the transaction was received by the bank.

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 the Error Reason Code section.