Pay By Bank

Make a payout

Use payouts when you need to refund or send money back to someone who has made a payment.

Important information to remember about payouts:

A payout must be made based on the ID of an original payment that you have received.
The payout amount cannot exceed the amount of the original payment. Partial payouts are supported.
You can only make a payout request 15 minutes after the initial payment.

Required fields for a payout

To send a payout, you must include the following fields in the request body:

payoutType: Must be either REFUND or WITHDRAWAL.
- REFUND: Return funds for a previous payment. This can be a full or partial payment, up to the full value of the original payment.
- WITHDRAWAL: Move funds for any reason other than refunding. For example, if a customer topped up a payment for a service but now wants to withdraw the money.
payoutReference: Your reference for the generated payout.
sourcePaymentId: The ID of the original payment.

Initiate a payout

To initiate a payout, send the following POST /payouts request.

Sample request

Curl

curl --request POST \
  --url https://api-mock.payments.jpmorgan.com/tsapi/pay-by-bank/v2/payouts \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: ' \
  --data '{
  "payoutType": "REFUND",
  "paymentType": "RTP",
  "payoutAmount": {
    "value": "10.50",
    "currency": "EUR"
  },
  "payoutReference": "Refund 220-1z008",
  "sourcePaymentId": "a14a49b4-b21e-416e-ab8d-c0e57efbd2ea"
}'

The following sample response shows the payout details after a successful request.

Sample response

Json

{
 "id": "0f7d8749-555e-41fc-a947-98bca7f7310b",
 "status": "PENDING",
 "createdAt": "2023-07-24T14:15:22Z",
 "payoutType": "REFUND",
 "paymentType": "RTP",
 "payoutAmount": {
   "value": "10.50",
   "currency": "EUR"
 },
 "payoutReference": "Refund 220-1z008",
 "sourcePaymentId": "a14a49b4-b21e-416e-ab8d-c0e57efbd2ea"
}

Get information about a payout

To get information about a specific payout, including the payment status, use GET /payouts/{id}.

Sample request

Curl

curl --request GET \
  --url https://api-mock.payments.jpmorgan.com/tsapi/pay-by-bank/v2/payouts/id \
  --header 'Accept: application/json'

The following sample response shows the information about a specific payout, including the payment status.

Sample response

Json

{
  "id": "0f7d8749-555e-41fc-a947-98bca7f7310b",
  "status": "PENDING",
  "createdAt": "2023-07-24T14:15:22Z",
  "payoutType": "REFUND",
  "paymentType": "RTP",
  "payoutAmount": {
    "value": "10.50",
    "currency": "EUR"
  },
  "payoutReference": "Refund 220-1z008",
  "sourcePaymentId": "a14a49b4-b21e-416e-ab8d-c0e57efbd2ea"
}

Reference

Fields in a POST /payouts request

Fields in a POST /payouts request
Field	Type	Description	Required
`payoutReference`	String	Reference for the payout.	Y
`sourcePaymentId`	String	Unique identifier of the original payment being refunded.	Y
`amount`	Object	Object encapsulating currency and value details.	Y
`currency`	String	Part of the `amount` object. The currency in which the payout is being made.	Y
`value`	Number	Part of the `amount` object. The payout amount.	Y
`payoutType`	String	Type of payout. Must be `REFUND` or `WITHDRAWAL`.	Y

Fields in the POST /payouts response

Fields in a response to POST /payouts
Field	Type	Description	Required
`id`	String	The unique identifier of the payout.	Y
`payoutReference`	String	Reference for the payout.	Y
`sourcePaymentId`	String	Unique identifier of the source or origin payment transaction.	Y
`amount`	Object	Object encapsulating currency and value details.	Y
`currency`	String	Part of the `amount` object. The currency in which the payout is being made.	Y
`value`	Number	Part of the `amount` object. The payout amount.	Y
`payoutType`	String	Type of payout. Will be `REFUND` or `WITHDRAWAL`.	Y
`status`	Object	Status of the Payout.
`createdAt`	String (Date/Time)	The date and time on which you initiated the payout.

Sequence diagram of API requests for a refund

The following sequence diagram illustrates the API workflow for processing a refund payout.