Developer docs

Create charge

POST /charge — generalised payment initialise. Prefer /escrow/initiate for full escrow checkout; use /charge when you need Idempotency-Key or a direct (non-escrow) settle option.

HTTP

POST https://www.harrenapay.com/api/public/v1/charge

Body

Field	Type	Notes
reference	string	Your order id. 1–120 chars.
amount	integer	Kobo. Positive; max ₦10,000,000.
currency	string	Defaults to NGN.
customer_email	string	Buyer email (required).
customer_name	string	Optional buyer name.
description	string	Optional. Max 500 chars.
return_url	string	Required HTTPS URL after checkout.
escrow	boolean	Default true. When false, marks the charge as skip_escrow (instant settle path).
release_window_hours	integer	1–1440. Default 168. Used when escrow is true.
metadata	object	Optional key/value bag.

Idempotency

Pass Idempotency-Key (8–128 chars, [\w.\-:]). Replays with the same key and body return the cached response with Idempotent-Replay: true. Same key, different body → 409.

cURL

curl -X POST https://www.harrenapay.com/api/public/v1/charge \
  -H "Authorization: Bearer hpay_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: charge_order_4821" \
  -d '{
    "reference": "order_4821",
    "amount": 2500000,
    "customer_email": "buyer@example.com",
    "return_url": "https://yourstore.com/orders/4821",
    "escrow": true
  }'

200 response

JSON

{
  "checkout_url": "https://www.harrenapay.com/checkout/order_4821",
  "account_number": "90……",
  "bank_name": "…",
  "amount_kobo": 2500000,
  "expires_at": "…",
  "reference": "order_4821",
  "charge_id": "uuid",
  "escrow": true
}

For the primary merchant escrow flow, use Create escrow instead — it supports delivery_mode, seller invites, and the managed-delivery lifecycle.