Payment Lifecycle
A payment moves through a series of merchant-visible statuses from creation to a terminal outcome. This page documents the statuses GET /v2/payments/{id} can actually return, what each means for your integration, and how to track a payment to completion.
- Endpoint:
GET /v2/payments/{paymentId}β poll or check status after any payment operation - Scope:
merchant - Use: Tracking a payment from creation to a terminal state, and deciding when to retry, capture, or cancel
Merchant-Facing Statusesβ
| Status | Terminal? | Meaning |
|---|---|---|
PENDING | No | Queued or in flight β no vendor response yet |
AUTH_REQUIRED | No | Card requires a 3DS challenge before authorization can proceed |
CONFIRMATION_REQUIRED | No | 3DS challenge complete; waiting for the confirm call (handled automatically by the CCG Widget) |
CONFIRMATION_INITIALIZED | No | Confirm call received; processor finalizing the authorization |
AUTHORIZED | No | Pre-auth hold placed; funds held but not captured. Expires after 7 days if not captured. |
ACCEPTED | No | ACH payment accepted by the processor; settlement pending |
CAPTURE_INITIALIZED | No | Capture in progress (PRE-AUTH flow only β a SALE flow collapses this to PENDING) |
CANCEL_INITIALIZED | No | Cancellation in progress (PRE-AUTH flow only β a SALE flow collapses this to PENDING) |
COMPLETED | β | Payment fully processed and settled |
FAILED | β | Payment permanently failed β see Payment Error Codes |
CANCELED | β | Payment cancelled by the merchant or the system (including a split-tender sibling rollback) |
For SALE transactions (authorizeCard=false), the capture/cancel steps happen automatically behind the scenes β CAPTURE_INITIALIZED/CANCEL_INITIALIZED never surface; you'll only see PENDING until the payment reaches a terminal state. For PRE-AUTH transactions (authorizeCard=true), these intermediate states are surfaced so you can track the capture/cancel lifecycle explicitly.
Standard Flow Patternsβ
| Flow | Status Path |
|---|---|
| Card β Sale | PENDING β COMPLETED / FAILED |
| Card β Pre-Auth + Capture | PENDING β AUTHORIZED β CAPTURE_INITIALIZED β COMPLETED / FAILED |
| Card β Pre-Auth + Cancel | PENDING β AUTHORIZED β CANCEL_INITIALIZED β CANCELED |
| Card β 3DS challenge | PENDING β AUTH_REQUIRED β CONFIRMATION_REQUIRED β CONFIRMATION_INITIALIZED β COMPLETED / FAILED |
| Bank Account (ACH) | PENDING β ACCEPTED β COMPLETED / FAILED |
Status Handlingβ
Poll GET /v2/payments/{paymentId} or subscribe to payment webhooks β webhooks are the recommended primary mechanism; use polling as a fallback. Treat COMPLETED, FAILED, and CANCELED as terminal β stop polling once one of these is reached. All other statuses are transient and may still transition.
Cancellation Eligibilityβ
| Status | Cancel Allowed? |
|---|---|
PENDING | β Before processing starts |
AUTHORIZED | β Pre-auth void |
ACCEPTED | β ACH reversal |
COMPLETED | β Use a refund instead |
FAILED / CANCELED | β Already terminal |
Capture Eligibilityβ
Only a payment in AUTHORIZED status can be captured (full or partial); all other statuses reject a capture request.
Retry Handlingβ
A FAILED payment can be retried using the same merchantTransactionId; retry limits and idempotency behavior are documented in Retry Mechanisms, including session-mode-specific flows and webhook payloads.
Related Documentationβ
- Payments β general Payments API integration guide
- Retry Mechanisms
- Payment Error Codes
- Webhooks