Add a payment instrument
Beta

Last updated: September 16, 2026

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

post

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


1{
2  "label": "Bob's Bank Account",
3  "type": "bank_account",
4  "currency": "USD",
5  "country": "US",
6  "default": true,
7  "instrument_details": {
8    "account_number": "12345678",
9    "bank_code": "050389"
10  },
11  "document": {
12    "type": "bank_statement",
13    "file_id": "file_wxglze3wwywujg4nna5fb7ldli"
14  }
15}

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:

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.

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

Information

Request example