Card Payments Lifecycle

Understand how card payments progress from authorization to settlement, how cancellations and refunds are recorded, and how to interpret payment amounts and events.

Payment records and history

Anchor represents a card payment using two resources:

A payment accumulates history entries as it progresses. Each entry has a category and an amountAffecting flag. Some entries contribute to payment amounts; others record information without changing those amounts.

History categories, payment statuses, and webhook events describe different aspects of a payment. For example, canceling an authorization creates a CARD_REVERSAL history entry, changes the payment status to VOIDED, and emits cardPayment.canceled.

Amounts and currency

Payment amounts are integers in the currency's minor units. For USD, 10000 means USD 100.00. All examples below use USD minor units.

The amounts object tracks separate totals. These totals retain what happened during the lifecycle: settling or canceling a payment does not erase its authorized amount.

Informational entries do not contribute to the financial totals. Refund requests are recorded separately in amounts.refundAuthorized, even though their history entries are not amount-affecting.

Authorization and settlement

An authorization reserves funds for a proposed purchase. Settlement captures the payment. Treat an authorized payment as pending settlement.

CARD_AUTHORIZATION → CARD_SETTLEMENT
AUTHORIZED           SETTLED

For a USD 100.00 payment that settles for its authorized amount:

A follow-up authorization notification may add an informational CARD_AUTHORIZATION entry. It does not add another authorized amount or emit another authorization event.

Direct settlement

A payment can settle without an earlier authorization. Anchor records a CARD_SETTLEMENT entry and emits cardPayment.settled. No authorization history entry is manufactured.

For a direct settlement of USD 100.00, amounts.authorized is 0 and amounts.settled is 10000.

Canceling an authorization

When an authorization is canceled before settlement, Anchor releases the full hold and records a CARD_REVERSAL entry. The payment becomes VOIDED, and Anchor emits cardPayment.canceled.

CARD_AUTHORIZATION → CARD_REVERSAL
AUTHORIZED           VOIDED

For an authorization of USD 100.00 that is canceled:

Authorization cancellation releases the complete hold; partial hold release is not supported in this flow.

A genuinely later settlement can still change a voided payment to SETTLED. Continue handling subsequent payment events after cancellation.

Authorization expiration

An expiration notification is recorded as CARD_AUTHORIZATION_EXPIRATION. This informational entry does not change payment amounts, update the payment status, or emit a webhook event. Do not interpret the history entry as a cardPayment.canceled event.

Reversing a settled payment

A reversal after settlement returns funds through a credit. Anchor records a CARD_REVERSAL entry, changes the payment status to REVERSED, and emits cardPayment.reversed.

CARD_SETTLEMENT → CARD_REVERSAL
SETTLED           REVERSED

For a USD 100.00 settlement that is fully reversed, amounts.settled remains 10000 and amounts.reversed becomes 10000.

Both cancellation and reversal use the CARD_REVERSAL history category. The payment status and event distinguish release of an unsettled authorization from reversal of a settled payment.

Settlement adjustments

A correction to an outstanding authorization can increase or reduce the amount that settles. Anchor records the adjustment and then the corrected settlement:

CARD_AUTHORIZATION → CARD_SETTLEMENT_ADJUSTMENT → CARD_SETTLEMENT
AUTHORIZED                                        SETTLED

This flow emits cardPayment.adjusted, followed by cardPayment.settled during processing.

The adjustment amount alone does not identify its direction. Use the recorded settlement amount for the settled total. Do not add amounts.adjusted to amounts.settled: the corrected settlement already includes that adjustment.

Refunds

A refund can be represented by a separate CardPayment with its own history. Do not assume that the refund payment ID is the original purchase ID or that the original purchase's amounts.refunded automatically includes amounts from a separate refund payment.

Refund request and completion

CARD_REFUND_REQUEST → CARD_REFUND
REFUND_REQUESTED      REFUNDED

The request records the amount requested for refund without crediting funds. The refund payment remains REFUND_REQUESTED until the credit completes. A completed refund creates a CARD_REFUND entry, changes the refund payment to REFUNDED, and emits cardPayment.refunded.

For a USD 100.00 refund:

There is no refund-request webhook. A nonzero requested amount does not mean that the credit has completed.

Standalone credit

A refund credit can arrive without a preceding refund request. Anchor records a CARD_REFUND entry on a separate payment, marks it REFUNDED, and emits cardPayment.refunded. No refund-request history entry is manufactured.

For a standalone credit of USD 100.00, amounts.refundAuthorized is 0 and amounts.refunded is 10000.

Declined payments

A declined attempt creates a CARD_DECLINE history entry and has status DECLINED. Anchor emits cardPayment.declined.

The decline entry does not add to the payment amount totals. Check declineReason, when present, to understand why the attempt was rejected. Possible reasons include insufficient funds, an incorrect PIN, or an inactive or invalid card.

History categories

Payment statuses