Complex Authorization Scenarios

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

1. Multi-Capture
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 these key authorization scenarios in Canopy.

Multi-Capture

Multi-capture allows merchants to settle a previously authorized amount in multiple partial captures, rather than settling the full amount at once. This is commonly used in scenarios like e-commerce (where items ship separately) or hotel stays (where charges accumulate over time).

1. The initial authorization request is recorded following Canopy's authorization flows, which verifies available credit before recording the authorized charge.
2. Partial Captures: Each time a portion of the transaction is settled, it is captured using the partial capture API with the appropriate amount settled for the portion.
   • Multiple capture requests can be made.
   • The remaining authorized amount stays open, maintaining its grasp on available_credit until fully settled, which is indicated on the request body via the final_capture attribute being set to true on the partial capture API.
     
     
   json

   { 
     "amount_cents": 2500,
     "effective_at": "2024-01-04T20:01:27Z",
     "final_capture": true,
   }
   

   
   

🚧

Note: The total amount_cents from all partial captures will be aggregated and deducted from the original AUTHORIZED hold. Any remaining difference will be automatically added as an adjustment to the original charges amount. The settlement_status of the original charge will also be transitioned to SETTLED

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.

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"}
    }
}