# Add a payment instrument

A sub-entity must create a payment instrument for each of its holding currencies. The account details they provide for each payment instrument are stored securely in the Checkout.com [Vault](https://www.checkout.com/docs/payments/store-and-manage-credentials.md). In return, the sub-entity receives a unique payment instrument ID that they can reuse in payout requests, without having to enter their full account details each time.

Call the [Add a payment instrument](https://api-reference.checkout.com/tag/Payment-instruments/#operation/addPlatformsPaymentInstrument) endpoint, and provide the sub-entity ID as the `{id}` path parameter.

In the request body, provide the following:

- `label` – Your reference for the payment instrument
- `type` – Set to `bank_account`.
- `currency` – The account's currency, as an ISO 4217 currency code
- `country`– The account's country, as an ISO 3166 alpha-2 country code
- `instrument_details.account_number` – The alphanumeric value that identifies the account
- `instrument_details.bank_code` – The code that identifies the bank
- `document.type`– Set to `bank_statement`.
- `document.file_id`– The file ID of the document uploaded when adding bank account details

If you're using a SEPA account, see the [API reference](https://api-reference.checkout.com/tag/Payment-instruments/#operation/addPlatformsPaymentInstrument) for more information.

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/accounts/entities/{id}/payment-instruments`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/accounts/entities/{id}/payment-instruments`

### Request example

```json
{
  "label": "Bob's Bank Account",
  "type": "bank_account",
  "currency": "USD",
  "country": "US",
  "default": true,
  "instrument_details": {
    "account_number": "12345678",
    "bank_code": "050389"
  },
  "document": {
    "type": "bank_statement",
    "file_id": "file_wxglze3wwywujg4nna5fb7ldli"
  }
}
```
When a payment instrument is created, it automatically goes through a due diligence verification process.
It must successfully pass the verification process before you can proceed to the next step.

When the result is available, you receive one of the following webhooks:
- [Payment instrument verification passed](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/payment_instrument_verification_passed.md)
- [Payment instrument verification failed](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/payment_instrument_verification_failed.md)

The first payment instrument added for a specific currency is automatically associated with the payouts schedule for that currency. Your sub-entity must associate any subsequent payment instruments to use as the destination when a payout is made. For more information, see [Schedule a payout](https://www.checkout.com/docs/platforms/for-saas/process-sub-entity-payouts/process-sub-entity-bank-payouts.md#Schedule_a_payout).

After creating a payment instrument, you can perform the following actions on behalf of your sub-entity:

- [Retrieve the payment instrument details](https://api-reference.checkout.com/tag/Payment-instruments/#operation/getPlatformsPaymentInstrument)
- [Update the payment instrument details](https://api-reference.checkout.com/tag/Payment-instruments/#operation/updatePlatformsPaymentInstrument)
- [Fetch all payment instruments for a sub-entity](https://api-reference.checkout.com/tag/Payment-instruments/#operation/queryPlatformsPaymentInstruments)