--- title: "Create an instrument" method: POST path: "/instruments" tags: ["Instruments"] --- # Create an instrument `POST /instruments` ## Request - Base URL: `https://{prefix}.api.sandbox.checkout.com` - URL: `https://{prefix}.api.sandbox.checkout.com/instruments` - Auth: one of: - OAuth 2 - Client credentials - Token URL: `string` scopes: `vault`, `vault:instruments` - API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) Create a payment instrument like card, bank, ach or sepa to use for future payments and payouts. The parameters you need to provide when creating a bank account payment instrument depend on the account's country and currency. See the payout formatting documentation, or use the `GET /validation/bank-accounts/{country}/{currency}` endpoint. ## Request body - union: The type of instrument to be stored - object: Store bank account details - `type` 'bank_account', required: The type of instrument. `bank_account` payment instruments only support payouts. - `account_type` 'savings' | 'current' | 'cash': The type of account - `account_number` string: Number (which can contain letters) that identifies the account - `bank_code` string: Code that identifies the bank - `branch_code` string: Code that identifies the bank branch - `iban` string: Internationally agreed standard for identifying bank account - `bban` string: The combination of bank code and/or branch code and account number - `swift_bic` string: 8 or 11 character code which identifies the bank or bank branch - `currency` string, required: The three-letter ISO currency code of the account's currency - `country` string, required: The two-letter ISO country code of where the account is based - `processing_channel_id` string: The ID of the primary processing channel this instrument is intended to be used for - `account_holder` union: The bank account holder details. Having accurate and complete data improves payout performance (increases success rate and the prevents delays). - object: Store a previously tokenized instrument - `type` 'individual' | 'corporate' | 'government', required: The type of the legal account holder. - `first_name` string, required: The legal first name of the account holder. - `last_name` string, required: The legal last name of the account holder. - `tax_id` string: The legal account holder's tax number or reference. - `date_of_birth` string, date: The account holder's date of birth in a `YYYY-MM-DD` format. Strongly recommended where available. - `country_of_birth` string: The two-letter ISO country code of the account holder's country of birth. - `residential_status` 'resident' | 'non_resident': The account holder's residential status. - `billing_address` Address, required - `address_line1` string: The first line of the address. - `address_line2` string: The second line of the address.

For SEPA payments, this value has a maximum length of 10 characters. - `city` string: The address city. - `state` string: The state or province of the address country ISO 3166-2 code (for example: CA for California in the United States). - `zip` string: The address zip or postal code. - `country` string: The two-letter ISO country code of the address. - `phone` PhoneNumber: A phone number - `country_code` string: The international country calling code. Required if `source.type` is `tamara`. - `number` string: The phone number. Required if `source.type` is `tamara`. - `identification` object: The account holder's government document identification. For example, the social security number (SSN). - `type` string: The document type - `issuing_country` string: The country where the document was issued - `number` string: The document number - object: Store a previously tokenized instrument - `type` 'individual' | 'corporate' | 'government', required: The type of the legal account holder. - `company_name` string, required: The full legal name of a registered company that holds the account. - `tax_id` string: The legal account holder's tax number or reference. - `billing_address` Address - `address_line1` string: The first line of the address. - `address_line2` string: The second line of the address.

For SEPA payments, this value has a maximum length of 10 characters. - `city` string: The address city. - `state` string: The state or province of the address country ISO 3166-2 code (for example: CA for California in the United States). - `zip` string: The address zip or postal code. - `country` string: The two-letter ISO country code of the address. - object: Store a previously tokenized instrument - `type` 'individual' | 'corporate' | 'government', required: The type of the legal account holder. - `company_name` string, required: The full legal name of a registered company that holds the account. - `tax_id` string: The legal account holder's tax number or reference. - `billing_address` Address - `address_line1` string: The first line of the address. - `address_line2` string: The second line of the address.

For SEPA payments, this value has a maximum length of 10 characters. - `city` string: The address city. - `state` string: The state or province of the address country ISO 3166-2 code (for example: CA for California in the United States). - `zip` string: The address zip or postal code. - `country` string: The two-letter ISO country code of the address. - `bank` BankDetails: Details of the bank - `name` string: The bank's name - `branch` string: The bank branch's name - `address` Address - `address_line1` string: The first line of the address. - `address_line2` string: The second line of the address.

