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 collection

2. 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 — the reference is the primary handle
  • POST /escrow/initiate — same
  • POST /transfers — accepts Idempotency-Key; use it, a retried payout would pay twice

Operations that are already safe to retry

  • POST /escrow/{reference}/deliver — idempotent, returns already_delivered: true
  • POST /escrow/{reference}/release — idempotent, returns already_released: true
  • GET endpoints 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.