Bank payouts testing
Last updated: April 29, 2022
Use the sample requests on this page to test a number of Bank payouts scenarios.
Payment instruments
Successful creation
A successful attempt means that the bank account payment instrument was created and stored in the Vault.
You can trigger this by including one of the following bank codes, IBANs, or SWIFT BICs in your request to create a payment instrument:
Type | Code | Country |
---|---|---|
|
| _ |
| _ | |
| _ | |
| _ | |
| _ | |
| _ | |
| _ | |
| _ | |
| _ | |
|
| Switzerland |
| Switzerland | |
| Switzerland | |
| Ireland | |
| Ireland | |
| Israel | |
| Israel | |
| Israel | |
| Israel | |
| Israel | |
|
| Philippines |
| Philippines | |
| Philippines | |
| Philippines | |
| Israel |
The request
Endpoint
post
https://api.sandbox.checkout.com/instruments
Header parameters
Header | Value |
---|---|
required |
|
required |
|
Request examples
1{2"type": "bank_account",3"account_number": "13654567",4"bank_code": "160008",5"currency": "GBP",6"country": "GB",7"account_holder": {8"first_name": "John",9"last_name": "Smith",10"billing_address": {11"address_line1": "123 High St.",12"city": "London",13"zip": "SW1A 1AA",14"country": "GB"15}16}17}
The response
Response example
1{2"type": "bank_account",3"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",4"id": "src_wmlfc3zyhqzehihu7giusaaawu"5}
Successful creation with enriched data
Sometimes we're able to get more information about the bank account you're trying to store in the Vault, meaning you can store additional fields in the payment instrument, such as the bank name and branch.
You can trigger this by including "iban": "GB29NWBK60161331926819"
in your request to create a payment instrument.
The request
Endpoint
post
https://api.sandbox.checkout.com/instruments
Header parameters
Header | Value |
---|---|
required |
|
required |
|
Request example
1{2"type": "bank_account",3"iban": "GB29NWBK60161331926819",4"currency": "EUR",5"country": "GB",6"account_holder": {7"first_name": "John",8"last_name": "Smith",9"billing_address": {10"address_line1": "123 High St.",11"city": "London",12"zip": "SW1A 1AA",13"country": "GB"14}15}16}
The response
Response example
1{2"type": "bank_account",3"fingerprint": "mucw7ytsz6gulnl7jllv4xbgzq",4"id": "src_qaen3zb3f5fejbqseafxigaopm",5"iban": "GB29NWBK60161331926819",6"swift_bic": "NWBKGB2LXXX",7"bank": {8"name": "Test Bank",9"branch": "Main branch",10"address": {11"address_line1": "Example Place",12"address_line2": "Example Square",13"city": "London",14"zip": "EC2M 4XY",15"country": "GB"16}17}18}
Successful creation with corrected data
Sometimes we're able to correct some of the bank account fields in your payment instrument when you create it.
You can trigger this by including "iban": "GB29NWBK60161331926819"
and "swift_bic": "NWBKGB2TXXX"
in your request to create a payment instrument.
The request
Endpoint
post
https://api.sandbox.checkout.com/instruments
Header parameters
Header | Value |
---|---|
required |
|
required |
|
Request example
1{2"type": "bank_account",3"iban": "GB29NWBK60161331926819",4"swift_bic": "NWBKGB2TXXX",5"currency": "GBP",6"country": "GB",7"account_holder": {8"first_name": "John",9"last_name": "Smith",10"billing_address": {11"address_line1": "123 High St.",12"city": "London",13"zip": "SW1A 1AA",14"country": "GB"15}16}17}
The response
In the response, you'll notice that the swift_bic
value has been corrected from NWBKGB2TXXX
to NWBKGB2LXXX
.
Response example
1{2"type": "bank_account",3"fingerprint": "mucw7ytsz6gulnl7jllv4xbgzq",4"id": "src_p3ogzppc6upernp3sbjxkyo3my",5"iban": "GB29NWBK60161331926819",6"swift_bic": "NWBKGB2LXXX",7"bank": {8"name": "Test Bank",9"branch": "Main branch",10"address": {11"address_line1": "Example Place",12"address_line2": "Example Square",13"city": "London",14"zip": "EC2M 4XY",15"country": "GB"16}17}18}
Failed attempt
A failed attempt means that the bank account payment instrument was not created, owing to some error.
You can trigger this error by including one of the following bank codes, IBANs, or SWIFT BICs in your request when creating a payment instrument:
bank_code
:507013
,000000000
,123456789
, or928934723
iban
:GB33BUZB50701355555552
swift_bic
:NWBKGB2L
,NWBKGB2LXXX
, orABCDPHEF
The request
Endpoint
post
https://api.sandbox.checkout.com/instruments
Header parameters
Header | Value |
---|---|
required |
|
required |
|
Request examples
1{2"type": "bank_account",3"account_number": "13654567",4"bank_code": "507013",5"currency": "GBP",6"country": "GB",7"account_holder": {8"first_name": "John",9"last_name": "Smith",10"billing_address": {11"address_line1": "123 High St.",12"city": "London",13"zip": "SW1A 1AA",14"country": "GB"15}16}17}
The response
Response example
1{2"request_id": "71ccac67-5018-4917-9446-f2f6f2b8270e",3"error_type": "request_invalid",4"error_codes": [5"bank_code_invalid"6]7}
Payout requests
Quote expiry when requesting a payout
A quote expiry error indicates that your FX quote has expired and cannot be used to make a payout. You can trigger this by including one of the following bank codes or IBANs in your request to create a payment instrument:
bank_code
:160008
,200407
,250631
, or504044
.iban
:IE64IRCE92050112345678
,CH5604835012345678009
,IE70AIBK93006732013730
, orCH5104835048708081000
.
Step 1: Create a payment instrument in the Vault
Endpoint
post
https://api.sandbox.checkout.com/instruments
Header parameters
Header | Value |
---|---|
required |
|
required |
|
Request example
1{2"type": "bank_account",3"account_number": "13654567",4"bank_code": "160008",5"currency": "GBP",6"country": "GB",7"account_holder": {8"first_name": "John",9"last_name": "Smith",10"billing_address": {11"address_line1": "123 High St.",12"city": "London",13"zip": "SW1A 1AA",14"country": "GB"15}16}17}
Response example
1{2"type": "bank_account",3"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",4"id": "src_gsd2agaqd2sernz5tpcfv555nq"5}
Step 2: Create a payout
Include the following quote_id
in your request to trigger the error: qte_mbabizu24mvu3mela5njyhpit4
.
Endpoint
post
https://api.sandbox.checkout.com/payments
Header parameters
Header | Value |
---|---|
required |
|
required |
|
Request example
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"sender": {17"type": "instrument",18"reference": "8285282045818"19},20"instruction": {21"purpose": "Wallet Withdrawal",22"quote_id": "qte_mbabizu24mvu3mela5njyhpit4"23}24}
Response example
1{2"request_id": "71ccac67-5018-4917-9446-f2f6f2b8270e",3"error_type": "processing_error",4"error_codes": [5"quote_expired"6]7}
Payout with 'Declined' status
The declined status indicates that the payout has failed. You can trigger this by including one of the following in your request to create a payment instrument:
bank_code
:250631
iban
:IE70AIBK93006732013730
Step 1: Create a payment instrument in the Vault
Endpoint
post
https://api.sandbox.checkout.com/instruments
Header parameters
Header | Value |
---|---|
required |
|
required |
|
Request example
1{2"type": "bank_account",3"account_number": "13654567",4"bank_code": "250631",5"currency": "GBP",6"country": "GB",7"account_holder": {8"first_name": "John",9"last_name": "Smith",10"billing_address": {11"address_line1": "123 High St.",12"city": "London",13"zip": "SW1A 1AA",14"country": "GB"15}16}17}
Response example
1{2"type": "bank_account",3"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",4"id": "src_ez3bolgy7ggu5bnjsilialkegi"5}
Step 2: Create a payout
Endpoint
post
https://api.sandbox.checkout.com/payments
Header parameters
Header | Value |
---|---|
required |
|
required |
|
Request example
1{2"source": {3"type": "currency_account",4"id": "ca_y3oqhf46pyzuxjbcn2giaqnb44"5},6"destination": {7"type": "id",8"id": "src_ez3bolgy7ggu5bnjsilialkegi"9},10"amount": 1000,11"currency": "GBP",12"reference": "PO-215-5721",13"billing_descriptor": {14"reference": "Withdrawal"15},16"sender": {17"type": "instrument",18"reference": "8285282045818"19},20"instruction": {21"purpose": "Wallet Withdrawal",22"quote_id": "qte_xrhaw53z5m6ehbbxz2n6n5lk74"23}24}
Response example
1{2"id": "pay_axh4wk2nhjqenlr2vqvm6kxqta",3"status": "Pending",4"reference": "PO-215-5721",5"instruction": {6"value_date": "2020-06-12T22:24:55.8771497Z"7},8"_links": {9"self": {10"href": "https://api.sandbox.checkout.com/payments/pay_axh4wk2nhjqenlr2vqvm6kxqta"11},12"actions": {13"href": "https://api.sandbox.checkout.com/payments/pay_axh4wk2nhjqenlr2vqvm6kxqta/actions"14}15}16}
Step 3: Payment declined webhook notification
In response, you will receive the following payment_declined
webhook.
1{2"id": "evt_6ebhaydlc3kepmacp22s5smodq",3"type": "payment_declined",4"version": "1.0.3",5"created_on": "2020-06-12T15:20:55.7983215Z",6"data": {7"id": "pay_axh4wk2nhjqenlr2vqvm6kxqta",8"reference": "PO-215-5721",9"action_id": "act_2sgst4337zjurdj7b2fsonxwre",10"response_code": "50001",11"response_summary": "Compliance error",12"amount": 1000,13"currency": "GBP",14"source": {15"type": "currency_account",16"id": "ca_y3oqhf46pyzuxjbcn2giaqnb44"17},18"destination": {19"type": "bank_account",20"id": "src_ez3bolgy7ggu5bnjsilialkegi",21"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q"22},23"processed_on": "2020-06-12T15:20:51.5677679Z"24},25"_links": {26"self": {27"href": "https://api.sandbox.checkout.com/workflows/events/evt_6ebhaydlc3kepmacp22s5smodq"28},29"subject": {30"href": "https://api.sandbox.checkout.com/workflows/events/subject/pay_axh4wk2nhjqenlr2vqvm6kxqta"31}32}33}
Payout with 'Paid' status
The paid status indicates that the payout was successful. You can trigger this by including one of the following in your request to create a payment instrument:
bank_code
:200407
iban
:CH5604835012345678009
Step 1: Create a payment instrument in the Vault
Endpoint
post
https://api.sandbox.checkout.com/instruments
Header parameters
Header | Value |
---|---|
required |
|
required |
|
Request example
1{2"type": "bank_account",3"account_number": "13654567",4"bank_code": "200407",5"currency": "GBP",6"country": "GB",7"account_holder": {8"first_name": "John",9"last_name": "Smith",10"billing_address": {11"address_line1": "123 High St.",12"city": "London",13"zip": "SW1A 1AA",14"country": "GB"15}16}17}
Response example
1{2"type": "bank_account",3"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",4"id": "src_vovjchw6exauvjrdzpmfu3sm3y"5}
Step 2: Create a payout
Endpoint
post
https://api.sandbox.checkout.com/payments
Header parameters
Header | Value |
---|---|
required |
|
required |
|
Request example
1{2"source": {3"type": "currency_account",4"id": "ca_y3oqhf46pyzuxjbcn2giaqnb44"5},6"destination": {7"type": "id",8"id": "src_vovjchw6exauvjrdzpmfu3sm3y"9},10"amount": 1000,11"currency": "GBP",12"reference": "PO-215-5721",13"billing_descriptor": {14"reference": "Withdrawal"15},16"sender": {17"type": "instrument",18"reference": "8285282045818"19},20"instruction": {21"purpose": "Wallet Withdrawal",22"desired_value_date": "2019-09-10T10:11:12Z",23"quote_id": "qte_xrhaw53z5m6ehbbxz2n6n5lk74"24}25}
Response example
1{2"id": "pay_dvxl6j6stpqufkzfgbaahmfrzm",3"status": "Pending",4"reference": "PO-215-5721",5"instruction": {6"value_date": "2020-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}
Step 3: Payment paid webhook notification
In response, you will receive the following payment_paid
webhook.
1{2"id": "evt_ooratpvrc4yezkrjjrfohi26te",3"type": "payment_paid",4"version": "1.0.3",5"created_on": "2020-06-12T17:46:24.4862402Z",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"id": "ca_y3oqhf46pyzuxjbcn2giaqnb44"17},18"destination": {19"type": "bank_account",20"id": "src_vovjchw6exauvjrdzpmfu3sm3y",21"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q"22},23"processed_on": "2020-06-12T17:46:15.2106459Z",24"instruction": {25"value_date": "2020-06-13T05:46:15.2845092Z"26}27},28"_links": {29"self": {30"href": "https://api.sandbox.checkout.com/workflows/events/evt_ooratpvrc4yezkrjjrfohi26te"31},32"subject": {33"href": "https://api.sandbox.checkout.com/workflows/events/subject/pay_dvxl6j6stpqufkzfgbaahmfrzm"34}35}36}
Payout with 'Returned' status
The returned status indicates that the payout failed and has been returned. You can trigger this by including one of the following in your request to create a payment instrument:
bank_code
:504044
iban
:CH5104835048708081000
Step 1: Create a payment instrument in the Vault
Endpoint
post
https://api.sandbox.checkout.com/instruments
Header parameters
Header | Value |
---|---|
required |
|
required |
|
Request example
1{2"type": "bank_account",3"account_number": "13654567",4"bank_code": "504044",5"currency": "GBP",6"country": "GB",7"account_holder": {8"first_name": "John",9"last_name": "Smith",10"billing_address": {11"address_line1": "123 High St.",12"city": "London",13"zip": "SW1A 1AA",14"country": "GB"15}16}17}
Response example
1{2"type": "bank_account",3"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",4"id": "src_ddy3e5xuuilutddqxh5pso75i4"5}
Step 2: Create a payout
Endpoint
post
https://api.sandbox.checkout.com/payments
Header parameters
Header | Value |
---|---|
required |
|
required |
|
Request example
1{2"source": {3"type": "currency_account",4"id": "ca_y3oqhf46pyzuxjbcn2giaqnb44"5},6"destination": {7"type": "id",8"id": "src_ddy3e5xuuilutddqxh5pso75i4"9},10"amount": 1000,11"currency": "GBP",12"reference": "PO-215-5721",13"billing_descriptor": {14"reference": "Withdrawal"15},16"sender": {17"type": "instrument",18"reference": "8285282045818"19},20"instruction": {21"purpose": "Wallet Withdrawal",22"quote_id": "qte_xrhaw53z5m6ehbbxz2n6n5lk74"23}24}
Response example
1{2"id": "pay_tli5tj6y5upe7m4chnunbzjr5q",3"status": "Pending",4"reference": "PO-215-5721",5"instruction": {6"value_date": "2020-06-12T22:29:33.5117845Z"7},8"_links": {9"self": {10"href": "https://api.sandbox.checkout.com/payments/pay_zwju7gzdbvwe5ewlzpjdd7zbla"11},12"actions": {13"href": "https://api.sandbox.checkout.com/payments/pay_zwju7gzdbvwe5ewlzpjdd7zbla/actions"14}15}16}
Step 3: Payment paid webhook notification
In response, you will receive the following payment_paid
webhook.
1{2"id": "evt_ooratpvrc4yezkrjjrfohi26te",3"type": "payment_paid",4"version": "1.0.3",5"created_on": "2020-06-12T17:46:24.4862402Z",6"data": {7"id": "pay_tli5tj6y5upe7m4chnunbzjr5q",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"id": "ca_y3oqhf46pyzuxjbcn2giaqnb44"17},18"destination": {19"type": "bank_account",20"id": "src_ddy3e5xuuilutddqxh5pso75i4",21"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q"22},23"processed_on": "2020-06-12T17:46:15.2106459Z",24"instruction": {25"value_date": "2020-06-13T05:46:15.2845092Z"26}27},28"_links": {29"self": {30"href": "https://api.sandbox.checkout.com/workflows/events/evt_ooratpvrc4yezkrjjrfohi26te"31},32"subject": {33"href": "https://api.sandbox.checkout.com/workflows/events/subject/pay_tli5tj6y5upe7m4chnunbzjr5q"34}35}36}
Step 4: Payment returned webhook notification
You will then receive the following payment_returned
webhook.
1{2"id": "evt_djb3apm54d2ehg2pt4kmtlrfqu",3"type": "payment_returned",4"version": "1.0.3",5"created_on": "2020-06-12T17:44:34.2986234Z",6"data": {7"id": "pay_tli5tj6y5upe7m4chnunbzjr5q",8"reference": "PO-215-5721",9"action_id": "act_aw2a5iw4qgau7hekeiwjd3yjiy",10"response_code": "50401",11"response_summary": "Bank details invalid",12"amount": 1000,13"currency": "GBP",14"source": {15"type": "currency_account",16"id": "ca_y3oqhf46pyzuxjbcn2giaqnb44"17},18"destination": {19"type": "bank_account",20"id": "src_ddy3e5xuuilutddqxh5pso75i4",21"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q"22},23"processed_on": "2020-06-12T17:44.34Z"24},25"_links": {26"self": {27"href": "https://api.sandbox.checkout.com/workflows/events/evt_djb3apm54d2ehg2pt4kmtlrfqu"28},29"subject": {30"href": "https://api.sandbox.checkout.com/workflows/events/subject/pay_tli5tj6y5upe7m4chnunbzjr5q"31}32}33}