Errors & idempotency

Errors are JSON with a human-readable reason and the HTTP status carries the class:

{ "error": "total mismatch: server-computed 9700" }

Status	Meaning	Examples
400	Validation or state error	total mismatch, bad cashback_rate, auth not capturable, auth expired, return qty exceeds captured
401	Missing or invalid credentials	missing x-api-key, invalid or expired session
403	Permission, environment or gate	owner/admin required, key env mismatch, merchant KYB not approved, blocked by monitoring
404	Unknown resource	charge not found, no active checkout on this terminal
500	Unexpected server error	Retry later; capture retries are safe

Idempotency

• Capture is idempotent on the charge id. Retrying POST /charges/{id}/capture returns the same transaction reference and cashback — it never charges twice. Safe to retry on network failure.
• Void is state-guarded: only AUTHORIZED charges can be voided; a repeat is a 400.
• Returns are not idempotent. Each call records a new return. Retry only when the previous attempt produced no response, and check the charge's captured/returned quantities before retrying.
• Checkout creation is not idempotent. A retry creates a new checkout and supersedes the previous PENDING checkout on the same reusable terminal. Carry your own order_id for reconciliation.
• Webhooks: dedupe on the x-fluense-delivery header (unique per delivery, stable across retries).

Conventions

• Money is always integer minor units (cents) with an ISO-4217 currency field.
• Amounts never cross currencies in one operation.
• Timestamps are RFC 3339 UTC strings.
• Pagination uses limit plus a cursor; responses carry next_cursor (null when done).