Last updated
These docs are intended for a developer audience.Dismiss

Payment instruments

A payment instrument is a term which describes any means of making a digital payment, such as: credit cards, debit cards, direct debits, payment service providers, and digital wallets.

A payment instrument is not a resource. It is a term used to describe a specific set of resources, such as payment cards and bank accounts.

Lifecycle

Use the following libraries to manage PCI DSS compliance and automate the collection of risk metadata and lead source data:

Payment card status

A payment card has a natural lifecycle.

StatusDescription
inactive or verification-neededPayment card is registered but has not completed a payment transaction. A card starts in an inactive state. The card remains in an inactive state if no transactions are processed against the card, including authorizations.
activeOne or more payments have been completed using the payment card. When a successful transaction is processed against the card, the card moves to an active state.
expiredPayment card expiration date is exceeded. Once the expiration date is reached, a card may be marked as expired by the system.
deactivatedPayment card is removed and is no longer valid, or is deactivated. Once deactivated, no further charges can be made against the card. The card cannot be re-activated.
first successful transaction
Inactive
Active
Expired
Deactivated

Default card

Inactive or an active cards can be set as the default payment card for a subscription. If set, all subscription renewal charges for the subscriber are made against the default card.

Alternative methods status

Alternative, bank account, PayPal, and Khelocard lifecycle statuses:

StatusDescription
inactive or verification-neededPayment instrument is registered but has not completed a payment transaction. The payment instrument remains in an inactive state if no transactions are processed against it, including authorizations
activeOne or more payments have been completed using the payment instrument. When a successful transaction is processed against the payment instrument, the payment instrument moves to an active state.
deactivatedPayment instrument is removed, or is deactivated, and is no longer valid. Once deactivated, no further charges can be made against the payment instrument. The payment instrument cannot be re-activated.

Usage

Payment instruments are defined in the paymentInstrument object. A customer may have a default or primary payment instrument. For more information, see Payment instruments.

Not all payment instruments are suitable for recurring autopay transactions.

Payment instrument object example

{
  "method": "payment-card",
  "paymentInstrumentId": "<id generated by API>"
}

Store for future use

To store payment instruments for future use, before they are used, the following actions may be required:

  • Post an authorize transaction with the selected payment instrument, particularly for payment cards. You may also be required to void the authorizing transaction.
  • Perform Strong Customer Authentication (SCA), particularly for 3DS authorization.

Each payment method and gateway has different setup requirements, to create a uniform setup:

  1. Configure GatewayAccount.setupInstruction to contain the required action for the specified payment method and payment gateway.
  2. Use a transaction with type setup. This transaction performs the required actions on the specified payment instrument.