PayFacto API - v2.0 - Charge & Refund Status Values

All possible status values for charges and refunds in the PayFacto Payment API v2.0, with the state transitions allowed between them. Use this reference to drive UI state, reconciliation logic, and webhook handling.

Contents

📊Overview 💳Charge Status Values ↩️Refund Status Values 🔄State Transition Rules 📋Charge Lifecycle

📊

Overview

Every charge and refund object returned by the API has a status field describing its current state in the transaction lifecycle. Status values are mutually exclusive — a resource is always in exactly one state — and transitions between states follow strict rules described below.

ℹ️

Poll GET /charges/{chargeId} or GET /refunds/{refundId} to check current status, or configure a webhook to be notified of status changes in real time.

💳

Charge Status Values

Status	Type	Description
AUTHORIZED	Pre-auth	Funds are reserved on the card but not yet collected. Created when a charge is submitted with `capture: false`.
CAPTURED	Active	Funds have been collected from a previously authorized charge via the captures endpoint. Awaiting settlement.
SUCCEEDED	Final	An immediate purchase (capture: true) was approved and funds collected in a single step.
DECLINED	Final	The issuer refused the transaction. See result.declineCode for the reason.
FAILED	Final	The transaction could not be processed due to a system or validation error — not an issuer decline.
VOIDED	Final	A captured or succeeded charge was cancelled before batch close. No settlement occurs.
RELEASED	Final	An authorized (pre-auth) charge was released without being captured. The hold is removed; no funds were ever collected.

↩️

Refund Status Values

Status	Type	Description
SUCCEEDED	Final	The refund was approved and funds will be returned to the cardholder at settlement.
FAILED	Final	The refund could not be processed — typically due to insufficient remaining captured amount or a system error.
VOIDED	Final	The refund was cancelled before batch close via the refund voids endpoint. Error correction only.

⚠️

Refunds do not have an intermediate pre-authorization state. A refund is either SUCCEEDED, FAILED, or later VOIDED before settlement.

🔄

State Transition Rules

From Status	Allowed Transition	Notes
AUTHORIZED	→ CAPTURED, VOIDED, RELEASED	Capture collects funds. Void cancels (rare — usually used on captured, not authorized). Release cancels the hold without collecting funds.
AUTHORIZED	→ AUTHORIZED (increment)	An increment updates the authorized amount but keeps the charge in AUTHORIZED status.
CAPTURED	→ VOIDED	A captured charge can be voided before the end-of-day batch closes.
SUCCEEDED	→ VOIDED	An immediate purchase can also be voided before batch close, same as a captured charge.
CAPTURED / SUCCEEDED	→ (refunded via separate Refund resource)	Refunds are separate resources, not a status change on the charge itself. The charge remains CAPTURED or SUCCEEDED; a new Refund resource is created.
DECLINED / FAILED	→ (terminal — no further transitions)	Once declined or failed, a charge cannot be retried in place. Submit a new charge request.

📋

Charge Lifecycle

Two paths exist depending on whether the charge is created with capture: true (immediate purchase) or capture: false (pre-authorization).

Path A — Immediate Purchase

Flow

POST /charges (capture: true)
        │
        ▼
┌─────────────┐     ┌─────────┐
│  SUCCEEDED  │ ──▶ │ VOIDED  │  (before batch close)
└─────────────┘     └─────────┘
        │
        ▼
  (Refund resource created separately, if needed)

Path B — Pre-Authorization

Flow

POST /charges (capture: false)
        │
        ▼
┌──────────────┐
│  AUTHORIZED  │
└──────┬───────┘
       │
  ┌────┼────────────────┐
  ▼    ▼                ▼
CAPTURED  RELEASED   AUTHORIZED (increment, stays AUTHORIZED)
  │
  ▼
VOIDED (before batch close)