For SEPA payments, this value has a maximum length of 10 characters. - `city` string: The address city. - `state` string: The state or province of the address country ISO 3166-2 code (for example: CA for California in the United States). - `zip` string: The address zip or postal code. - `country` string: The two-letter ISO country code of the address. - `customer` StoreCustomerInstrumentRequest: The customer's details - `id` string: The identifier of an existing customer - `email` string, email: An optional email address to associate with the customer - `name` string: The customer's name. This will only set the name for *new* customers. - `phone` PhoneNumber: A phone number - `country_code` string: The international country calling code. Required if `source.type` is `tamara`. - `number` string: The phone number. Required if `source.type` is `tamara`. - `default` boolean: If true, this instrument will become the default for the customer. If a *new* customer is created as a result of this request, the instrument will automatically be the default. - `metadata` InstrumentMetadata: A set of key-value pairs that you can attach to a card token or payment instrument to store your own references, such as a customer document number or partner reference. You can include a maximum of 20 key-value pairs. Each key must be between 1 and 100 characters long, and each value can be up to 100 characters long. Keys and values must be strings. Nested objects, arrays, numbers, booleans, and `null` values are not supported. Metadata is stored encrypted, and is returned exactly as you provided it. Keys are case-sensitive. Do not store card details, credentials, or personal data you do not have consent to store in metadata. - object: Details of the token to store. - `type` 'card', required: The type of instrument. - `number` string, pan, required: The card number. - `expiry_month` integer, required: The card's expiration month. - `expiry_year` integer, required: The card's expiration year. - `name` string: The cardholder's name. - `account_holder` StoreAccountHolderTokenRequest: The account holder details - `first_name` string: The first name of the account holder - `last_name` string: The last name of the account holder - `billing_address` Address - `address_line1` string: The first line of the address. - `address_line2` string: The second line of the address.

For SEPA payments, this value has a maximum length of 10 characters. - `city` string: The address city. - `state` string: The state or province of the address country ISO 3166-2 code (for example: CA for California in the United States). - `zip` string: The address zip or postal code. - `country` string: The two-letter ISO country code of the address. - `phone` PhoneNumber: A phone number - `country_code` string: The international country calling code. Required if `source.type` is `tamara`. - `number` string: The phone number. Required if `source.type` is `tamara`. - `customer` StoreCustomerInstrumentRequest: The customer's details - `id` string: The identifier of an existing customer - `email` string, email: An optional email address to associate with the customer - `name` string: The customer's name. This will only set the name for *new* customers. - `phone` PhoneNumber: A phone number - `country_code` string: The international country calling code. Required if `source.type` is `tamara`. - `number` string: The phone number. Required if `source.type` is `tamara`. - `default` boolean: If true, this instrument will become the default for the customer. If a *new* customer is created as a result of this request, the instrument will automatically be the default. - `entity_id` string: The client entity, used for billing purposes. If you do not provide an `entity_id`, you must provide a `processing_channel_id` instead. - `processing_channel_id` string: The processing channel, used for billing purposes. If you do not provide a `processing_channel_id`, you must provide an `entity_id` instead. - `network_token` ProvisionNetworkToken: Provision network token details - `provision` boolean: Indicates whether a network token should be provisioned or not. If you do not pass the provision field, the default value will be set as false. - `metadata` InstrumentMetadata: A set of key-value pairs that you can attach to a card token or payment instrument to store your own references, such as a customer document number or partner reference. You can include a maximum of 20 key-value pairs. Each key must be between 1 and 100 characters long, and each value can be up to 100 characters long. Keys and values must be strings. Nested objects, arrays, numbers, booleans, and `null` values are not supported. Metadata is stored encrypted, and is returned exactly as you provided it. Keys are case-sensitive. Do not store card details, credentials, or personal data you do not have consent to store in metadata. - object: Store token details - `type` 'token', required: The type of instrument - `token` string, required: The Checkout.com token - `account_holder` StoreAccountHolderTokenRequest: The account holder details - `first_name` string: The first name of the account holder - `last_name` string: The last name of the account holder - `billing_address` Address - `address_line1` string: The first line of the address. - `address_line2` string: The second line of the address.

