Skip to main content
Beta version

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

Initiate a return request

In this tutorial, you will learn how to use the Global Payments 2 API to initiate a payments return for receivables using the original incoming payment reference numbers. By the end of this tutorial, you will know how to: 

  • Create a well-formed return request payload.
  • Interpret a successful response.

Before you begin

To use return requests, 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 status request

In this step, you’ll learn how to create and send return requests.

Example of a return using a bank reference number
Curl
curl 
  --request POST \
  --url https://api.payments.jpmorgan.com/payment/v2/payments/returns \
  --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 '{
  "paymentType": "RTP",
  "originalPaymentIdentifiers": {
    "bankReferenceNumber": "ABC12346000"
  },
  "paymentIdentifiers": {
    "endToEndId": "RT202109311350000"
  },
  "country": "BR",
  "returnType": "PARTIAL",
  "value": {
    "amount": "50.00",
    "currency": "BRL"
  },
  "additionalInformation": [
    "OrderNumber:OD-1234000"
  ]
}'

This example shows how to create a client-iniciated return using the payment ID of the original transaction. 

Example of a return using payment ID
Curl
curl 
  --request POST \
  --url https://api.payments.jpmorgan.com/payment/v2/payments/returns \
  --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 '{
  "paymentType": "RTP",
  "originalPaymentIdentifiers": {
    "paymentId": "bre4c092-b90d-4b33-bd19-1a3843370bpt"
  },
  "paymentIdentifiers": {
    "endToEndId": "RT202109311350000"
  },
  "country": "BR",
  "returnType": "PARTIAL",
  "value": {
    "amount": "50.00",
    "currency": "BRL"
  },
  "additionalInformation": [
    "OrderNumber:OD-1234000"
  ]
}'

The following example shows to process a client-iniciated return using the original incoming payments details, including amount, currency, and value date. 

Example of a return using the original incoming payment details
Curl
  --request POST \
  --url https://api.payments.jpmorgan.com/payment/v2/payments/returns \
  --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 '{
  "paymentType": "RTP",
  "originalPaymentIdentifiers": {
    "endToEndId": "RT202109311350000"
    "originalValue": {
       "currency": "BRL",
       "amount": "100.00"
  },
    "valueDate": "2025-04-15",
  },
  "paymentIdentifiers": {
    "endToEndId": "RT202109311350000"
  },
  "country": "BR",
  "returnType": "PARTIAL",
  "value": {
    "amount": "50.00",
    "currency": "BRL"
  },
  "additionalInformation": [
    "OrderNumber:OD-1234000"
  ]
}'

Confirm the response

For all use cases, you should receive a successful response containing a returnId. These values can be used to retrieve the status of your request.

Next steps

 Learn how to retrieve the status of your RTP request.