Bank payouts testing

Last updated: October 18, 2023

Use the examples on this page to test a number of Bank payouts scenarios.

The paid status indicates that the payout was successful. The example below shows a valid request for merchants contracting with CKO Ltd, paying out to the UK in GBP. The bank details required are bank account then sort code.

Example bank account details for other country/currency combinations can be found here.

post

https://api.sandbox.checkout.com/payments

Header Value

Header	Value
`Authorization` required	`OAuth Bearer access_token`
`Content-Type` required	`application/json`

Authorization

required

OAuth Bearer access_token

Content-Type

required

application/json


1{
2    "source": {
3        "type": "currency_account",
4        "id": "ca_pt5kvurrlmrube2crzaqdhqbdm"
5    },
6    "amount": 10,
7    "destination": {
8        "type": "bank_account",
9        "account_type": "current",
10        "account_number": "55555555",
11        "bank_code": "202015",
12        "country": "GB",
13        "account_holder": {
14            "type": "individual",
15            "first_name": "John",
16            "last_name": "Smith",
17            "country_code": "GB",
18            "billing_address": {
19                "address_line1": "123 High St.",
20                "city": "London",
21                "zip": "SW1A 1AA",
22                "country": "GB"
23            }
24        }
25    },
26    "currency": "GBP",
27    "reference": "Payouts - GB Testing",
28    "billing_descriptor": {
29        "reference": "CKO - payouts - GB Testing"
30    },
31    "instruction": {
32        "purpose": "Payouts - sbox testing"
33    },
34    "processing_channel_id": "pc_ru45af4clzpeffww6fd5bqlvje"
35}


1{
2  "id": "pay_3tbq6nwlgy7epjf6lsafzejlqq",
3  "status": "Pending",
4  "reference": "Payouts - GB Testing",
5  "instruction": {
6        "value_date": "2023-06-12T17:24:55.8771497Z"
7    },
8  "_links": {
9    "self": {
10      "href": "https://api.sandbox.checkout.com/payments/pay_3tbq6nwlgy7epjf6lsafzejlqq"
11    },
12    "actions": {
13      "href":   "https://api.sandbox.checkout.com/payments/pay_3tbq6nwlgy7epjf6lsafzejlqq/actions"
14      }
15    }
16}


1{
2  "id": "evt_3x54vfczj45ehjpwbkijbauooq",
3  "type": "payment_paid",
4  "version": "1.0.33",
5  "created_on": "2023-06-12T17:24:55.8771497Z",
6  "data": {
7    "id": "pay_3tbq6nwlgy7epjf6lsafzejlqq",
8    "reference": "Payouts - GB Testing",
9    "action_id": "act_3vz6yrnwtr4ezohqbiwdqstk5a",
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_pt5kvurrlmrube2crzaqdhqbdm"
18    },
19    "destination": {
20      "type": "bank_account",
21      "id": "src_osjaqn3jvleelk4kegwmwslmre",
22      "fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q"
23    },
24    "processed_on": "2023-06-12T17:25:55.8771497Z",
25    "instruction": {
26      "value_date": "2023-06-12TT00:00:00+00:00"
27    },
28"event_links": {
29      "payment": "https://api.sandbox.checkout.com/payments/pay_3tbq6nwlgy7epjf6lsafzejlqq",
30      "payment_actions": "https://api.sandbox.checkout.com/payments/pay_3tbq6nwlgy7epjf6lsafzejlqq/actions"
31    }
32  },
33  "_links": {
34    "self": {
35      "href": "https://api.sandbox.checkout.com/workflows/events/evt_3x54vfczj45ehjpwbkijbauooq"
36    },
37    "subject": {
38      "href": "https://api.sandbox.checkout.com/workflows/events/subject/pay_3tbq6nwlgy7epjf6lsafzejlqq"
39    },
40    "payment": {
41      "href": "https://api.sandbox.checkout.com/payments/pay_3tbq6nwlgy7epjf6lsafzejlqq"
42    },
43    "payment_actions": {
44      "href": "https://api.sandbox.checkout.com/payments/pay_3tbq6nwlgy7epjf6lsafzejlqq/actions"
45    }
46  }
47}

To check the status of your payout you can use the following Get endpoint.

This is an immediate API response from our validation service that informs you of any payment elements that have not been provided and are required or have an invalid formatting.

All error codes are explained in further detail here.

post

https://api.sandbox.checkout.com/payments

Header Value

Header	Value
`Authorization` required	`OAuth Bearer access_token`
`Content-Type` required	`application/json`

Authorization

required

OAuth Bearer access_token

Content-Type

required

application/json


