Transaction Lifecycle

Understanding how card transactions flow through the system from authorization to settlement.

Card authorization flow

Cardholder ──► Merchant POS/Online ──► Card Network ──► Payscribe ──► Business Webhook

1. Authorization

When a cardholder makes a purchase, the merchant requests an authorization:

1. Merchant sends transaction to the card network
2. The card network checks the card balance and available limit
3. Funds are held (not yet captured) — balance decreases but transaction is pending
4. Payscribe receives a purchase.card.auth.approved webhook from the card network
5. Payscribe dispatches a cards.auth.approved webhook to the business

                  Auth hold ($50)
  ┌──────────────────────────────────┐
  │  Card balance: $100 → $50        │  (held, not captured)
  │  Status: pending authorization    │
  └──────────────────────────────────┘

2. Settlement

The merchant captures the authorized amount (usually within 1–7 days):

1. The card network sends a purchase.card.auth.settled webhook
2. Payscribe dispatches a cards.auth.settled webhook to the business
3. The held amount is officially deducted from the card

                  Settlement ($50)
  ┌──────────────────────────────────┐
  │  Card balance: $50               │  (captured and deducted)
  │  Status: settled                 │
  └──────────────────────────────────┘

3. Refund / Reversal

If the merchant issues a refund:

1. The card network sends a purchase.card.return.auth.settled webhook
2. Payscribe dispatches a cards.adjusted.refund webhook to the business
3. Funds are credited back to the card balance

                  Refund ($50)
  ┌──────────────────────────────────┐
  │  Card balance: $50 → $100        │  (refunded)
  │  Status: refund settled          │
  └──────────────────────────────────┘

Decline flow

If the card has insufficient balance or is restricted:

1. The card network sends a purchase.card.auth.declined webhook
2. Payscribe dispatches cards.auth.declined to the business
3. After 3 consecutive declines, the card is automatically frozen

                  Decline
  ┌──────────────────────────────────┐
  │  Auth: DECLINED                  │
  │  After 3 declines: card frozen   │
  └──────────────────────────────────┘

Card lifecycle states

Created ──► Active ──► Frozen ──► Active
                │                     │
                └──► Terminated ◄─────┘

State	Description
Created	Card has been issued by the provider but not yet activated
Active	Card can be used for transactions
Frozen	Card is temporarily blocked. Can be unfrozen.
Terminated	Card is permanently closed. Cannot be reactivated.

Cross-border transactions

When a card is used in a different currency region:

1. The card network sends a purchase.card.cross-border.settled webhook
2. Payscribe dispatches cards.adjusted.crossborder to the business

Webhook event sequence

Order	Provider event	Payscribe event	Description
1	purchase.card.auth.approved	cards.auth.approved	Authorization approved, funds held
2	purchase.card.pre-auth.approved	cards.auth.approved	Pre-authorization approved
3	purchase.card.auth.settled	cards.auth.settled	Authorization captured and settled
4	purchase.card.contactless-payment.settled	cards.auth.settled	Contactless payment settled
5	purchase.card.return.auth.settled	cards.auth.settled	Returned payment settled
6	purchase.card.auth.reversal.settled	cards.adjusted.refund	Reversal settled
7	purchase.card.return.auth.approved	cards.adjusted.refund	Return approved
8	purchase.card.auth.declined	cards.auth.declined	Authorization declined
9	purchase.card.cross-border.settled	cards.adjusted.crossborder	Cross-border transaction settled
10	purchase.card.terminate	cards.adjusted.terminated	Card terminated

See the Webhooks reference for webhook setup instructions.