Get card charge status and receipt

📘
API Refs

Staging: Retrieve a card charge

GET /api/public/card-charges/{id}

Replace {id} with the AgentSnap charge ID returned when you created the charge. Include your account's API key in the Authorization header. A charge that does not belong to your account is not returned.

Status

Status	Meaning
`processing`	The payment is initiated, confirmed, queued, or pending. Completion is not yet confirmed.
`settled`	The card issuer has settled the payment, but wallet credit is not yet confirmed.
`succeeded`	The processor reports the transfer completed and the wallet credited.
`failed`	The payment failed. Check `failureCode` and `failureMessage`.
`canceled`	The processor reports the payment canceled.
`reversed`	The processor reports the transfer reversed.
`partially_refunded`	A refund of part of the charge has been confirmed.
`refunded`	Refunds of the full charge have been confirmed.

You may not observe every intermediate status when polling. settled is not the same as succeeded. The processor's overall completed, failed, canceled, or reversed state takes precedence over an earlier card-rail state. Only successful refunds produce partially_refunded or refunded; pending and failed refunds do not count as returned money.

Receipt and response fields

All monetary values below are integer cents. receipt always describes the original charge, even after a refund; use refunds[].refunded for confirmed returned funds.

Field	Meaning
`receipt.subtotalCents`	Original principal charged, before any surcharge.
`receipt.surchargeCents`	Surcharge paid by the cardholder, or zero.
`receipt.taxCents` / `receipt.tipCents`	Both are zero because this API currently does not accept separate tax or tip inputs.
`receipt.totalCents`	Original total charged to the card.
`receipt.currency`	`USD`.
`amount`	Original subtotal, surcharge, total, and currency, retained for compatibility. Use `receipt` for full itemization.
`card`	Card brand and last four digits; either field may be null if unavailable.
`refunds`	Refund history, including processing and failed attempts. Always included on GET, but omitted from the charge-creation response.
`failureCode` / `failureMessage`	A code for application logic and a readable explanation. Normally null when no failure is reported.
`metadata`	Metadata supplied with the charge, or null.
`createdAt`	The original charge creation time.

Merchant processing fees are not payer surcharges and are not included as extra receipt items. This receipt is not a merchant fee or net-settlement statement.

Example response

Illustrative response for a completed $1 charge with no refunds:

{
  "id": 14,
  "status": "succeeded",
  "receipt": {
    "subtotalCents": 100,
    "surchargeCents": 0,
    "taxCents": 0,
    "tipCents": 0,
    "totalCents": 100,
    "currency": "USD"
  },
  "refunds": [],
  "amount": {
    "subtotalCents": 100,
    "surchargeCents": 0,
    "totalCents": 100,
    "currency": "USD"
  },
  "card": { "brand": "Visa", "lastFour": "3000" },
  "failureCode": null,
  "failureMessage": null,
  "metadata": null,
  "createdAt": "2026-09-11T02:15:25.807Z"
}

For an issuer decline, a failed charge can instead contain failureCode: "do-not-honor" and failureMessage: "The card issuer declined this payment. Contact the issuer or use another card." Unknown failure codes have a general explanation; do not depend on the exact wording of failureMessage in application logic.

Reconcile against the processor

This GET is a validation read: it refreshes the original transfer and linked pending refunds from Moov before returning the result. It can repair stale local status when a webhook is delayed or missed. If current provider state cannot be verified, the endpoint returns HTTP 503; retry the read later rather than treating the last known state as confirmed completion.

Use webhook notifications for updates and GET to reconcile current state when needed. During integration testing, capture the actual webhook before using GET as evidence of automatic delivery: a GET that refreshes the record does not prove the webhook arrived.