1{
2  "source": {
3    "type": "currency_account",
4    "id": "ca_2tnpfwrkkbeexkfnrpqxvpmtuu"
5  },
6  "amount": 10,
7  "destination": {
8    "type": "bank_account",
9    "account_type": "current",
10    "iban": "FR1212345123451234567A12310131231231231",
11    "currency": "EUR",
12    "country": "FR",
13    "account_holder": {
14      "type":"individual",
15      "first_name": "Jane",
16      "last_name": "Smith",
17      "country_code": "FR",
18      "billing_address": {
19        "address_line1": "123 Example St.",
20        "city": "Erquy",
21        "zip": "22430",
22        "country": "FR"
23      }
24    }
25  },
26  "currency": "EUR",    
27  "reference": "Payouts - FR Testing",
28  "billing_descriptor": {
29    "reference": "CKO - Payouts - Testing"
30  },
31  "instruction": {
32    "purpose": "Payouts - Testing"
33  },
34  "processing_channel_id": "pc_zffqslexocpunoetvhxv54m2na"
35}


1{
2  "request_id": "dc2b166d-c2c2-469b-960c-c4bb8209b09d",
3  "error_type": "processing_error",
4  "error_codes": [
5    "iban_invalid"
6  ]
7}

To trigger a decline, you can use any of the account numbers or IBANs (depending on the required bank field) in the table below.

Decline Reason	Decline Code	IBANs	Account Number
`Compliance error`	`50001`	GB85HLFX11111100050001 ES1121000418910000050001 FR9220041010050000005000106	`Any ending in 50001`
`Invalid recipient error`	`50021`	GB30HLFX11111100050021 ES5321000418910000050021 FR2420041010050000005002106	`Any ending in 50021`
`Processing error`	`50150`	GB90HLFX11111100050105 ES1621000418910000050105 FR5120041010050000005015006	`Any ending in 50150`

The full list of decline codes can be found here

post

https://api.sandbox.checkout.com/payments

Header Value

Header	Value
`Authorization` required	`OAuth Bearer access_token`
`Content-Type` required	`application/json`

Authorization

required

OAuth Bearer access_token

Content-Type

required

application/json


1{
2    "source": {
3        "type": "currency_account",
4        "id": "ca_pt5kvurrlmrube2crzaqdhqbdm"
5    },
6    "amount": "10",
7    "destination": {
8        "type": "bank_account",
9        "account_type": "current",
10        "account_number": "0050001",
11        "bank_code": "202015",
12        "country": "GB",
13        "account_holder": {
14            "type": "individual",
15            "first_name": "John",
16            "last_name": "Smith",
17            "country_code": "GB",
18            "billing_address": {
19                "address_line1": "123 High St.",
20                "city": "London",
21                "zip": "SW1A 1AA",
22                "country": "GB"
23            }
24        }
25    },
26    "currency": "GBP",
27    "reference": "Payouts - GB Testing",
28    "billing_descriptor": {
29        "reference": "Decline"
30    },
31    "instruction": {
32        "purpose": "Payouts - sbox testing"
33    },
34    "processing_channel_id": "pc_wxqex6b4ciruhopr2lzm3sutiu"
35}


1{
2    "source": {
3        "type": "currency_account",
4        "id": "ca_pt5kvurrlmrube2crzaqdhqbdm"
5    },
6    "amount": "10",
7    "destination": {
8        "type": "bank_account",
9        "account_type": "current",
10        "iban": "FR5120041010050000005015006",
11        "country": "FR",
12        "account_holder": {
13            "type": "individual",
14            "first_name": "Jane",
15            "last_name": "Smith",
16            "country_code": "FR",
17            "billing_address": {
18                "address_line1": "123 Example St.",
19                "city": "Paris",
20                "zip": "70123",
21                "country": "FR"
22            }
23        }
24    },
25    "currency": "EUR",
26    "reference": "Payouts - FR Testing",
27    "billing_descriptor": {
28        "reference": "Decline"
29    },
30    "instruction": {
31        "purpose": "Payouts - sbox testing"
32    },
33    "processing_channel_id": "pc_wxqex6b4ciruhopr2lzm3sutiu"
34}


1{
2  "id": "pay_wxqex6b4ciruhopr2lzm3sutiu",
3  "status": "Pending",
4  "reference": "Payouts - GB Testing",
5  "instruction": {
6    "value_date": "2023-06-12T17:28:45.8845997Z"
7    },
8  "_links": {
9    "self": {
10      "href": "https://api.sandbox.checkout.com/payments/pay_wxqex6b4ciruhopr2lzm3sutiu"
11    },
12    "actions": {
13      "href":   "https://api.sandbox.checkout.com/payments/pay_wxqex6b4ciruhopr2lzm3sutiu/actions"
14    }
15  }
16}