For SEPA payments, this value has a maximum length of 10 characters. - `city` string: The address city. - `state` string: The state or province of the address country ISO 3166-2 code (for example: CA for California in the United States). - `zip` string: The address zip or postal code. - `country` string: The two-letter ISO country code of the address. - `phone` PhoneNumber: A phone number - `country_code` string: The international country calling code. Required if `source.type` is `tamara`. - `number` string: The phone number. Required if `source.type` is `tamara`. - `customer` StoreCustomerInstrumentRequest: The customer's details - `id` string: The identifier of an existing customer - `email` string, email: An optional email address to associate with the customer - `name` string: The customer's name. This will only set the name for *new* customers. - `phone` PhoneNumber: A phone number - `country_code` string: The international country calling code. Required if `source.type` is `tamara`. - `number` string: The phone number. Required if `source.type` is `tamara`. - `default` boolean: If true, this instrument will become the default for the customer. If a *new* customer is created as a result of this request, the instrument will automatically be the default. - `metadata` InstrumentMetadata: A set of key-value pairs that you can attach to a card token or payment instrument to store your own references, such as a customer document number or partner reference. You can include a maximum of 20 key-value pairs. Each key must be between 1 and 100 characters long, and each value can be up to 100 characters long. Keys and values must be strings. Nested objects, arrays, numbers, booleans, and `null` values are not supported. Metadata is stored encrypted, and is returned exactly as you provided it. Keys are case-sensitive. Do not store card details, credentials, or personal data you do not have consent to store in metadata. - object: Store bank account details - `type` 'sepa', required: The type of instrument. `sepa` payment instruments. - `instrument_data` object, required: The details of the mandate - `type` 'Core' | 'B2B': The type of mandate. - `account_number` string, required: The International Bank Account Number (IBAN) of the account. - `country` string, required: The country of the account. - `currency` string, required: The currency of the account. - `payment_type` 'recurring' | 'regular', required: The type of payment. `recurring` or `regular`. - `mandate_id` string: The mandate ID. If a mandate ID is not provided, a new, random mandate ID will be generated. - `date_of_signature` string, date: The date on which the mandate was signed, in the format 'yyyy-MM-dd'. Required if `mandate_id` is provided. Ignored and set as the current date if `mandate_id` is not provided. - `account_holder` object, required: The account holder details - `first_name` string, required: The first name of the account holder - `last_name` string, required: The last name of the account holder - `billing_address` object, required: The billing address of the account holder - `address_line1` string, required: The first line of the address. - `address_line2` string, required: The street number. If no number, pass "w/n". - `city` string, required: The address city. - `zip` string, required: The address zip/postal code. - `country` string, required: The two-letter ISO country code of the address. - `company_name` string: The legal name of a registered company that holds the account. - `type` 'individual' | 'corporate': The type of account holder. - `customer` StoreCustomerInstrumentRequest: The customer's details - `id` string: The identifier of an existing customer - `email` string, email: An optional email address to associate with the customer - `name` string: The customer's name. This will only set the name for *new* customers. - `phone` PhoneNumber: A phone number - `country_code` string: The international country calling code. Required if `source.type` is `tamara`. - `number` string: The phone number. Required if `source.type` is `tamara`. - `default` boolean: If true, this instrument will become the default for the customer. If a *new* customer is created as a result of this request, the instrument will automatically be the default. - object: Store bank account details - `type` 'ach', required: The type of instrument. `ach` payment instruments. - `instrument_data` object, required: The details of the bank account - `account_type` 'savings' | 'checking', required: The type of Direct Debit account - `account_number` string, required: The account number of the Direct Debit account - `bank_code` string, required: The bank code of the Direct Debit account - `currency` string, required: The currency of the account - `country` string, required: The country of the account - `account_holder` object, required: The account holder details - `first_name` string, required: First name. Required for individual account holder type - `last_name` string, required: Last name. Required for individual account holder type - `company_name` string, required: Company name. Required for corporate account holder type - `type` 'individual' | 'corporate', required: Account holder type - `customer` StoreCustomerInstrumentRequest: The customer's details - `id` string: The identifier of an existing customer - `email` string, email: An optional email address to associate with the customer - `name` string: The customer's name. This will only set the name for *new* customers. - `phone` PhoneNumber: A phone number - `country_code` string: The international country calling code. Required if `source.type` is `tamara`. - `number` string: The phone number. Required if `source.type` is `tamara`. - `default` boolean: If true, this instrument will become the default for the customer. If a *new* customer is created as a result of this request, the instrument will automatically be the default. - object: Store Bacs Direct Debit account details - `type` 'bacs', required: The type of instrument. `bacs` payment instruments. - `account` object, required: The account configuration for the instrument. - `processing_channel_id` string, required: The ID of the processing channel to associate with the instrument. - `instrument_data` object, required: The details of the Bacs Direct Debit account. - `account_number` string, required: The account number of the Bacs Direct Debit account. - `bank_code` string, required: The sort code of the Bacs Direct Debit account. - `country` string, required: The country of the account, as an ISO 3166-1 alpha-2 code. - `currency` string, required: The currency of the account. - `payment_type` 'Recurring' | 'Regular', required: The type of payment. `Recurring` or `Regular`. - `allow_partial_match` boolean: Indicates whether the Bacs instrument is created when account validation returns a partial match. When `true`, the instrument is created on a partial match; when `false`, instrument creation fails on a partial match. - `account_holder` object, required: The account holder details - `first_name` string, required: The first name of the account holder - `last_name` string, required: The last name of the account holder - `billing_address` object, required: The billing address of the account holder - `address_line1` string: The first line of the address. - `address_line2` string: The street number. If no number, pass "w/n". - `city` string: The address city. - `zip` string: The address zip/postal code. - `country` string, required: The two-letter ISO country code of the address. - `customer` StoreCustomerInstrumentRequest: The customer's details - `id` string: The identifier of an existing customer - `email` string, email: An optional email address to associate with the customer - `name` string: The customer's name. This will only set the name for *new* customers. - `phone` PhoneNumber: A phone number - `country_code` string: The international country calling code. Required if `source.type` is `tamara`. - `number` string: The phone number. Required if `source.type` is `tamara`. - `default` boolean: If true, this instrument will become the default for the customer. If a *new* customer is created as a result of this request, the instrument will automatically be the default. ## Response `200` Existing instrument for customer and card details found - union: The response for type of instrument stored - object: Store bank account instrument response - `type` 'bank_account', required: The type of instrument - `id` string, required: The unique identifier of the payment source or destination that can be used later for payments - `fingerprint` string, required: A token that can uniquely identify this instrument across all customers - `customer` CustomerResponse: Stored customer details - `id` string, required: The customer's unique identifier. This can be passed as a source when making a payment. - `email` string: The customer's email address. - `name` string: The customer's name. - `phone` PhoneNumber: A phone number - `country_code` string: The international country calling code. Required if `source.type` is `tamara`. - `number` string: The phone number. Required if `source.type` is `tamara`. - `summary` CustomerSummary: Summary of the customer's transaction history.
Used for risk assessment when `source.type` is `Tamara` - `registration_date` string, date: The date the customer registered. - `first_transaction_date` string, date: The date of the customer's first transaction. - `last_payment_date` string, date: The date of the customer's last payment. - `total_order_count` integer: The total number of orders made by the customer. - `last_payment_amount` number, float: The amount of the customer's last payment. - `is_premium_customer` boolean: Specifies whether the customer is a premium customer. - `is_returning_customer` boolean: Specifies whether the customer is a returning customer. - `lifetime_value` number, float: The customer's lifetime value. This is the total monetary amount that the customer has ordered, in their local currency, excluding the following: - canceled orders - rejected payments - refunded payments - Tamara payments The lifetime value is an indicator of how valuable the relationship with the customer is to your company. - `bank` BankDetails: Details of the bank - `name` string: The bank's name - `branch` string: The bank branch's name - `address` Address - `address_line1` string: The first line of the address. - `address_line2` string: The second line of the address.

