Skip to navigation
GuidesPaymentsCard Present

Unified Charge Workflow

Read, charge, print, and email in a single charge-card interaction.

POST /api/terminal/{device_id}/charge-card runs up to four stages in one interaction: read → charge → print (optional) → email (optional).

{
  "amount": "25.00",
  "beep": true,
  "include_signature": true,
  "print_receipt": true,
  "send_receipt": true,
  "email": "customer@example.com"
}
  • Amount format: decimal dollars as a string, greater than zero, at most 2 decimal places (e.g., "19.99"). Any invalid amount returns 400 {"error": "Field amount is invalid"}. The same rule applies to read-card.
  • order_id is optional; if omitted, one is generated as <4-digit-random><yymmddHHMMSS>.
  • Requesting a step the device can’t do never fails the transaction. The charge completes, and the skipped step is tagged in result.stage_errors.
  • On success, result is the Payments API charge response. Fields vary by gateway, so treat the documented fields as representative, not exhaustive.

Reading stage_errors

KeyValueWhen it appears
readError messageThe read failed or was cancelled. The charge was never attempted.
signatureAlways "not supported"Capability gap.
chargeError messageA gateway fault prevented the charge — not a decline.
print"not supported" or an error messageCapability gap and device errors.
otherError messageAnything uncategorized.

Handling declines

A decline is an outcome, not a failure — and status won't tell you about it

A declined card returns status: "succeeded" with no stage_errors. Approval or decline is indicated by result — the Payments API’s own result field, carried inside the Terminal API’s result object. Always check result before showing the merchant an approval.

Print and email still run on a decline if requested — the merchant receives a receipt for the declined charge. Don’t treat “printed” or “emailed” as equivalent to “paid.”

result values, per the Payments API:

ValueMeaning
AApproved
BRetry
CDeclined
  1. status is failed or cancelled → show the stage_errors.read (or other) message; no charge occurred.
  2. status is succeeded → check result:
    • A (Approved) — show the approval.
    • C (Declined) — show the decline.
    • B (Retry) — a transient processor issue, not a decline; retry the charge with a new charge-card call rather than showing it to the merchant as declined.
  3. Check stage_errors for signature / print tags and surface them as non-blocking notices.