Add a payment instrument
Beta
Last updated: March 25, 2026
You must create a payment instrument for each holding currency you specify. The account details are saved securely in the Checkout.com Vault. You receive a unique instrument ID to use in payout requests, instead of entering the bank details every 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 instrumenttype– Set tobank_account.currency– The account's currency, as an ISO 4217 currency codecountry– The account's country, as an ISO 3166 alpha-2 country codeinstrument_details.account_number– The alphanumeric value that identifies the accountinstrument_details.bank_code– The code that identifies the bankdocument.type– Set tobank_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
When you create a payment instrument, 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 to the payouts schedule for that currency. You need to associate any subsequent payment instruments to use as the destination when a payout is made. For more information, see Scheduled payouts.