For SEPA payments, this value has a maximum length of 10 characters. - `city` string: The address city. - `state` string: The state or province of the address country ISO 3166-2 code (for example: CA for California in the United States). - `zip` string: The address zip or postal code. - `country` string: The two-letter ISO country code of the address. - `swift_bic` string: 8 or 11 character code which identifies the bank or bank branch - `account_number` string: Number (which can contain letters) that identifies the account - `bank_code` string: Code that identifies the bank - `iban` string: Internationally agreed standard for identifying bank account - `metadata` InstrumentMetadata: A set of key-value pairs that you can attach to a card token or payment instrument to store your own references, such as a customer document number or partner reference. You can include a maximum of 20 key-value pairs. Each key must be between 1 and 100 characters long, and each value can be up to 100 characters long. Keys and values must be strings. Nested objects, arrays, numbers, booleans, and `null` values are not supported. Metadata is stored encrypted, and is returned exactly as you provided it. Keys are case-sensitive. Do not store card details, credentials, or personal data you do not have consent to store in metadata. - object: card instrument response - `type` 'card', required: The type of instrument - `id` string, required: The unique identifier of the payment source or destination that can be used later for payments - `fingerprint` string, required: A token that can uniquely identify this instrument across all customers - `expiry_month` integer, required: The expiry month - `expiry_year` integer, required: The expiry year - `scheme` string: The card scheme - `scheme_local` 'cartes_bancaires': The local co-branded card scheme - `last4` string, required: The last four digits of the card number - `bin` string, required: The card issuer's bank identification number (BIN) - `card_type` 'CREDIT' | 'DEBIT' | 'PREPAID' | 'CHARGE': The card type - `card_category` 'CONSUMER' | 'COMMERCIAL': The card category - `issuer` string: The name of the card issuer - `issuer_country` string: The card issuer's country (two-letter ISO code) - `product_id` string: The issuer/card scheme product identifier - `product_type` string: The issuer/card scheme product type - `account_holder` AccountHolderResponse: The account holder details - `first_name` string: The account holder's first name. - `last_name` string: The account holder's last name. - `billing_address` Address - `address_line1` string: The first line of the address. - `address_line2` string: The second line of the address.

