Bank payouts

Make seamless payouts to your customer’s bank accounts with Bank payouts. Access local clearing methods globally, circumventing the challenges of international payments and simplifying complex payment infrastructures.

You can send a payout in two ways: (1) use a bank account payment instrument that you have previously created and stored, or (2) use the bank account fields required for the country and currency to which you want to pay out funds.

Use the get bank account field formatting endpoint to retrieve the relevant bank account fields and formatting for the country and currency to which you'll be paying out.

Once you've done that, you can either use those bank account details directly in your payout request, or use them to create a reusable bank account payment instrument, which you can then use in your Bank payout requests.

Request a Bank payout by using the relevant bank account fields or a bank account payment instrument (prefixed by src_). To get a detailed view of all required and optional fields, see our API reference.

post

https://api.checkout.com/payments

Header Value

Header	Value
`Authorization` required	`OAuth Bearer access token`
`Content-Type` required	`application/json`
`Cko-Idempotency-Key` optional	An optional idempotency key for safely retrying payout requests.

Authorization

required

OAuth Bearer access token

Content-Type

required

application/json

Cko-Idempotency-Key

optional

An optional idempotency key for safely retrying payout requests.

Information

See our API reference for the full specification.

Field name	Description
`source` required object	Details about the payout source.
`source.type` required string	The type of source. Set this to `currency_account`.
`source.id` required string	The source identifier. This is prefixed by `ca_`.
`destination` required object	Details about the payout destination.
`destination.type` required object	The type of payout destination. Set this to `id`. Information To create a bank account payment instrument, use our Instruments API.
`destination.id` required string	The bank account payment instrument identifier. This is prefixed by `src_`.
`amount` required integer(>=0)	The amount you want to pay out to the destination account. The exact format depends on the currency. Note You must specify either the destination `amount` or the `source.amount`.
`currency` required string (3 chars)	The three-letter ISO code of the destination currency. The currency should match that of the destination account.
`reference` optional string	An optional reference you can later use to identify this payout.
`billing_descriptor` required object	Details about the billing descriptor.
`billing_descriptor.reference` required string	The reference that is (where possible) displayed on the account holder's statement.
`sender` required object	Details about the sender of the payout's funds. Conditional if sender is not the same as the entity.
`sender.type` required string	The type of sender. This can be `individual` or `corporate`. Conditional if sender is not the same as the entity.
`sender.address` required string	The sender's address.
`sender.reference` required string	The sender's unique ID.
`instruction` optional object	Details about the instruction for payouts to bank accounts.
`instruction.purpose` optional string	An optional description of the payout purpose, for example `Insurance claim` or `Remittance`.
`instruction.scheme` optional string (enum)	The preferred payment scheme or network the bank transfer will be sent through. This can be one of: `local` `instant` `SEPA` Bank details must be in line with the chosen scheme.
`processing_channel_id` required string	The processing channel identifier.

Field name	Description
`source` required object	Details about the payout source.
`source.type` required string	The type of source. Set this to `currency_account`.
`source.id` required string	The source identifier. This is prefixed by `ca_`.
`destination` required object	Details about the payout destination.
`destination.type` required object	The type of payout destination. Set this to `bank_account`. Information To find out which bank account fields are required, use the get bank account field formatting endpoint.
`amount` required integer(>=0)	The amount you want to pay out to the destination account. The exact format depends on the currency. Note You must specify either the destination `amount` or the `source.amount`.
`currency` required string (3 chars)	The three-letter ISO code of the destination currency. The currency should match that of the destination account.
`reference` optional string	An optional reference you can later use to identify this payout.
`billing_descriptor` required object	Details about the billing descriptor.
`billing_descriptor.reference` required string	The reference that is (where possible) displayed on the account holder's statement.
`sender` required object	Details about the sender of the payout's funds. Conditional if the sender is not the same as the entity.
`sender.type` required string	The type of sender. This can be `instrument`, `individual`, or `corporate`. Conditional if the sender is not the same as the entity.
`sender.address` required string	The sender's address.
`sender.reference` required string	The sender's unique ID.
`instruction` optional object	Details about the instruction for payouts to bank accounts.
`instruction.purpose` optional string	An optional description of the payout purpose, for example `Insurance claim` or `Remittance`.
`instruction.scheme` optional string (enum)	The preferred payment scheme or network the bank transfer will be sent through. This can be one of: `local` `instant` `SEPA` Bank details must be in line with the chosen scheme.
`processing_channel_id` required string	The processing channel identifier.


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


