Skip to main content
Beta version

Welcome to the beta version of the Global Payments 2 API! For the generally available Global Payments API, refer to Global Payments. 

Initiate a Real-Time Payments request

In this tutorial, you will learn how to use the Global Payments API to initiate a Real-Time Payments (RTP) request for several common use cases. By the end of this tutorial, you will know how to:

  • Create a well-formed RTP request payload
  • Interpret a successful response

Before you begin

To use RTP, you will need the following:

  • A registered and fully onboarded Developer Account on the J.P. Morgan Payments Developer Portal.
  • An active project that provides you with the credentials used to make a request.
  • A bank account configured for each country where you want to perform an RTP transaction.

Send a request

RTP request payloads may vary depending on the use case. In this step, you’ll learn how to create and send RTP requests for vendor payments, wallet withdrawals and drawdowns, and merchant payouts.

Tip

RTP requests for the Global Payments API have different required payment parameters depending on the region. The following examples show the minimum required fields for the United States.

Vendor payments

Use RTP to pay vendors for goods and services and reduce costly follow-ups. The following example shows the minimum required fields for a vendor payment in the United States:

Example of a RTP vendor payment request
curl --request POST \
  --url https://api-mock.payments.jpmorgan.com/payment/v2/payments \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 1b036f9c-8c84-4ce6-b1dd-5979472945a1' \
  --header 'Request-Id: 1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p' \
  --data '{
"requestedExecutionDate": "2024-10-15",
  "paymentIdentifiers": {
    "endToEndId": "pl210g9t231r13541130"
  },
  "transferType": "CREDIT",
  "value": {
    "currency": "USD",
    "amount": "500"
  },
  "paymentType": "RTP",
  "debtor": {
    "name": "Paula Smitty",
    "account": {
      "accountNumber": "000678901234567",
      "accountType": "DDA"
    }
  },
  "debtorAgent": {
    "financialInstitutionIds": [
      {
        "id": "021000021",
        "idType": "USABA"
      }
    ]
  },
  "creditor": {
    "account": {
      "accountNumber": "000000034257284"
    },
    "name": "Clint Davos",
    "postalAddress": {
      "addressType\"": "ADDR",
      "streetName": "Cow Hollow",
      "buildingNumber": "65",
      "postalCode": "05483",
      "city": "San Francisco",
      "country": "US",
      "countrySubDivision": "SFO"
    }
  },
  "creditorAgent": {
    "financialInstitutionIds": [
      {
        "id": "071000013",
        "idType": "USABA"
      }
    ]
  },
  "additionalParties": {
    "ultimateDebtor": {
      "name": "Raj Patel",
      "individualIds": [
        {
          "individualId": "001"
        }
      ],
      "postalAddress": {
        "addressType\"": "ADDR",
        "streetName": "Hancock Ave",
        "buildingNumber": "121",
        "city": "Jersey City",
        "postalCode": "07302",
        "country": "US"
      },
      "dateAndPlaceOfBirth": {
        "birthDate": "1984-01-01",
        "city": "Hull",
        "country": "GB"
      }
    }
  },
  "remittanceInformation": {
    "unstructuredInformation": [
      {
        "text": "Payment for rustic vintage furniture"
      }
    ]
  }
}'

Wallet withdrawals and drawdowns

Use RTP to give users immediate access to funds by initiating transfers from digital wallets to bank accounts. This allows for instantaneous wallet drawdowns and withdrawals. 

Before you begin

To enable this use case, you must first integrate the Global Payments API with your wallet ecosystem. Then, when your consumer triggers a wallet push-out request, you receive instant confirmation if the payment is successful.

The following example shows the minimum required fields for a wallet withdrawal request in the United States:

Example of a RTP wallet withdrawal request
curl --request POST \
  --url https://api-mock.payments.jpmorgan.com/payment/v2/payments \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 1b036f9c-8c84-4ce6-b1dd-5979472945a1' \
  --header 'Request-Id: 1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p' \
  --data '{
"requestedExecutionDate": "2023-08-07",
  "paymentIdentifiers": {
    "endToEndId": "6ZUS5JFPLAFRFDM"
  },
  "transferType": "CREDIT",
  "value": {
    "currency": "USD",
    "amount": "1202.08"
  },
  "paymentType": "RTP",
  "debtor": {
    "name": "PLATFORM PROVIDER",
    "account": {
      "accountNumber": "000678901234567"
    }
  },
  "debtorAgent": {
    "financialInstitutionIds": [
      {
        "id": "021000021",
        "idType": "USABA"
      }
    ]
  },
  "creditor": {
    "account": {
      "accountNumber": "000000034257284"
    },
    "name": "John Doe"
  },
  "creditorAgent": {
    "financialInstitutionIds": [
      {
        "id": "063100277",
        "idType": "USABA"
      }
    ]
  }
}'

Merchant payouts

Use RTP to enable instantaneous (“on-demand”) payouts to your platform sellers or merchants, sending their current sales proceeds directly to their bank accounts.

Before you begin

To enable this use case, you must first integrate the Global Payments API with your platform ecosystem. Then, you can trigger payouts to your sellers/vendors according to their settlement cycles or allow them to receive payouts "on-demand". You will receive instant confirmation if payments are successful.

The following example shows the minimum required fields for a merchant payout request in the United States:

Example of a RTP merchant payout request
curl --request POST \
  --url https://api-mock.payments.jpmorgan.com/payment/v2/payments \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 1b036f9c-8c84-4ce6-b1dd-5979472945a1' \
  --header 'Request-Id: 1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p' \
  --data '{
   "requestedExecutionDate": "2023-08-07",
  "paymentIdentifiers": {
    "endToEndId": "6ZUS5JFPLAFRFDM"
  },
  "transferType": "CREDIT",
  "value": {
    "currency": "USD",
    "amount": "1202.08"
  },
  "paymentType": "RTP",
  "debtor": {
    "name": "PLATFORM PROVIDER",
    "account": {
      "accountNumber": "000678901234567"
    }
  },
  "debtorAgent": {
    "financialInstitutionIds": [
      {
        "id": "021000021",
        "idType": "USABA"
      }
    ]
  },
  "creditor": {
    "account": {
      "accountNumber": "000000034257284"
    },
    "name": "John Doe"
  },
  "creditorAgent": {
    "financialInstitutionIds": [
      {
        "id": "063100277",
        "idType": "USABA"
      }
    ]
  }
}'

Confirm the response

For all use cases, you should receive a successful response containing an endToEndId and a paymentId. These values can be used to retrieve the status or payment details of your request.

Example of a successful RTP payment response
Json
{
  "endToEndId": "AD202109311354152",
  "paymentId": "1b036f9c-8c84-4ce6-b1dd-5979472945a1"
}

There are a number of error messages that you may receive when submitting your payment request. The Global Payments API uses standard HTTP response codes and provides additional detail through the error response payload. For more information, see Global Payments 2 status responses and error codes.

Next Steps