Complex Authorization Scenarios

Card authorizations vary depending on the issuer processor and underlying card network. The most common authorization scenarios include:

1. Partial Authorization
2. Incremental Authorization
3. Partial Reversal

Canopy supports complex authorization flows by allowing updates to draws with a non-final status. Specifically, the amount of a SIMPLE_CHARGE draw type can be increased, decreased, or updated as long as its settlement_status is not SETTLED.

Below, we outline how to ledger two key authorization scenarios in Canopy.

Incremental Authorization

An incremental authorization allows merchants to increase the authorized amount on a confirmed transaction before capturing the funds.

1. The initial authorization request is recorded following Canopy's authorization flows

2. Authorization increments are recorded using the adjust balance API. This API updates the draw balance by specifying the adjustment_amount_cents:

   • Positive values increase the balance
   • Negative values decrease the balance
   
   
   json

   {
       "adjustment_amount_cents": 30000, // Increases the original draw by $300
       "effective_at": "2024-01-10T19:00:00Z",
       "metadata": { "reason": "incremental authorization" }
   }
   

   ---

   🚧

   Note: Adjustments are only permitted for transactions in non-final statuses (e.g., AUTHORIZED, PENDING).

3. Finally, the issuer processor updates the transaction’s settlement status in Canopy using the settle transaction API

Partial Reversal

A partial reversal occurs when a merchant requests a transaction amount that exceeds the available credit, and the issuer approves only a portion of it.

How Canopy Handles Partial Reversal

1. The initial authorization request is recorded following Canopy's authorization flows, which verifies available credit before recording the authorized charge.
2. If the transaction settles for a different amount (typically lower), the settlement request must reflect this change. This is specified via the settlement attribute in the settle transaction API

{
    "effective_at": "2024-01-12T19:00:00Z",
    "adjustment": {
        "amount_cents": 380000, // 3.8k $
        "metadata": {"reason": "final settlement adjustment"}
    }
}