Sign in
Payment instruments

Create a payment instrument

Creates a payment instrument to issue a physical card, a virtual card, or a business account to your user.

For more information, refer to Issue cards or Issue business accounts.

post/paymentInstruments

Request body

balanceAccountIdstring required

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

descriptionstring

Your description for the payment instrument, maximum 300 characters.

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.

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

The status comment provides additional information for the statusReason of the payment instrument.

statusReason'accountClosure' | 'damaged' | 'endOfLife' | 'expired' | 'lost' | 'other' | 'stolen' | 'suspectedFraud' | 'transactionRule'

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.

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'

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

The status comment provides additional information for the statusReason of the payment instrument.

statusReason'accountClosure' | 'damaged' | 'endOfLife' | 'expired' | 'lost' | 'other' | 'stolen' | 'suspectedFraud' | 'transactionRule'

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 13 of the 51 revisions of this API.31337

  • v20ec7e1e654c71See the full diff
    • ○

      added discriminator to additionalBankAccountIdentifications/items/ response property for the response status 200

      response-property-discriminator-added

  • v2a4fab1c7333b3See the full diff
    • ○

      added the new optional request property card/configuration/printLine

      new-optional-request-property

    • ○

      added the optional property additionalBankAccountIdentifications/items/oneOf[IbanAccountIdentification]/bic to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property card/configuration/printLine to the response with the 200 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

  • v24cd18d5551af12See the full diff
    • ▲

      the response property card/number became optional for the status 200

      response-property-became-optional

    • ○

      added the new optional request property card/configuration/bulkAddress/name

      new-optional-request-property

    • ○

      added the optional property card/configuration/bulkAddress/name to the response with the 200 status

      response-optional-property-added

  • v2c6628742df826See the full diff
    • ○

      added the new optional request property card/configuration/bulkAddress/line1

      new-optional-request-property

    • ○

      added the new optional request property card/configuration/bulkAddress/line2

      new-optional-request-property

    • ○

      added the new optional request property card/configuration/bulkAddress/line3

      new-optional-request-property

    • ○

      added the optional property card/configuration/bulkAddress/line1 to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property card/configuration/bulkAddress/line2 to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property card/configuration/bulkAddress/line3 to the response with the 200 status

      response-optional-property-added

  • v29fede8325f6d2See the full diff
    • ○

      added the new optional request property card/usage

      new-optional-request-property

    • ○

      added the optional property card/usage to the response with the 200 status

      response-optional-property-added

  • v2508e86c65b0b2See the full diff
    • ○

      added the optional property replacedById to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property replacementOfId to the response with the 200 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

  • v280dfacd37eec1See the full diff
    • ○

      added the optional property bankAccount/branchNumber to the response with the 200 status

      response-optional-property-added

  • v2f874764bcf8b2See the full diff
    • ○

      added the new optional request property statusComment

      new-optional-request-property

    • ○

      added the optional property statusComment to the response with the 200 status

      response-optional-property-added

  • v26f1fad79c6c01113See the full diff
    • ▲

      the bankAccount response's property type/format changed from / to object/ for status 200

      response-property-type-changed

    • ●

      removed the optional property additionalBankAccountIdentifications/items/oneOf[IbanAccountIdentification]/formFactor from the response with the 200 status

      response-optional-property-removed

    • ○

      added the new optional request property card/deliveryContact/company

      new-optional-request-property

    • ○

      the request property bankAccount/formFactor became nullable

      request-property-became-nullable

    • ○

      the formFactor request property default value physical was added

      request-property-default-value-added

    • ○

      added the optional property bankAccount/accountNumber to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property bankAccount/accountType to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property bankAccount/formFactor to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property bankAccount/iban to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property bankAccount/routingNumber to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property bankAccount/sortCode to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property card/deliveryContact/company to the response with the 200 status

      response-optional-property-added

    • ○

      response property additionalBankAccountIdentifications deprecated

      response-property-deprecated

    • ○

      removed IbanAccountIdentification UKLocalAccountIdentification USLocalAccountIdentification from the bankAccount response property oneOf list for the response status 200

      response-property-one-of-removed

    • ○

      added the required property bankAccount/type to the response with the 200 status

      response-required-property-added

  • v212b2826f399011See the full diff
    • ▲

      added UKLocalAccountIdentification to the bankAccount response property oneOf list for the response status 200

      response-property-one-of-added

    • ○

      added the optional property additionalBankAccountIdentifications to the response with the 200 status

      response-optional-property-added