# Bank payouts testing

Use the examples on this page to test [Enterprise bank payouts](https://www.checkout.com/docs/payments/request-payouts/bank-payouts.md) scenarios.

> **Information**
>
> To check the required bank account fields and format for the country and currency you want to pay out to, see [Bank account field formatting](https://www.checkout.com/docs/payments/request-payouts/bank-payouts/bank-account-field-formatting.md).

---

## Successful payout

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_.

### Create a payout

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments`

### Request example

**United Kingdom**

```json
{
    "source": {
        "type": "currency_account",
        "id": "ca_pt5kvurrlmrube2crzaqdhqbdm"
    },
    "amount": 10,
    "destination": {
        "type": "bank_account",
        "account_type": "current",
        "account_number": "55555555",
        "bank_code": "202015",
        "country": "GB",
        "account_holder": {
            "type": "individual",
            "first_name": "John",
            "last_name": "Smith",
            "country_code": "GB",
            "billing_address": {
                "address_line1": "123 High St.",
                "city": "London",
                "zip": "SW1A 1AA",
                "country": "GB"
            }
        }
    },
    "currency": "GBP",
    "reference": "Payouts - GB Testing",
    "billing_descriptor": {
        "reference": "CKO - payouts - GB Testing"
    },
    "instruction": {
        "purpose": "Payouts - sbox testing"
    },
    "processing_channel_id": "pc_ru45af4clzpeffww6fd5bqlvje"
}
```

### Response example

**Pending**

```json withBorder={false}
{
  "id": "pay_3tbq6nwlgy7epjf6lsafzejlqq",
  "status": "Pending",
  "reference": "Payouts - GB Testing",
  "instruction": {
    	"value_date": "2023-06-12T17:24:55.8771497Z"
 	},
  "_links": {
   	"self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_3tbq6nwlgy7epjf6lsafzejlqq"
    },
    "actions": {
      "href":	"https://{prefix}.api.sandbox.checkout.com/payments/pay_3tbq6nwlgy7epjf6lsafzejlqq/actions"
 	  }
	}
}
```

### Webhook example

**Paid**

```json withBorder={false}
{
  "id": "evt_3x54vfczj45ehjpwbkijbauooq",
  "type": "payment_paid",
  "version": "1.0.33",
  "created_on": "2023-06-12T17:24:55.8771497Z",
  "data": {
    "id": "pay_3tbq6nwlgy7epjf6lsafzejlqq",
    "reference": "Payouts - GB Testing",
    "action_id": "act_3vz6yrnwtr4ezohqbiwdqstk5a",
    "response_code": "10000",
    "response_summary": "Approved",
    "amount": 1000,
    "currency": "GBP",
    "source": {
      "type": "currency_account",
    "card_on_file": false,
      "id": "ca_pt5kvurrlmrube2crzaqdhqbdm"
    },
    "destination": {
      "type": "bank_account",
      "id": "src_osjaqn3jvleelk4kegwmwslmre",
      "fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q"
    },
    "processed_on": "2023-06-12T17:25:55.8771497Z",
    "instruction": {
      "value_date": "2023-06-12TT00:00:00+00:00"
    },
"event_links": {
      "payment": "https://{prefix}.api.sandbox.checkout.com/payments/pay_3tbq6nwlgy7epjf6lsafzejlqq",
      "payment_actions": "https://{prefix}.api.sandbox.checkout.com/payments/pay_3tbq6nwlgy7epjf6lsafzejlqq/actions"
    }
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/workflows/events/evt_3x54vfczj45ehjpwbkijbauooq"
    },
    "subject": {
      "href": "https://{prefix}.api.sandbox.checkout.com/workflows/events/subject/pay_3tbq6nwlgy7epjf6lsafzejlqq"
    },
    "payment": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_3tbq6nwlgy7epjf6lsafzejlqq"
    },
    "payment_actions": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_3tbq6nwlgy7epjf6lsafzejlqq/actions"
    }
  }
}
```

> **Information**
>
> To check the payout's status, call the [Get payment details](https://www.checkout.com/docs/payments/manage-payments/get-payment-details) endpoint.

---

## Validation error

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.

For  error codes are explained in further detail [here](https://www.checkout.com/docs/developer-resources/testing/codes/error-codes).

### Create a payout

`POST` `https://{prefix}.api.sandbox.checkout.com/payments`

### Header parameters

| Header | Value |
| --- | --- |
| `Authorization`<br><br>`required` | `OAuth Bearer access_token` |
| `Content-Type`<br><br>`required` | `application/json` |

### Request example

**France**

