Transaction statuses

Use these statuses to track and act on transaction progress. All endpoints require headers Content-Type: application/json, x-api-key: <MY_API_KEY>, and x-token: <MY_TOKEN>.

Looking for withdrawal statuses? See Withdrawal statuses.

Status reference

Name
PENDING
Type
status
Description
Awaiting completion or payment confirmation.
Keep showing the payment prompt or QR; allow retries; avoid double-charging.
Name
CONFIRMED
Type
status
Description
Payment authorized/cleared and funds available.
Fulfill the order or service; send confirmation to the customer.
Name
FAILED
Type
status
Description
Payment attempt did not complete (invalid data, network, or processor error).
Show a retry option; allow changing payment method; log reason if provided.
Name
REFUNDED
Type
status
Description
Full amount returned to the payer.
Stop fulfillment, confirm refund to the user, and reconcile in your ledger.
Name
EXPIRED
Type
status
Description
Payment window closed without completion.
Mark the order as expired; offer to restart a new payment.

Example transaction

{
  "magic_id": "03UdoKvLNLHg",
  "amount": 4.00,
  "currency": "BRL",
  "status": "CONFIRMED",
  "decline_reason": null,
  "payment_method": "Pix",
  "end_to_end": "E123456789...",
  "external_ref": "external_ref_order",
  "created_at": "2025-12-10T15:21:24.420Z",
  "updated_at": "2025-12-10T15:25:00.000Z"
}

Dispute statuses

When a customer disputes a transaction, you'll see these additional statuses:

Name
DISPUTE_NEEDS_RESPONSE
Type
status
Description
A dispute was opened and action from you is required.
Collect evidence (invoice, delivery proof), respond within the dispute SLA.
Name
DISPUTE_IN_REVIEW
Type
status
Description
Dispute under review by the processor/network.
Monitor status; avoid duplicate submissions; keep customer comms updated.
Name
DISPUTE_WON
Type
status
Description
Dispute resolved in your favor. Funds remain with you.
Close internal case; notify customer if needed; retain evidence for audits.
Name
DISPUTE_LOST
Type
status
Description
Dispute resolved against you. Funds debited.
Update accounting; notify customer; review policies to prevent recurrence.

Dispute example

{
  "magic_id": "03UdoKvLNLHg",
  "amount": 4.00,
  "currency": "BRL",
  "status": "DISPUTE_NEEDS_RESPONSE",
  "decline_reason": "Customer claims item not received",
  "payment_method": "Pix",
  "external_ref": "external_ref_order",
  "created_at": "2025-12-10T15:21:24.420Z",
  "updated_at": "2025-12-15T10:00:00.000Z"
}

Operational tips

Always reconcile using magic_id or external_ref returned on creation.

For PENDING/EXPIRED, avoid creating new charges automatically without customer consent.
Subscribe to webhooks to stay in sync; use idempotent handlers keyed by magic_id or external_ref.
Surface clear messaging in your UI for FAILED/EXPIRED so users can retry safely.