1{
2  "id": "evt_mzaup7g6chbuleywv2kvp4d4i4",
3  "type": "payment_declined",
4  "version": "1.0.33",
5  "created_on": "2023-06-12T17:28:45.8845997Z",
6  "data": {
7    "id": "pay_wxqex6b4ciruhopr2lzm3sutiu",
8    "reference": "Payouts GB - Testing",
9    "action_id": "act_5fxa4dxs3v4u3ahyicmksltrgm",
10    "response_code": "50001",
11    "response_summary": "Compliance error",
12    "amount": 10,
13    "currency": "GBP",
14    "source": {
15      "type": "currency_account",
16       "card_on_file": false,
17      "id": "ca_pt5kvurrlmrube2crzaqdhqbdm"
18    },
19    "destination": {
20      "type": "bank_account",
21      "id": "src_2c5qyro5rkbubaisjijhfahnr4",
22      "fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q"
23    },
24    "processed_on": "2023-06-12T17:29:45.8845997Z",
25     "event_links": {
26      "payment": "https://api.sandbox.checkout.com/payments/pay_wxqex6b4ciruhopr2lzm3sutiu",
27      "payment_actions": "https://api.sandbox.checkout.com/payments/pay_wxqex6b4ciruhopr2lzm3sutiu/actions"
28    }
29  },
30  "_links": {
31    "self": {
32      "href": "https://api.sandbox.checkout.com/workflows/events/evt_mzaup7g6chbuleywv2kvp4d4i4"
33    },
34    "subject": {
35      "href": "https://api.sandbox.checkout.com/workflows/events/subject/pay_wxqex6b4ciruhopr2lzm3sutiu"
36    },
37    "payment": {
38      "href": "https://api.sandbox.checkout.com/payments/pay_wxqex6b4ciruhopr2lzm3sutiu"
39    },
40    "payment_actions": {
41      "href": "https://api.sandbox.checkout.com/payments/pay_wxqex6b4ciruhopr2lzm3sutiu/actions"
42    }
43  }
44}

Payouts can be submitted using a pre-configured Checkout instrument (more information here).

Below is a request example you can use to make a EUR payout to a corporate/business recipient in Spain (if you are a merchant based in EEA).

post

https://api.sandbox.checkout.com/instruments

Header Value

Header	Value
`Authorization` required	`OAuth Bearer access_token`
`Content-Type` required	`application/json`

Authorization

required

OAuth Bearer access_token

Content-Type

required

application/json


1{
2  "type": "bank_account",
3  "iban": "ES9121000418450200051332",
4  "currency": "EUR",
5  "country": "ES",
6  "account_holder": {
7    "type": "corporate",
8  "company_name": "Acme Corporation",
9    "billing_address": {
10      "address_line1": "456 Test St.",
11      "city": "Madrid",
12      "zip": "28009",
13      "country": "ES"
14    }
15  }
16}


1{
2  "iban": "ES9121000418450200051332",
3    "bank": {
4        "name": "CaixaBank SA",
5        "branch": "Via Roma",
6        "address": {
7            "address_line1": "456 Test St.",
8            "city": "Salou",
9            "zip": "43840",
10            "country": "ES"
11        }
12    },
13    "type": "bank_account",
14    "fingerprint": "tsrjngs7xr3unhvalwacsp6ora",
15    "id": "src_anebzamwgj3u5g5uqx72micura"
16}


1{
2  "source": {
3        "amount": 10,
4        "type": "currency_account",
5        "id": "ca_4jewwjd77l6upmxper675vegey"
6    },
7    "destination": {
8        "type": "id",
9        "id": "src_anebzamwgj3u5g5uqx72micura"   
10    },
11    "currency": "EUR",
12    "reference": "Payout testing",
13    "billing_descriptor": {
14        "reference": "Bank Payout Statement Reference or Decline"
15    },
16    "instruction": {
17        "purpose": "Payouts - Testing Instrument"
18    },
19    "processing_channel_id": "pc_hpswyyx23geezflc2ocz3exn4y"
20}

If you use 000000 for the sort code and account number this will result in a validation error and the payment instrument will not be created.


1{
2  "type": "bank_account",
3  "account_number": "0200051332",
4  "bank_code": "000000",
5  "currency": "GBP",
6  "country": "GB",
7  "account_holder": {
8  "type": "corporate",
9  "company_name": "Acme Corporation",
10    "billing_address": {
11      "address_line1": "123 High St.",
12      "city": "London",
13      "zip": "SW1A 1AA",
14      "country": "GB"
15    }
16  }
17}


1{
2  "request_id": "0fbc247e-22d3-48c2-a422-1b7b9b481288",
3    "error_type": "request_invalid",
4    "error_codes": [
5        "account_number_invalid_format"
6    ]
7}

Bank payouts testing

Scenarios

Successful payout

Create a payout

Endpoint

Header parameters

Request example

Response example with pending

Webhook example with paid response

Validation error

Create a payout

Endpoint

Header parameters

Request example

Response example

Declined payout

Create a payout

Endpoint

Header parameters

Request example

Response example with pending

Webhook with declined response

Payout request with payment instrument

Step 1: Create a payment instrument successfully

Endpoint

Header parameters

Request example

Response example

Step 2: Payout request using the above payment instrument

Fail to create a payment instrument

Request example

Response example