# Add a bank account as a destination for money

`POST /customers/{id}/payees` · Skerry · Paying out

Add a bank account as a destination for money. The body is the banking partner's external-account fields, passed on as sent: `currency`, `account_type` (`us`, `iban` or `gb`), `account_owner_name` as the bank holds it, `account_owner_type` (business or individual) with `business_name` for a business, `bank_name`, `address` (`street_line_1`, `street_line_2`, `city`, `state`, `postal_code`, and `country` as ISO 3166-1 alpha-3), and the account itself: `account: { routing_number, account_number, checking_or_savings }` for `us`, `iban: { account_number, bic, country }` for `iban`, `account: { sort_code, account_number }` for `gb`. For example `{"currency": "eur", "account_type": "iban", "account_owner_name": "Example GmbH", "account_owner_type": "business", "business_name": "Example GmbH", "address": {"street_line_1": "1 Hauptstrasse", "city": "Berlin", "postal_code": "10115", "country": "DEU"}, "iban": {"account_number": "DE89370400440532013000", "country": "DEU"}}`. Under a mandate that covers `payee.create` the operation allow-list and approval rules apply; if it is held, send the same request again with `Skerry-Approval` once a person has approved it.

- Scope: payees:write
- Moves money: no
- Idempotency: optional
- Untrusted: name, name_check

## Parameters

- `id` (path, required), string
- `Idempotency-Key` (header), string: A repeat with the same key and body returns the first answer instead of acting twice.

## Request body

`application/json`

```json
{
  "type": "object"
}
```

## Responses

- `200`: Success.
- `202`: requires_approval — Not an error: the operation is held for a person. The body names the approval.
- `400`: price_below_minimum — The price is below the smallest single payment for a method (`detail.method`, `detail.minimum`), or has a part of a cent. Set `credit_only`, raise the price, or drop the method.
- `401`: dpop_invalid — The token is bound to a key and the DPoP proof was missing, wrong for this request, or already used.
- `402`: payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms.
- `403`: agent_payment_over_max — The merchant asks for more than `max_amount`. Nothing was signed. `detail.asked_minor` is the lowest price asked, in US cents.
- `404`: not_found — No such object in this project — including one that belongs to somebody else.
- `409`: token_not_issued — A delegated payment token could not be issued ready to use, for instance because the payer would have to act. Nothing was sent to the merchant.
- `429`: too_many_waiters — This key already has as many requests waiting (`?wait=`) as it may. Let one finish, or read without wait.
- `500`: internal_error — Ours. Quote the `request_id` and we can find the call.
- `502`: platform_error — A provider failed. Safe to retry with the same Idempotency-Key.
- `503`: oauth_unavailable — The authorisation server's keys could not be read, so tokens cannot be checked. API keys still work.

## Example

```sh
curl -X POST 'https://api.skerry.xyz/customers/{id}/payees' \
  -H 'Authorization: Bearer $KEY' \
  -H 'Content-Type: application/json' \
  -d '"{ currency, account_type, account_owner_name, account_owner_type, business_name?, bank_name?, address: { street_line_1, street_line_2?, city, state?, postal_code?, country }, account?: { routing_number, account_number, checking_or_savings } | { sort_code, account_number }, iban?: { account_number, bic?, country } }"'
```