Transaction Statuses

Use this page as the canonical status reference for payment state in your system.

Canonical statuses

Status	Meaning	Typical action
`pending`	waiting for the next state change	keep the order open
`processing`	payment processing is in progress	wait and monitor
`paid`	payment completed	fulfill once
`captured`	card capture completed	fulfill once
`authorized`	card authorized but not final	keep pending until your business rule allows fulfillment
`three_ds_required`	card flow needs customer authentication	continue `next_action` instead of failing
`partially_paid`	only part of the amount settled	apply your partial-settlement policy
`refunded`	fully refunded	reverse fulfillment and finance state
`partially_refunded`	partially refunded	update order and accounting state
`canceled`	transaction canceled	close the attempt
`expired`	payment timed out	let the customer retry
`refused`	the payment was declined	surface a recoverable failure
`chargedback`	dispute or chargeback state	escalate to risk and finance
`processed`	an intermediate processing step completed	monitor until a final state
`in_protest`	banking or dispute hold	route to operations

Rules

Drive state changes from webhooks first.
For vouchers, pending can mean the payment instruction was issued and the customer still needs to pay through the selected local payment option.
Treat paid, captured, refunded, partially_refunded, canceled, expired, and refused as terminal in most payment systems.
Reconcile with GET /v2/transactions/{id} whenever a state transition is uncertain.

Example resource snapshot

{
  "id": "018f1f2e-7b42-7c9a-8d3e-1a2b3c4d5e6f",
  "status": "paid",
  "method": "pix",
  "amount": 1500,
  "currency": "BRL",
  "paid_at": "2026-03-16T14:03:10.000Z"
}

Payments

Checkout Links

Pix

Vouchers

Cards

Canonical statuses

Rules

Example resource snapshot

Read next

​Canonical statuses

​Rules

​Example resource snapshot

​Read next

Canonical statuses

Rules

Example resource snapshot

Read next