# Card payment lifecycle

Increase is an issuer processor and supports all flows that cards require. Unlike other Transfers (like ACH), Card Payments do not iterate through a series of statuses. Instead, a `card_payment` is composed of different entries which are closely modeled on the messages Visa sends. Together, these entries encompass the full lifecycle of a cardholder’s experience.

Entries are added to the `card_payment` object as they’re processed and you can receive [webhook Events](/documentation/real-time-decisions#real-time-decisions) when they’re received.

## Card Payment entries

![Card Payment entries](/images/docs-cards-lifecycle.png)

### card_authorization

Most Card Payments start with an authorization. At this stage, no money is moved. Instead, an authorization represents a message from the merchant and their acquirer that says “please hold $X for this transaction, as I intend to settle it later.” Increase creates a Pending Transaction for each authorization to model this hold.

### card_increment

Before a Card Payment clears, an authorization can be updated to a larger amount. This is called an increment, and is useful for things like a [tips at a restaurant](/documentation/card-payment-lifecycle#examples). An authorization can be incremented multiple times. Each time, Increase updates the Pending Transaction to modify the hold on the Account balance.

### card_reversal

An authorization can be either partially or fully reversed before the payment clears. An authorization can also be reversed multiple times. Reversals are often used for reducing holds of larger amounts (for example when checking out of a hotel room). When a reversal is received, Increase updates the Pending Transaction to modify the hold on the Account balance.

Additionally, since issuers often do not decline authorizations for things such as an invalid zip code, a common pattern is to immediately reverse an authorization after it has been created if it comes back with an invalid address validation status.

### card_settlement

Once an authorization clears, Increase creates a `card_settlement` entry to represent the settlement of funds. Predictably, each `card_settlement` maps to a single Transaction. However, there are some less intuitive aspects:

1. An authorization can be cleared multiple times. This means that a Card Payment can include multiple `card_settlement` entries for different amounts, and consequentially also map to multiple Transactions. For example, this is commonly used for settling individual line items from a single order as they ship.

2. An authorization can be cleared for a higher or lower amount than the original. For example, sometimes restaurant bills with tips are cleared for the full amount rather than incrementing the authorization first.

3. Card Payments do not technically need to be authorized. Therefore, it's possible for a `card_settlement` to appear without any prior authorization or notice. This is referred to as a “force push." There are certain rules that allow issuers to dispute these with the reason that they should’ve been authorized first.

### card_refund

When a payment is refunded, Visa sends a separate `card_refund` message. Up until the last few years, refunds were always processed solely with clearing files, meaning they settled without any prior authorization. However, this was not an ideal cardholder experience since refunds often took days to appear on a statement. Recently, Visa started mandating the use of refund authorizations. This helps by showing a positive hold on the funds instantly, which is then turned into an actual refund later. While this is the new standard, refunds are still commonly processed without prior authorization. Visa unfortunately does not clearly associate refunds with the original payment. Therefore a `card_refund` is associated with its own `card_payment` object.

### card_decline

A payment can be declined for multiple reasons, including insufficient funds or incorrect card details (like the expiration). This message does not move funds, but does create a Declined Transaction on the Account. A `card_decline` is a singular, terminal entry.

### card_authorization_expiration

While a transaction can technically be cleared at any time, there are rules for how long it is considered “valid” after which the merchant pays more interchange and the transaction has different dispute rules. Increase follows Visa’s rules for expiring authorizations. For example, we release most authorizations after 7 days but wait 30 days for authorizations related to hotels and rental cars. However, per Visa’s recommendations, you (as an Issuer) can choose to release funds earlier to minimize insufficient funds declines.

### card_validation

A card validation sends a $0 authorization in order to check if a card number (and optionally its CVV2 or cardholder address) is valid. This message does not move funds. A `card_validation` is a singular, terminal entry.

### card_fuel_confirmation

A Fuel Confirmation is a special message sent by Visa explicitly for the use of incrementing holds at gas station pumps. Functionally, a `card_fuel_confirmation` acts like a `card_increment`, however it follows a different technical process. When a user swipes their card at a gas pump, Visa creates an initial $175 authorization. When pumping finishes, instead of directly updating the authorization, Visa sends an “Advice” message with details of the final amount prior to it clearing. Fuel Confirmations predate Card Increments and remain in common use due to a large network of legacy fuel pumps.

## Examples

### A typical payment

![Card flows: Typical payment](/images/docs-cards-flows-typical.png)

1. A user purchases an item for $10.
2. A `card_payment` is created. It includes a `card_authorization` entry for $10.
3. A `pending_transaction` for -$10 is created on the Account to hold the funds.
4. Once the merchant clears the payment, a `card_settlement` entry is created for $10.
5. The `pending_transaction` for -$10 completes.
6. A `transaction` is created for -$10 on the Account.

### An increment (Tipping)

![Card flows: Increments](/images/docs-cards-flows-increment.png)

1. A user purchases a coffee for $5.
2. A `card_payment` is created. It includes a `card_authorization` entry for $5.
3. A `pending_transaction` for -$5 is created on the Account to hold the funds.
4. The user adds a $1 tip.
5. A `card_increment` entry is received for $1.
6. The `pending_transaction` amount updates to -$6.
7. Once the merchant clears the payment, a `card_settlement` entry is created for $6.
8. The `pending_transaction` for -$6 completes.
9. A `transaction` is created for -$6 on the Account.

### A partial reversal (Hotel holds)

![Card flows: Reversals](/images/docs-cards-flows-reversal.png)

1. A user checks into a prepaid hotel. They provide a card for a $100 security deposit.
2. A `card_payment` is created. It includes a `card_authorization` entry for $100.
3. A `pending_transaction` for -$100 is created on the Account to hold the funds.
4. The user accumulates $20 of room charges and checks out.
5. A `card_reversal` entry is received for $80.
6. The `pending_transaction` amount updates to -$20.
7. Once the merchant clears the payment, a `card_settlement` entry is created for $20.
8. The `pending_transaction` for -$20 completes.
9. A `transaction` is created for -$20 on the Account.

### A refund (with authorization)

![Card flows: Refunds](/images/docs-cards-flows-refund.png)

1. A user returns an item for $10.
2. A `card_payment` is created. It includes a `card_authorization` entry for -$10.
3. A `pending_transaction` for +$10 is created to instantly credit the funds.
4. Once the merchant clears the payment, a `card_settlement` entry is created for -$10.
5. The `pending_transaction` for +$10 completes.
6. A `transaction` is created for +$10 on the Account.

### A multi-capture (shipping separate line items)

![Card flows: Multi-capture](/images/docs-cards-flows-multi-capture.png)

1. A user purchases two items ($50 and $70 respectively) for a total of $120.
2. A `card_payment` is created. It includes a `card_authorization` entry for $120.
3. A `pending_transaction` for -$120 is created on the Account to hold the funds.
4. The merchant ships the first item and clears payment for $50.
5. A `card_settlement` entry is received for $50.
6. A `Transaction` is created for -$50 on the Account.
7. The `pending_transaction` amount updates to -$70.
8. The merchant ships the second item and clears payment for $70.
9. A `card_settlement` entry is received for $70.
10. The `pending_transaction` for -$70 completes.
11. A `transaction` is created for -$70 on the Account.