Card Payments Lifecycle

Card payments move through a lifecycle that may include authorization, voiding, settlement, refund requested, refund, or decline.

Anchor represents this lifecycle using two resources:

New entries are added to a CardPayment as payment events occur. This gives customers a consistent history of the payment without exposing the underlying processing details.

A CardPayment does not have a payment kind or direction.

Supported lifecycle entries

Typical payment lifecycle

Most card payments begin with an authorization and finish with one settlement.

card_authorization
        │
        ├── card_reversal
        │
        └── card_settlement
                    │
                    └── 0..n card_settlement_adjustment

An authorization does not move money. A settlement represents the actual movement of funds.

A payment cannot have both a successful settlement and an authorization reversal. A reversal closes the authorization without settlement.

Exact settlement

When the authorized and settled amounts are the same:

card_authorization: USD 10,000
card_settlement:    USD 10,000

The CardPayment becomes settled with:

authorized_amount: USD 10,000
settled_amount:   USD 10,000

Settlement adjustments

A CARD_SETTLEMENT_ADJUSTMENT is a financial correction received when the payment is being settled.

card_authorization
        │
        └── card_settlement_adjustment

For example:

card_authorization:            NGN 10,000
card_settlement_adjustment: NGN 2,000 additional debit
settled_amount:    NGN 12,000

The original settlement remains in the payment history. The adjustment records the subsequent correction, while the parent CardPayment exposes the resulting adjusted amount.

A settlement adjustment may increase or reduce the final amount.

adjusted_amount =
    settled_amount
    + debit adjustments
    - credit adjustments

Voiding an authorization

A card_reversal means an authorized transaction was cancelled before it settled.

card_authorization
        │
        └── card_reversal

For example:

card_authorization: NGN 10,000
card_reversal:      NGN 10,000

The reversal voids the complete authorization. No settlement is created, and the CardPayment becomes voided.

Anchor does not currently support partial reversals. A reversal applies to the full authorized amount.

Direct settlement

A payment may settle without a preceding authorization.

CardPayment
    │
    └── card_settlement

In this flow:

• A new CardPayment is created.
• No synthetic authorization is added.
• One card_settlement entry records the complete amount.
• The payment becomes settled.

Refund lifecycle

A refund is represented as a separate CardPaymentHistory. It is added to the original purchase’s lifecycle.

Original CardPayment
        │
        └── card_settlement
                 ⋮
                 └── optional relationship

Refund CardPayment
        │
        ├── card_refund_request
        └── card_refund

The refund lifecycle works as follows:

1. A separate refund CardPaymentHistory is created.
2. A CARD_REFUND_REQUEST entry records the refund request with an amount of 0.
3. No money moves when the refund is requested.
4. The refund payment remains pending.
5. A CARD_REFUND entry records the credited amount.
6. The refund payment becomes settled.

Example:

card_refund_request: NGN 0
card_refund:     NGN 10,000 credit

The refund may be related to the original purchase when a reliable identifier is available. The refund must still be processed when the original purchase cannot be identified.

The original purchase remains settled after the refund. Any refunded amount displayed on the purchase is calculated from related refund payments.

Standalone credit

A credit or refund may be received without a preceding refund request.

CardPayment
    │
    └── card_refund

In this case:

• A separate CardPayment is created.
• No synthetic card_refund_request is added.
• The credit is represented by one card_refund.
• The payment is marked as settled.

Declined payment

A decline is a terminal payment attempt that does not move money.

card_decline

A declined payment may contain a decline reason, such as:

• insufficient_funds
• incorrect_pin
• incorrect_expiration_date
• card_inactive_or_invalid
• amount_limit_exceeded
• suspected_fraud
• do_not_honor
• restricted_card
• mcc_deny_list
• country_deny_list
• unspecified_decline

The CardPayment becomes declined, and no settlement is created.

Payment amounts

The parent CardPayment exposes amounts derived from its lifecycle entries:

There is no held_amount field.

Payment statuses

A payment’s status is derived from its lifecycle entries.

A settlement adjustment changes the payment amount but does not create a second settlement. The payment remains settled.