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 when they’re received.

Card Payment entries

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. 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, its 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

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)

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)

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)

1. A user returns a 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)

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.