Developer docs
Create a collection
A collection is money coming in. You give us an amount and a customer; we give you a bank account to receive the money and a checkout page for the customer.
POST https://www.harrenapay.com/api/public/v1/collectionsBody
| Field | Type | Notes |
|---|---|---|
| reference | string | Your idempotency key. 1–120 chars. |
| amount | integer | Kobo. Positive; up to ₦10,000,000. |
| currency | string | Defaults to NGN. Nigeria only. |
| customer_email | string | Who is paying. Required. |
| customer_name | string | Optional. |
| description | string | Optional. Max 500 chars. |
| return_url | string | Optional HTTPS URL after checkout. |
| escrow | boolean | Default true. false = direct collection (no seller, no release step) — see the Escrow product pages. |
| release_window_hours | integer | 1–1440, default 168. Only used when escrow is true. |
| metadata | object | Optional key/value bag. |
Example
curl -X POST https://www.harrenapay.com/api/public/v1/collections \
-H "Authorization: Bearer hpay_live_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order_4821" \
-d '{
"reference": "order_4821",
"amount": 2500000,
"customer_email": "buyer@example.com",
"customer_name": "Ada Obi",
"description": "Order 4821",
"return_url": "https://yourstore.com/orders/4821"
}'200 response
{
"checkout_url": "https://www.harrenapay.com/checkout/order_4821",
"account_number": "6185…",
"bank_name": "Wema Bank",
"amount_kobo": 2500000,
"expires_at": "2026-11-12T10:00:00.000Z",
"reference": "order_4821",
"charge_id": "uuid",
"escrow": true,
"collection_fee_kobo": 25000,
"net_settlement_kobo": 2475000,
"fee_model": "api-v1",
"settles_to": "merchant_revenue_account"
}Send the customer to checkout_url, or give them the account_number and bank_name to transfer to. When the money lands you get a payment.success / charge.success webhook.
Idempotency
reference is your idempotency handle. Posting the same reference again returns the same collection; posting it with a different amount or customer returns 409 rather than quietly collecting the wrong money. You can also send an Idempotency-Key header (8–128 chars) — a replay with the same body returns the cached response with Idempotent-Replay: true.
Where the money goes
A capped collection fee is deducted from what you are paid out. You never receive the customer's money — only your commission — see pricing and transfers out.