Bank payouts testing

Last updated: April 29, 2022

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": "Michael",
16            "last_name": "Scott",
17            "country_code": "GB",
18            "billing_address": {
19                "address_line1": "The Office",
20                "city": "London",
21                "zip": "N17BQ",
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": " Asterix",
16      "last_name": " the Gaul",
17      "country_code": "FR",
18      "billing_address": {
19        "address_line1": "Rue de Plaine Garenne",
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": "Michael",
16            "last_name": "Scott",
17            "country_code": "GB",
18            "billing_address": {
19                "address_line1": "The Office",
20                "city": "London",
21                "zip": "N17BQ",
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": "Michael",
15            "last_name": "Scott",
16            "country_code": "FR",
17            "billing_address": {
18                "address_line1": "The Office",
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": "The Office Ltd.",
9    "billing_address": {
10      "address_line1": "C. de Jorge Juan, 106",
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": "Via Roma 9",
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": "Your reference here",
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": "The Office Ltd.",
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}

We've made some changes to our API

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