Request Bank Payouts

Information

This guide is for Enterprise Bank Payouts. For Bank Payouts to Platform sub-entities, see Process sub-entity Bank Payouts.

Bank Payouts enables you to pay funds out to your customer’s bank accounts. You can access local clearing methods around the world, circumventing the challenges of international payments and simplifying complex payment infrastructures.

In your payout request, you can provide as the destination a bank account payment instrument, or bank account fields.

You provide a reusable bank account payment instrument.

For a new instrument:

Check the required bank account field formatting for the country and currency you want to pay out to.
Create a bank account payment instrument.
Request a payout and provide the instrument ID.

For an existing instrument, request a payout and provide the instrument ID.

Call the Request a payment or payout endpoint.

post

https://api.checkout.com/payments

In the request body, provide the following:

source.id – The sending sub-account's unique identifier, prefixed with ca_.
source.type – Set to currency_account.
destination.type – Set to id.
destination.id – The unique identifier for the bank account payment instrument, prefixed with src_.
amount
currency
billing_descriptor.reference
processing_channel_id

Optionally, if the sender is different to the entity:

sender.type – This can be corporate or individual, or instrument.
sender.reference – The sender's unique identifier.

In the request body, provide the following:

source.id – The sending sub-account's unique identifier, prefixed with ca_.
source.type – Set to currency_account.
destination.type – Set to bank_account.
destination.country
destination.account_type – This can be cash, current, or savings.
Some beneficiary banks do not accept payouts to savings accounts.
amount
currency
billing_descriptor.reference
processing_channel_id
sender.type – This can be corporate, individual, or instrument.
sender.reference – The sender's unique identifier.

Provide the following bank details fields as required for the destination country:

destination.iban
destination.account_number
destination.bank_code
destination.branch_code
destination.bban
destination.swift_bic
destination.account_holder
account_holder.type – This can be corporate or individual.
account_holder.first_name
account_holder.last_name
account_holder.billing_address.address.country
account_holder.billing_address.address_line1 – Required for corporate, not for individual
account_holder.billing_address.address.city – Required for corporate, not for individual
iban – Required in all supported European countries
swift_bic – Required in all supported European countries


1{
2  "source": {
3    "id": "ca_y3oqhf46pyzuxjbcn2giaqnb44",
4    "type": "currency_account"
5  },
6  "destination": {
7    "id": "src_gsd2agaqd2sernz5tpcfv555nq",
8    "type": "id"
9  },
10  "amount": 1000,
11  "currency": "GBP",
12  "reference": "PO-215-5721",
13  "billing_descriptor": {
14    "reference": "Withdrawal"
15  },
16  "instruction": {
17    "scheme": "local"
18  },
19  "processing_channel_id": "pc_hpswyyx23geezflc2ocz3exn4y"
20}


1{
2  "source": {
3    "id": "ca_y3oqhf46pyzuxjbcn2giaqnb44",
4    "type": "currency_account"
5  },
6  "destination": {
7    "type": "bank_account",
8    "account_type": "current",
9    "account_number": "01008704",
10    "bank_code": "110350",
11    "country": "GB",
12    "account_holder": {
13      "type": "individual",
14      "first_name": "John",
15      "last_name": "Smith",
16      "billing_address": {
17        "address_line1": "123 Example St.",
18        "city": "London",
19        "zip": "SW1A 1AA",
20        "country": "GB"
21      }
22    }
23  },
24  "amount": 1000,
25  "currency": "GBP",
26  "reference": "PO-215-5721",
27  "billing_descriptor": {
28    "reference": "Withdrawal"
29  },
30  "instruction": {
31    "purpose": "Withdrawal"
32  },
33  "processing_channel_id": "pc_hpswyyx23geezflc2ocz3exn4y"
34}

If your payout request was sent:

Successfully – You receive a 202 Accepted response, with the status Pending.
Unsuccessfully – You receive a 422 Unprocessable Content or 429 Too Many Requests response containing an error code.


1{
2  "id": "pay_dvxl6j6stpqufkzfgbaahmfrzm",
3  "status": "Pending",
4  "reference": "PO-215-5721",
5  "instruction": {
6    "value_date": "2024-06-12T22:27:42.512594Z"
7  },
8  "_links": {
9    "self": {
10      "href": "https://api.sandbox.checkout.com/payments/pay_dvxl6j6stpqufkzfgbaahmfrzm"
11    },
12    "actions": {
13      "href": "https://api.sandbox.checkout.com/payments/pay_dvxl6j6stpqufkzfgbaahmfrzm/actions"
14    }
15  }
16}


1{
2  "request_id": "0HM5M8APSODP0:00000018",
3  "error_type": "request_invalid",
4  "error_codes": ["source_currency_account_not_found"]
5}


1{
2  "request_id": "0HL80RJLS76I7",
3  "error_type": "request_invalid",
4  "error_codes": ["duplicate_request"]
5}

You can configure your webhook server and subscribe to the following webhooks about the payout's status:

Successful payout – You receive a Payment paid webhook, with "response_code": "10000", and "response_summary": "Approved".
Declined payout – You receive a Payment declined webhook with "response_code": "50001-50399", and a response_summary explaining the reason for the decline.

Information

For more information, see API response codes.

To test different payout scenarios, see Bank Payouts testing.

To view all pending, successful, rejected, and declined bank payouts during a specified time frame, see the Bank Payouts Report.

Bank account field formatting

View the bank account field formatting required to create bank account instruments, or request bank payouts for each supported country.

Request Bank Payouts

Information

How it works

Request a payout

Request examples

Response examples

Webhooks

Information

Testing

Report

Related topics

Bank account field formatting