# 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](/docs/pci-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 embedded payment forms](/docs/dev-docs/get-started-integrate-payments).
- The FramePay JavaScript library. Use this library to create highly customized integrations. For more information, see [FramePay JavaScript library](/docs/dev-docs/framepay).


### 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. |



```mermaid
graph LR;
    id1(Inactive)-- first successful transaction -->id2(Active);
    id2(Active)-->id3(Expired);
    id2(Active)-->id4(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:

| 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](/docs/dev-docs/api/payment-instruments/).

Not all payment instruments are suitable for recurring autopay transactions.

### Payment instrument object example


```json
{
  "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.