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

JPMorgan supports idempotent processing of transactions by performing duplicate checks. Global Payments 2 (in beta) has two dimensions of duplicate checks – idempotency and business checks. Global Payments (current version) supports only business duplicate checks.

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.

A unique idempotency key can be generated by the client and inserted into a standard HTTP request header. This optional key allows for a payment request to be safely retried. Idempotency keys are short-lived and may be reused after 24 hours. We recommend a Universally Unique Identifier (UUIDs) for an idempotency key value.

If the same idempotency key is used for different payloads the Global Payments 2 API will respond with an HTTP 422 (Unprocessable Content) status. If the same idempotency key and payload is sent more than once (within the 24 hours window) the initial request is processed and subsequent requests will result in a consistent response; If a subsequent request is made before the first has completed the API will respond with an HTTP 409 (Conflict) status.

API response for a duplicate payment with the same idempotency key on Global Payments 2

Json

{
    "title": "Idempotency Failure",
    "httpStatus": 422,
    "traceId": "3f8c1e2b-7a4d-4b2a-9f3e-8c6d9f1a2b3c",
    "requestId": "7a9d3f1c-5b2e-4c3d-8f7e-9b1a2c3d4e5f",
    "context": [{
            "code": "10106",
            "message": "Idempotency Key must not be reused across different payloads of this operation",
            "field": "Idempotency-Key",
            "location": "HEADER"
        }]
}

Business Duplicate Checks

Separately from the idempotency key, the client-generated endToEndId is used for business duplicate checks. When the same endToEndId is used for different payments, the API callback will respond with details of the original transaction: the endToEndId, paymentId, and a duplicateRequest = True flag.

API response for a duplicate payment on Global Payments 2

Json

{
    "endToEndId": "aBcDeFgHiJkLmNoP",
    "paymentId": "1b2c3d4e-5f6a-7b8c-9d0e-f1a2b3c4d5e6",
    "duplicateRequest": true
}

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

Business Duplicate Checks

The Global Payments API supports duplicate checks using the client-generated endToEndId. When the same endToEndId is used for different payments, the API callback will respond with details of the original transaction: the endToEndId and firmRootId.

Example of API response for a duplicate payment on Global Payments

Json

{
  "paymentInitiationResponse": {
    "firmRootId": "1b2c3d4e-5f6a-7b8c-9d0e-f1a2b3c4d5e6",
    "endToEndId": "aBcDeFgHiJkLmNoP"
  }
}

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: .

Global Payments Status responses and error codes
Global Payments 2 (beta) Status responses and error codes