Skip to content

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:

TypeCodeCountry

bank_code

050389

_

160008

_

200407

_

250631

_

504044

_

211170318

_

271972572

_

107006444

_

061000104

_

iban

CH7709000000403458523

Switzerland

CH5604835012345678009

Switzerland

CH5104835048708081000

Switzerland

IE64IRCE92050112345678

Ireland

IE70AIBK93006732013730

Ireland

IL620108000000099999999

Israel

IL812471574936472586435

Israel

IL242525955989749798812

Israel

IL897464662155661697787

Israel

IL742117699875433391788

Israel

swift_bic

AUBKPHMM

Philippines

BNORPHMM

Philippines

BOPIPHMMXXX

Philippines

CHBKPHMMXXX

Philippines

LUMIILITXXX

Israel

The request

Endpoint

post

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

Header parameters

HeaderValue

Authorization

required

OAuth Bearer access_token

Content-Type

required

application/json

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

HeaderValue

Authorization

required

OAuth Bearer access_token

Content-Type

required

application/json

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

HeaderValue

Authorization

required

OAuth Bearer access_token

Content-Type

required

application/json

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, or 928934723

  • iban: GB33BUZB50701355555552

  • swift_bic: NWBKGB2L, NWBKGB2LXXX, or ABCDPHEF

The request

Endpoint

post

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

Header parameters

HeaderValue

Authorization

required

OAuth Bearer access_token

Content-Type

required

application/json

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, or 504044.
  • iban: IE64IRCE92050112345678, CH5604835012345678009, IE70AIBK93006732013730, or CH5104835048708081000.

Step 1: Create a payment instrument in the Vault

Endpoint

post

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

Header parameters

HeaderValue

Authorization

required

OAuth Bearer access_token

Content-Type

required

application/json

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

HeaderValue

Authorization

required

OAuth Bearer access_token

Content-Type

required

application/json

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

HeaderValue

Authorization

required

OAuth Bearer access_token

Content-Type

required

application/json

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

HeaderValue

Authorization

required

OAuth Bearer access_token

Content-Type

required

application/json

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

HeaderValue

Authorization

required

OAuth Bearer access_token

Content-Type

required

application/json

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

HeaderValue

Authorization

required

OAuth Bearer access_token

Content-Type

required

application/json

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

HeaderValue

Authorization

required

OAuth Bearer access_token

Content-Type

required

application/json

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

HeaderValue

Authorization

required

OAuth Bearer access_token

Content-Type

required

application/json

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
}

On this page

Payment instruments
Successful creation with enriched data
Successful creation with corrected data
Failed attempt
Payout requests
Payout with 'Declined' status
Payout with 'Paid' status
Payout with 'Returned' status