--- title: "Update an instrument" method: PATCH path: "/instruments/{id}" tags: ["Instruments"] --- # Update an instrument `PATCH /instruments/{id}` ## Request - Base URL: `https://{prefix}.api.sandbox.checkout.com` - URL: `https://{prefix}.api.sandbox.checkout.com/instruments/{id}` - 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) Update the details of a payment instrument. To replace the `metadata` stored with a card or bank account payment instrument, provide the full `metadata` object. You can send a request that only contains `metadata`, without changing any card or bank account details. ## Path parameters - `id` string, required ## Request body - union: The type of instrument to be updated - object: Update bank account details - `type` string: The type of instrument. `card` payment instruments. - `expiry_month` integer: The expiry month of the card - `expiry_year` integer: The expiry year of the card - `name` string: Name of the cardholder - `account_holder` UpdateCardAccountHolder: 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` UpdateCustomerRequest: The customer's details - `id` string: The identifier of an existing customer - `default` boolean: If true, sets this instrument as the default for the customer - `metadata` NullableInstrumentMetadata, nullable: A set of key-value pairs that you can attach to a 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, and booleans are not supported as values. 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: Update bank account details - `type` string: The type of instrument. `bank_account` payment instruments. - `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: The three-letter ISO currency code of the account's currency - `country` string: 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` UpdateCustomerRequest: The customer's details - `id` string: The identifier of an existing customer - `default` boolean: If true, sets this instrument as the default for the customer - `metadata` NullableInstrumentMetadata, nullable: A set of key-value pairs that you can attach to a 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, and booleans are not supported as values. 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: Update bank account details - `type` string: The type of instrument. `sepa` payment instruments. - `instrument_data` object: 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: 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. - object: Update bank account details - `type` string: The type of instrument. `ach` payment instruments. - `instrument_data` object: The details of the bank account - `account_type` 'savings' | 'checking': The type of Direct Debit account - `account_number` string: The account number of the Direct Debit account - `bank_code` string: The bank code of the Direct Debit account - `currency` string: The currency of the account - `country` string: The country of the account - `account_holder` object: 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 - object: Update Bacs Direct Debit account details - `type` string: The type of instrument. `bacs` payment instruments. - `instrument_data` object: The details of the Bacs Direct Debit account. - `account_number` string: The account number of the Bacs Direct Debit account. - `bank_code` string: The sort code of the Bacs Direct Debit account. - `country` string: The country of the account, as an ISO 3166-1 alpha-2 code. - `currency` string: The currency of the account. - `payment_type` 'Recurring' | 'Regular': The type of payment. `Recurring` or `Regular`. - `allow_partial_match` boolean: Whether vault accepted a partial match when looking up the Bacs instrument for the supplied account details. - `account_holder` object: The account holder details - `first_name` string: The first name of the account holder - `last_name` string: The last name of the account holder - `company_name` string: The legal name of a registered company that holds the account. - `billing_address` object: 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: The two-letter ISO country code of the address. - `type` 'individual' | 'corporate': The type of account holder. ## Response `200` Instrument updated successfully - union: The response for type of instrument stored - object: The response for type of instrument stored - `type` 'card', required: The type of instrument - `fingerprint` string, required: A token that can uniquely identify this instrument across all customers - object: The response for type of instrument stored - `type` 'bank_account', required: The type of instrument - `fingerprint` string, required: A token that can uniquely identify this instrument across all customers - object: Update bank account instrument response - `type` 'sepa', required: The underlying instrument type. For instruments created from Checkout.com tokens, this will reflect the type of instrument that was tokenized. - `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: Update bank account instrument response - `type` 'ach', required: The underlying instrument type. For instruments created from Checkout.com tokens, this will reflect the type of instrument that was tokenized. - `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: Update Bacs Direct Debit account instrument response - `type` 'bacs', required: The underlying instrument type. For instruments created from Checkout.com tokens, this will reflect the type of instrument that was tokenized. - `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 - `401`: Unauthorized - `404`: Instrument not found or not associated with client - `409`: A concurrent update conflict occurred. Call the [Get customer details](/tag/Customers#operation/getCustomerDetails) to retrieve the latest state before retrying. - `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)