Developer docs
Idempotency
Networks retry. Payments must not double-charge. Two mechanisms, used together.
1. Your reference is the handle
Every collection, escrow and transfer takes reference — your order id. It is scoped to your API key, and it is what makes a retry safe:
- The same reference with the same amount and customer returns the same collection. No second account, no second charge.
- The same reference with a different amount or customer returns
409— we will not quietly collect the wrong money.
cURL
# first attempt
curl -X POST https://www.harrenapay.com/api/public/v1/collections -H "Authorization: Bearer hpay_live_…" -d '{"reference":"order_4821","amount":2500000,"customer_email":"a@b.c"}'
# the network died — retry with the SAME reference
curl -X POST https://www.harrenapay.com/api/public/v1/collections -H "Authorization: Bearer hpay_live_…" -d '{"reference":"order_4821","amount":2500000,"customer_email":"a@b.c"}'
# -> 200, the same collection2. Idempotency-Key for POSTs
Some endpoints accept an Idempotency-Key header as well: 8–128 characters from [\w.\-:]. The key is scoped to your API key and the response is cached for 24 hours.
- Same key, same body → the cached response, with
Idempotent-Replay: true. - Same key, different body →
409. That is a bug on your side; fix the key.
Which endpoints take a key
POST /collections— thereferenceis the primary handlePOST /escrow/initiate— samePOST /transfers— acceptsIdempotency-Key; use it, a retried payout would pay twice
Operations that are already safe to retry
POST /escrow/{reference}/deliver— idempotent, returnsalready_delivered: truePOST /escrow/{reference}/release— idempotent, returnsalready_released: trueGETendpoints are always safe.
When to retry
- Retry: 429 (honour
Retry-After), 5xx, and a network timeout. - Do not retry: 400, 401, 403, 404, 409, 422 — the request itself is wrong and will fail the same way.
See Errors for the full envelope, and the changelog if you are migrating an older integration.