Authorizations and clearing

An authorization is the bank's decision on one purchase. A clearing posts it, and a settlement pays the network for a day's clearings.

The decision

The issuer-processor sends POST /authorizations with network_ref, pan_token, amount, currency_code, merchant_name, mcc, country and channel (pos, ecommerce, atm or contactless). The network_ref identifies the purchase. Sending it again with the same terms returns the first decision with replayed true. Sending it with other terms is 409 conflict.

The card's status and controls, the sanctions lists and the cardholder are checked before funds.

A debit approval places a ledger hold of kind card_authorization, and the authorization carries its hold_id. On the account, holding_amount rises and available_amount falls. ledger_amount does not move until the clearing.
If the available balance does not cover the amount, the account's overdraft decision applies. Without cover the decline is insufficient_funds, code 51.
A credit approval places no deposit hold. It reserves room on the facility under the same network_ref.
With partial_approval_allowed true, a purchase the account or line cannot carry in full is approved for what is available. The code is 10, approved_amount is the amount authorized and requested_amount keeps what the merchant asked for.

Status

Status	Meaning	Event
`authorized`	Approved and waiting for its clearing. The hold or reservation stands until `expires_at`.	`cards.authorization.approved`
`declined`	Refused. Nothing was held.	`cards.authorization.declined`
`cleared`	Posted. `cleared_amount` and `journal_id` are set, and `draw_id` for a credit card.	`cards.authorization.cleared`
`reversed`	The merchant canceled it. The hold or reservation is released.	`cards.authorization.reversed`
`expired`	Never cleared within its window. The hold or reservation is released.	`cards.authorization.expired`

The window depends on the merchant category: 30 days for hotels, car rental, airlines and cruise lines, 3 days for fuel (5541, 5542) and 7 days otherwise. POST /authorizations/expirations runs the sweep and answers with the number expired.

POST /authorizations/{id}/increments raises an open authorization by amount under a network_ref of its own. On a debit card the hold for the new total is placed before the original is released, so the account must have the whole new total available. On a credit card the reservation is raised. A declined increment leaves the original as it was. POST /authorizations/{id}/reverse releases an authorization that is still authorized.

Clearing

POST /authorizations/{id}/clear posts the purchase. amount is optional and defaults to the authorized amount. One journal debits the account, credits card settlement payable (GL 2310) and releases the hold.

The network has already paid the merchant, so a clearing posts even when the account or the line cannot carry it. A clearing that did not fit is recorded as a clearing exception, listed at GET /cards/clearing-exceptions and published as cards.clearing_exception.recorded.

Kind	Cause
`returned`	The deposit account could not cover the amount beyond the hold. The shortfall is carried as an overdraft.
`over_limit`	A credit clearing exceeded the facility's availability plus its own reservation.
`over_clearing`	The clearing exceeded the authorization by more than the tolerance: 20 percent where a tip is added, 15 percent for travel, up to 175.00 at a fuel pump, nothing elsewhere.
`no_authorization`	No authorization came first.

A clearing above the tolerance is refused when the account has a debit block, is not open, or the cardholder is no longer eligible.

POST /clearings force-posts a clearing that arrives without an authorization. It takes the authorization body, records an authorization of kind force_post and clears it.
POST /refunds credits the card. With original_network_ref the purchase must be cleared on the same card, and the refund cannot exceed it.

Credit cards

A credit clearing is a draw of kind card on the facility, posted by the lending service: it debits the facility's receivable and credits card settlement payable. The draw consumes the authorization's reservation, and the authorization records its draw_id. See Facilities and collateral.

Settlement

POST /cards/settlements takes business_date and network, with a new Idempotency-Key for each batch. It claims up to 1,000 clearings not yet settled through that date and posts one journal that debits card settlement payable and credits the bank's master account. The answer carries count, cleared_amount, journal_id and cash_effective_date. more_available true means another key is needed for the next batch. Each batch publishes cards.settlement.posted.

Clearings that arrive in a network clearing file are matched and settled through the clearing file routes instead, and never enter a batch here.