For SEPA payments, this value has a maximum length of 10 characters. - `city` string: The address city. - `state` string: The state or province of the address country ISO 3166-2 code (for example: CA for California in the United States). - `zip` string: The address zip or postal code. - `country` string: The two-letter ISO country code of the address. - `phone` PhoneNumber: A phone number - `country_code` string: The international country calling code. Required if `source.type` is `tamara`. - `number` string: The phone number. Required if `source.type` is `tamara`. - `customer` CustomerResponse: Stored customer details - `id` string, required: The customer's unique identifier. This can be passed as a source when making a payment. - `email` string: The customer's email address. - `name` string: The customer's name. - `phone` PhoneNumber: A phone number - `country_code` string: The international country calling code. Required if `source.type` is `tamara`. - `number` string: The phone number. Required if `source.type` is `tamara`. - `summary` CustomerSummary: Summary of the customer's transaction history.
Used for risk assessment when `source.type` is `Tamara` - `registration_date` string, date: The date the customer registered. - `first_transaction_date` string, date: The date of the customer's first transaction. - `last_payment_date` string, date: The date of the customer's last payment. - `total_order_count` integer: The total number of orders made by the customer. - `last_payment_amount` number, float: The amount of the customer's last payment. - `is_premium_customer` boolean: Specifies whether the customer is a premium customer. - `is_returning_customer` boolean: Specifies whether the customer is a returning customer. - `lifetime_value` number, float: The customer's lifetime value. This is the total monetary amount that the customer has ordered, in their local currency, excluding the following: - canceled orders - rejected payments - refunded payments - Tamara payments The lifetime value is an indicator of how valuable the relationship with the customer is to your company. - `network_token` NetworkToken: Network token details - `id` string, required: The network token's unique identifier. - `state` 'active' | 'suspended' | 'inactive': The token status - `metadata` InstrumentMetadata: A set of key-value pairs that you can attach to a card token or payment instrument to store your own references, such as a customer document number or partner reference. You can include a maximum of 20 key-value pairs. Each key must be between 1 and 100 characters long, and each value can be up to 100 characters long. Keys and values must be strings. Nested objects, arrays, numbers, booleans, and `null` values are not supported. Metadata is stored encrypted, and is returned exactly as you provided it. Keys are case-sensitive. Do not store card details, credentials, or personal data you do not have consent to store in metadata. - object: Store bank account instrument response - `type` 'sepa', required: The type of instrument - `id` string, required: The unique identifier of the payment source or destination that can be used later for payments - `fingerprint` string, required: A token that can uniquely identify this instrument across all customers - object: Store bank account instrument response - `type` 'ach', required: The type of instrument - `id` string, required: The unique identifier of the payment source or destination that can be used later for payments - `fingerprint` string, required: A token that can uniquely identify this instrument across all customers - object: Store Bacs Direct Debit account instrument response - `type` 'bacs', required: The type of instrument - `id` string, required: The unique identifier of the payment source or destination that can be used later for payments - `fingerprint` string, required: A token that can uniquely identify this instrument across all customers ## Other responses - `201`: Instrument created successfully - `401`: Unauthorized - `409`: A concurrent update conflict occurred. Retry the request. - `422`: Invalid data was sent - `500`: Internal Error --- [API](https://skmtc.dev/checkout/apis/checkout-com-api-reference.md) - [All operations](https://skmtc.dev/checkout/apis/checkout-com-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/checkout/apis/checkout-com-api-reference/revisions/0f1abdb1c3e9?raw)