Core Concepts
Transaction Lifecycle
How payments move through states from creation to settlement.
Every payment in Cresora follows a deterministic state machine. Understanding this is essential for building correct integration logic.
State diagram
requires_action → authorized → captured → settledPlus terminal states: voided, refunded, disputed, ach_returned
States
| State | Meaning |
|---|---|
requires_action | Payment created but requires 3DS or additional verification before authorization |
authorized | Funds reserved on the card; not yet captured. Only on capture_method: manual. |
captured | Funds captured; awaiting settlement batch. The typical happy-path final state for card payments. |
settled | Funds transferred to the merchant's settlement account. |
voided | Authorization reversed before capture. No settlement. |
refunded | Captured payment reversed after settlement. Creates a credit to the cardholder. |
disputed | Cardholder has initiated a dispute. Cresora delivers dispute.created webhook. |
ach_returned | ACH payment returned by the receiving bank (R-code). See ACH Returns. |
Webhook events
Each state transition fires a webhook event:
| Transition | Event |
|---|---|
Created → captured (automatic) | payment.captured |
Created → authorized (manual) | payment.authorized |
authorized → captured | payment.captured |
Any → failed | payment.failed |
Any → refunded | payment.refunded |
Any → disputed | dispute.created |
💡Tip
Webhooks are the authoritative source for payment state. Do not poll GET /v1/payments/{id} to check status — subscribe to webhook events instead.
Idempotent transitions
State transitions are idempotent: if you send a capture request for a payment that is already captured, Cresora returns the existing payment object without creating a new capture.