```json withBorder={false}
{
  "source": {
    "type": "currency_account",
    "id": "ca_2tnpfwrkkbeexkfnrpqxvpmtuu"
  },
  "amount": 10,
  "destination": {
    "type": "bank_account",
    "account_type": "current",
    "iban": "FR1212345123451234567A12310131231231231",
    "currency": "EUR",
    "country": "FR",
    "account_holder": {
      "type":"individual",
      "first_name": "Jane",
      "last_name": "Smith",
      "country_code": "FR",
      "billing_address": {
        "address_line1": "123 Example St.",
        "city": "Erquy",
        "zip": "22430",
        "country": "FR"
      }
    }
  },
  "currency": "EUR",    
  "reference": "Payouts - FR Testing",
  "billing_descriptor": {
    "reference": "CKO - Payouts - Testing"
  },
  "instruction": {
    "purpose": "Payouts - Testing"
  },
  "processing_channel_id": "pc_zffqslexocpunoetvhxv54m2na"
}
```

### Response example

**422 – Unprocessable Entity**

```json withBorder={false}
{
  "request_id": "dc2b166d-c2c2-469b-960c-c4bb8209b09d",
  "error_type": "processing_error",
  "error_codes": [
    "iban_invalid"
  ]
}
```

---

## Declined payout

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<br>- ES1121000418910000050001<br>- FR9220041010050000005000106 | `Any ending in 50001` |
| `Invalid recipient error` | `50021` | - GB30HLFX11111100050021<br>- ES5321000418910000050021<br>- FR2420041010050000005002106 | `Any ending in 50021` |
| `Processing error` | `50150` | - GB90HLFX11111100050105<br>- ES1621000418910000050105<br>- FR5120041010050000005015006 | `Any ending in 50150` |