1{
2  "source": {
3    "type": "currency_account",
4    "id": "ca_y3oqhf46pyzuxjbcn2giaqnb44"
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 successfully sent, you will receive a 202 response, with the status Pending. If your request was unsuccessful, you will receive a 422 or 429 response containing an error code.

You will then receive a webhook notification indicating the status of your payout


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}

After receiving the response to your payout request, you will get a webhook notification indicating the status of your payout:

If your payout is successful, you will receive a payment_paid webhook, with a 10000 response code and the Approved summary.
If your payout is declined, you will receive a payment_declined webhook with a 50001-50399 response code and a summary explaining the reason for the decline. View the list of response codes.

Information

Use our testing guide to test different payout scenarios.


1{
2  "id": "evt_ooratpvrc4yezkrjjrfohi26te",
3  "type": "payment_paid",
4  "version": "1.0.33",
5  "created_on": "2023-09-20T14:09:04.7926938Z",
6  "data": {
7    "id": "pay_dvxl6j6stpqufkzfgbaahmfrzm",
8    "reference": "PO-215-5721",
9    "action_id": "act_y37vtskjeweuhfy4mhiggxhpgu",
10    "response_code": "10000",
11    "response_summary": "Approved",
12    "amount": 1000,
13    "currency": "GBP",
14    "source": {
15      "type": "currency_account",
16      "card_on_file": false,
17      "id": "ca_y3oqhf46pyzuxjbcn2giaqnb44"
18    },
19    "destination": {
20      "type": "bank_account",
21      "id": "src_vovjchw6exauvjrdzpmfu3sm3y",
22      "fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q"
23    },
24    "processed_on": "2023-09-20T14:09:03.2717864Z",
25    "instruction": {
26      "value_date": "2023-09-20T00:00:00+00:00"
27    },
28    "event_links": {
29      "payment": "https://api.sandbox.checkout.com/payments/pay_dvxl6j6stpqufkzfgbaahmfrzm",
30      "payment_actions": "https://api.sandbox.checkout.com/payments/pay_dvxl6j6stpqufkzfgbaahmfrzm/actions"
31    }
32  },
33  "_links": {
34    "self": {
35      "href": "https://api.sandbox.checkout.com/workflows/events/evt_ooratpvrc4yezkrjjrfohi26te"
36    },
37    "subject": {
38      "href": "https://api.sandbox.checkout.com/workflows/events/subject/pay_dvxl6j6stpqufkzfgbaahmfrzm"
39    },
40    "payment": {
41      "href": "https://api.sandbox.checkout.com/payments/pay_dvxl6j6stpqufkzfgbaahmfrzm"
42    },
43    "payment_actions": {
44      "href": "https://api.sandbox.checkout.com/payments/pay_dvxl6j6stpqufkzfgbaahmfrzm/actions"
45    }
46  }
47}


1{
2  "id": "evt_6ebhaydlc3kepmacp22s5smodq",
3  "type": "payment_declined",
4  "version": "1.0.33",
5  "created_on": "2023-09-20T14:11:19.1324868Z",
6  "data": {
7    "id": "pay_axh4wk2nhjqenlr2vqvm6kxqta",
8    "reference": "PO-215-5721",
9    "action_id": "act_2sgst4337zjurdj7b2fsonxwre",
10    "response_code": "50150",
11    "response_summary": "Processing Error",
12    "amount": 1000,
13    "currency": "GBP",
14    "source": {
15      "type": "currency_account",
16      "card_on_file": false,
17      "id": "ca_y3oqhf46pyzuxjbcn2giaqnb44"
18    },
19    "destination": {
20      "type": "bank_account",
21      "id": "src_ez3bolgy7ggu5bnjsilialkegi",
22      "fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q"
23    },
24    "processed_on": "2023-09-20T14:11:16.9402308Z",
25    "event_links": {
26      "payment": "https://api.sandbox.checkout.com/payments/pay_axh4wk2nhjqenlr2vqvm6kxqta",
27      "payment_actions": "https://api.sandbox.checkout.com/payments/pay_axh4wk2nhjqenlr2vqvm6kxqta/actions"
28    }
29  },
30  "_links": {
31    "self": {
32      "href": "https://api.sandbox.checkout.com/workflows/events/evt_6ebhaydlc3kepmacp22s5smodq"
33    },
34    "subject": {
35      "href": "https://api.sandbox.checkout.com/workflows/events/subject/pay_axh4wk2nhjqenlr2vqvm6kxqta"
36    },
37    "payment": {
38      "href": "https://api.sandbox.checkout.com/payments/pay_axh4wk2nhjqenlr2vqvm6kxqta"
39    },
40    "payment_actions": {
41      "href": "https://api.sandbox.checkout.com/payments/pay_axh4wk2nhjqenlr2vqvm6kxqta/actions"
42    }
43  }
44}

Payout formatting

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

Bank payouts

Step 1: Get bank account field formatting (Optional)

Step 2: Request a payout

Endpoints

Header parameters

Body parameters

Information

Information

Note

Information

Note

Request example

Response examples

Webhooks

Information

Webhook examples

Related topics

Payout formatting