Bank payouts testing
Last updated: April 29, 2022
Use the sample requests on this page to test a number of Bank payouts scenarios.
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 |
post
https://api.sandbox.checkout.com/instruments
Header | Value |
---|---|
required |
|
required |
|
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}
1{2"type": "bank_account",3"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",4"id": "src_wmlfc3zyhqzehihu7giusaaawu"5}
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.
post
https://api.sandbox.checkout.com/instruments
Header | Value |
---|---|
required |
|
required |
|
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}
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}
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.
post
https://api.sandbox.checkout.com/instruments
Header | Value |
---|---|
required |
|
required |
|
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}
In the response, you'll notice that the swift_bic
value has been corrected from NWBKGB2TXXX
to NWBKGB2LXXX
.
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}
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
post
https://api.sandbox.checkout.com/instruments
Header | Value |
---|---|
required |
|
required |
|
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}
1{2"request_id": "71ccac67-5018-4917-9446-f2f6f2b8270e",3"error_type": "request_invalid",4"error_codes": ["bank_code_invalid"]5}
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
.
post
https://api.sandbox.checkout.com/instruments
Header | Value |
---|---|
required |
|
required |
|
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}
1{2"type": "bank_account",3"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",4"id": "src_gsd2agaqd2sernz5tpcfv555nq"5}
Include the following quote_id
in your request to trigger the error: qte_mbabizu24mvu3mela5njyhpit4
.
post
https://api.sandbox.checkout.com/payments
Header | Value |
---|---|
required |
|
required |
|
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}
1{2"request_id": "71ccac67-5018-4917-9446-f2f6f2b8270e",3"error_type": "processing_error",4"error_codes": ["quote_expired"]5}
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
post
https://api.sandbox.checkout.com/instruments
Header | Value |
---|---|
required |
|
required |
|
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}
1{2"type": "bank_account",3"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",4"id": "src_ez3bolgy7ggu5bnjsilialkegi"5}
post
https://api.sandbox.checkout.com/payments
Header | Value |
---|---|
required |
|
required |
|
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}
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}
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}
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
post
https://api.sandbox.checkout.com/instruments
Header | Value |
---|---|
required |
|
required |
|
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}
1{2"type": "bank_account",3"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",4"id": "src_vovjchw6exauvjrdzpmfu3sm3y"5}
post
https://api.sandbox.checkout.com/payments
Header | Value |
---|---|
required |
|
required |
|
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}
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}
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}
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
post
https://api.sandbox.checkout.com/instruments
Header | Value |
---|---|
required |
|
required |
|
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}
1{2"type": "bank_account",3"fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q",4"id": "src_ddy3e5xuuilutddqxh5pso75i4"5}
post
https://api.sandbox.checkout.com/payments
Header | Value |
---|---|
required |
|
required |
|
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}
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}
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}
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}