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
The following libraries are available to manage PCI DSS compliance and automate the collection of risk metadata and lead source data:
- The Rebilly Instruments JavaScript library. This is the most commonly used, and easy to use library. Use this to create quick integrations. For more information, see Integrate self-hosted payment forms.
- The FramePay JavaScript library. Use this library to create highly customized integrations. For more information, see FramePay JavaScript library.
Payment card status
A payment card has a natural lifecycle.
| Status | Description |
|---|---|
inactive or verification-needed | Payment 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. |
active | One 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. |
expired | Payment card expiration date is exceeded. Once the expiration date is reached, a card may be marked as expired by the system. |
deactivated | Payment 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. |
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:
| Status | Description |
|---|---|
inactive or verification-needed | Payment 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 |
active | One 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. |
deactivated | Payment 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
authorizetransaction 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:
- Configure
GatewayAccount.setupInstructionto contain the required action for the specified payment method and payment gateway. - Use a transaction with type
setup. This transaction performs the required actions on the specified payment instrument.