Errors & response format

Envelope#

Every response is JSON with the same three keys:

{ "success": true,  "message": "Transaction committed successfully", "data": { "...": "..." } }
{ "success": false, "message": "Customer not found" }

• success — act on this, not only on the HTTP status.
• message — plain English, safe to show to a cashier.
• data — the payload; absent or null on failure.
• Some endpoints add top-level fields: is_duplicate (commit, redeem, void), already_member (members/add), errors (validation), code (PIN errors).

HTTP status#

Validation errors#

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "amount": ["The amount field is required."],
    "branch_id": ["The selected branch id is invalid."]
  }
}

errors is keyed by field. Common causes: branch_id from another merchant, amount of 0 on commit, missing user_id.

Duplicate handling, not errors#

These are 200 responses that tell you the work was already done:

Messages you will meet#