Idempotency

Send a unique idempotency_key on every purchase POST. Recommended format: VP + unique value (e.g. VP_AIRTIME_001). Never reuse a key for a different purchase.

Rules

In transaction JSON, reference and idempotency_key are the same string (what you sent, or a server UUID if omitted).
If the key was already used, the API returns 409 with errors.transaction_id, reference, and idempotency_key.
Do not expect a second debit — requery that transaction with GET /transactions/{id}.

Duplicate response example

JSON

{
  "success": false,
  "message": "This idempotency key has already been used. Use a unique key for each purchase.",
  "errors": {
    "transaction_id": 100,
    "reference": "VP_AIRTIME_001",
    "idempotency_key": "VP_AIRTIME_001"
  }
}