The full list of decline codes can be found [here](https://www.checkout.com/docs/developer-resources/codes/api-response-codes.md#50xxx_Card_payout_declines)

### Create a payout

`POST` `https://{prefix}.api.sandbox.checkout.com/payments`

### Header parameters

| Header | Value |
| --- | --- |
| `Authorization`<br><br>`required` | `OAuth Bearer access_token` |
| `Content-Type`<br><br>`required` | `application/json` |

### Request example

**United Kingdom**

```json
{
    "source": {
        "type": "currency_account",
        "id": "ca_pt5kvurrlmrube2crzaqdhqbdm"
    },
    "amount": "10",
    "destination": {
        "type": "bank_account",
        "account_type": "current",
        "account_number": "0050001",
        "bank_code": "202015",
        "country": "GB",
        "account_holder": {
            "type": "individual",
            "first_name": "John",
            "last_name": "Smith",
            "country_code": "GB",
            "billing_address": {
                "address_line1": "123 High St.",
                "city": "London",
                "zip": "SW1A 1AA",
                "country": "GB"
            }
        }
    },
    "currency": "GBP",
    "reference": "Payouts - GB Testing",
    "billing_descriptor": {
        "reference": "Decline"
    },
    "instruction": {
        "purpose": "Payouts - sbox testing"
    },
    "processing_channel_id": "pc_wxqex6b4ciruhopr2lzm3sutiu"
}
```

**France**

```json
{
    "source": {
        "type": "currency_account",
        "id": "ca_pt5kvurrlmrube2crzaqdhqbdm"
    },
    "amount": "10",
    "destination": {
        "type": "bank_account",
        "account_type": "current",
        "iban": "FR5120041010050000005015006",
        "country": "FR",
        "account_holder": {
            "type": "individual",
            "first_name": "Jane",
            "last_name": "Smith",
            "country_code": "FR",
            "billing_address": {
                "address_line1": "123 Example St.",
                "city": "Paris",
                "zip": "70123",
                "country": "FR"
            }
        }
    },
    "currency": "EUR",
    "reference": "Payouts - FR Testing",
    "billing_descriptor": {
        "reference": "Decline"
    },
    "instruction": {
        "purpose": "Payouts - sbox testing"
    },
    "processing_channel_id": "pc_wxqex6b4ciruhopr2lzm3sutiu"
}
```

### Response example with pending

```json withBorder={false}
{
  "id": "pay_wxqex6b4ciruhopr2lzm3sutiu",
  "status": "Pending",
  "reference": "Payouts - GB Testing",
  "instruction": {
    "value_date": "2023-06-12T17:28:45.8845997Z"
 	},
  "_links": {
   	"self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_wxqex6b4ciruhopr2lzm3sutiu"
    },
    "actions": {
      "href":	"https://{prefix}.api.sandbox.checkout.com/payments/pay_wxqex6b4ciruhopr2lzm3sutiu/actions"
    }
  }
}
```

### Webhook with declined response

```json withBorder={false}
{
  "id": "evt_mzaup7g6chbuleywv2kvp4d4i4",
  "type": "payment_declined",
  "version": "1.0.33",
  "created_on": "2023-06-12T17:28:45.8845997Z",
  "data": {
    "id": "pay_wxqex6b4ciruhopr2lzm3sutiu",
    "reference": "Payouts GB - Testing",
    "action_id": "act_5fxa4dxs3v4u3ahyicmksltrgm",
    "response_code": "50001",
    "response_summary": "Compliance error",
    "amount": 10,
    "currency": "GBP",
    "source": {
      "type": "currency_account",
       "card_on_file": false,
      "id": "ca_pt5kvurrlmrube2crzaqdhqbdm"
    },
    "destination": {
      "type": "bank_account",
      "id": "src_2c5qyro5rkbubaisjijhfahnr4",
      "fingerprint": "vnsdrvikkvre3dtrjjvlm5du4q"
    },
    "processed_on": "2023-06-12T17:29:45.8845997Z",
     "event_links": {
      "payment": "https://{prefix}.api.sandbox.checkout.com/payments/pay_wxqex6b4ciruhopr2lzm3sutiu",
      "payment_actions": "https://{prefix}.api.sandbox.checkout.com/payments/pay_wxqex6b4ciruhopr2lzm3sutiu/actions"
    }
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/workflows/events/evt_mzaup7g6chbuleywv2kvp4d4i4"
    },
    "subject": {
      "href": "https://{prefix}.api.sandbox.checkout.com/workflows/events/subject/pay_wxqex6b4ciruhopr2lzm3sutiu"
    },
    "payment": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_wxqex6b4ciruhopr2lzm3sutiu"
    },
    "payment_actions": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_wxqex6b4ciruhopr2lzm3sutiu/actions"
    }
  }
}
```

---

## Payout request with payment instrument

Payouts can be submitted using a pre-configured Checkout instrument (more information [here](https://www.checkout.com/docs/payments/store-and-manage-credentials/store-credentials/payment-instruments)).

### Step 1: Create a payment instrument successfully

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).

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/instruments`

### Header parameters

| Header | Value |
| --- | --- |
| `Authorization`<br><br>`required` | `OAuth Bearer access_token` |
| `Content-Type`<br><br>`required` | `application/json` |

### Request example

```json
{
  "type": "bank_account",
  "iban": "ES9121000418450200051332",
  "currency": "EUR",
  "country": "ES",
  "account_holder": {
    "type": "corporate",
  "company_name": "Acme Corporation",
    "billing_address": {
      "address_line1": "456 Test St.",
      "city": "Madrid",
      "zip": "28009",
      "country": "ES"
    }
  }
}
```

### Response example

```json
{
  "iban": "ES9121000418450200051332",
    "bank": {
        "name": "CaixaBank SA",
        "branch": "Via Roma",
        "address": {
            "address_line1": "456 Test St.",
            "city": "Salou",
            "zip": "43840",
            "country": "ES"
        }
    },
    "type": "bank_account",
    "fingerprint": "tsrjngs7xr3unhvalwacsp6ora",
    "id": "src_anebzamwgj3u5g5uqx72micura"
}
```

### Step 2: Payout request using the above payment instrument

```json
{
  "source": {
        "amount": 10,
        "type": "currency_account",
        "id": "ca_4jewwjd77l6upmxper675vegey"
    },
    "destination": {
        "type": "id",
        "id": "src_anebzamwgj3u5g5uqx72micura"   
    },
    "currency": "EUR",
    "reference": "Payout testing",
    "billing_descriptor": {
        "reference": "Bank Payout Statement Reference or Decline"
    },
    "instruction": {
        "purpose": "Payouts - Testing Instrument"
    },
    "processing_channel_id": "pc_hpswyyx23geezflc2ocz3exn4y"
}
```

---

## Fail to create a payment instrument

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.

### Request example

```json
{
  "type": "bank_account",
  "account_number": "0200051332",
  "bank_code": "000000",
  "currency": "GBP",
  "country": "GB",
  "account_holder": {
  "type": "corporate",
  "company_name": "Acme Corporation",
    "billing_address": {
      "address_line1": "123 High St.",
      "city": "London",
      "zip": "SW1A 1AA",
      "country": "GB"
    }
  }
}
```

### Response example

```json
{
  "request_id": "0fbc247e-22d3-48c2-a422-1b7b9b481288",
    "error_type": "request_invalid",
    "error_codes": [
        "account_number_invalid_format"
    ]
}
```