Account holders7

Authorized card users4

Balance accounts5

Balances5

Bank account validation1

Card orders2

Custom payout schedules (sweeps)5

Direct debit mandates4

Grant accounts1

Grant offers2

Manage card PIN3

Manage SCA devices6

Managed payout schedules8

Network tokens2

Payment instrument groups3

Payment instruments9

Platform3

Recurring top ups4

SCA association management3

SCA device management4

Transaction rules4

Transfer limits - balance account level6

Transfer limits - balance platform level4

Transfer routes1

Payment instruments

Update a payment instrument

Updates a payment instrument. Once a payment instrument is already active, you can only update its status. However, for cards created with inactive status, you can still update the balance account associated with the card.

patch/paymentInstruments/{id}

Path parameters

idstring required

The unique identifier of the payment instrument.

Request body

balanceAccountIdstring

The unique identifier of the balance account associated with this payment instrument.

You can only change the balance account ID if the payment instrument has inactive status.

status'active' | 'closed' | 'inactive' | 'suspended'

The status of the payment instrument. If a status is not specified when creating a payment instrument, it is set to active by default. However, there can be exceptions for cards based on the card.formFactor and the issuingCountryCode. For example, when issuing physical cards in the US, the default status is inactive.

Possible values:

active: The payment instrument is active and can be used to make payments.
inactive: The payment instrument is inactive and cannot be used to make payments.
suspended: The payment instrument is suspended, either because it was stolen or lost.
closed: The payment instrument is permanently closed. This action cannot be undone.

statusCommentstring

Comment for the status of the payment instrument.

Required if statusReason is other.

The reason for updating the status of the payment instrument.

Possible values: lost, stolen, damaged, suspectedFraud, expired, endOfLife, accountClosure, other. If the reason is other, you must also send the statusComment parameter describing the status change.

Response

OK - the request has succeeded.

balanceAccountIdstring required

The unique identifier of the balance account associated with the payment instrument.

descriptionstring

Your description for the payment instrument, maximum 300 characters.

idstring required

The unique identifier of the payment instrument.

issuingCountryCodestring required

The two-character ISO 3166-1 alpha-2 country code where the payment instrument is issued. For example, NL or US.

paymentInstrumentGroupIdstring

The unique identifier of the payment instrument group to which the payment instrument belongs.

referencestring

Your reference for the payment instrument, maximum 150 characters.

replacedByIdstring

The unique identifier of the payment instrument that replaced this payment instrument.

replacementOfIdstring

The unique identifier of the payment instrument that is replaced by this payment instrument.

status'active' | 'closed' | 'inactive' | 'suspended'

Possible values:

active: The payment instrument is active and can be used to make payments.
inactive: The payment instrument is inactive and cannot be used to make payments.
suspended: The payment instrument is suspended, either because it was stolen or lost.
closed: The payment instrument is permanently closed. This action cannot be undone.

statusCommentstring

Comment for the status of the payment instrument.

Required if statusReason is other.

The reason for the status of the payment instrument.

Possible values: accountClosure, damaged, endOfLife, expired, lost, stolen, suspectedFraud, transactionRule, other. If the reason is other, you must also send the statusComment parameter describing the status change.

type'bankAccount' | 'card' required

The type of payment instrument.

Possible values: card, bankAccount.

Changes

Changed in 12 of the 51 revisions of this API.31332

Jun 17, 2026v20ec7e1e654c71See the full diff
- ○
  added discriminator to / response property for the response status
  response-property-discriminator-added
May 1, 2026v2a4fab1c7333b3See the full diff
- ○
  added the new optional request property //
  new-optional-request-property
- ○
  added the optional property ////// to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Nov 19, 2025v24cd18d5551af12See the full diff
- ▲
  the response property / became optional for the status
  response-property-became-optional
- ○
  added the new optional request property ///
  new-optional-request-property
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
Sep 12, 2025v2c6628742df826See the full diff
- ○
  added the new optional request property ///
  new-optional-request-property
- ○
  added the new optional request property ///
  new-optional-request-property
- ○
  added the new optional request property ///
  new-optional-request-property
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
Jul 29, 2025v29fede8325f6d2See the full diff
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the optional property / to the response with the status
  response-optional-property-added
Apr 29, 2025v2508e86c65b0b2See the full diff
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
This revision also has 4 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Oct 10, 2024v280dfacd37eec1See the full diff
- ○
  added the optional property / to the response with the status
  response-optional-property-added
Apr 26, 2024v26f1fad79c6c01111See the full diff
- ▲
  the response's property type changed from no type to object for status
  response-property-type-changed
- ●
  removed the optional property ////// from the response with the status
  response-optional-property-removed
- ○
  added the new optional request property //
  new-optional-request-property
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  response property additionalBankAccountIdentifications deprecated
  response-property-deprecated
- ○
  removed from the response property oneOf list for the response status
  response-property-one-of-removed
- ○
  added the required property / to the response with the status
  response-required-property-added
Mar 4, 2024v212b2826f399011See the full diff
- ▲
  added to the response property oneOf list for the response status
  response-property-one-of-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
Feb 22, 2024v28a656ca0245a22See the full diff
- ●
  the /// request property's maxLength was set to 80
  request-property-max-length-set
- ●
  the /// request property's maxLength was set to 80
  request-property-max-length-set
- ○
  added the optional property ///// to the response with the status
  response-optional-property-added
- ○
  added the optional property ///// to the response with the status
  response-optional-property-added

Full history (12 revisions)