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.

HTTP
POST https://www.harrenapay.com/api/public/v1/collections

Body

FieldTypeNotes
referencestringYour idempotency key. 1–120 chars.
amountintegerKobo. Positive; up to ₦10,000,000.
currencystringDefaults to NGN. Nigeria only.
customer_emailstringWho is paying. Required.
customer_namestringOptional.
descriptionstringOptional. Max 500 chars.
return_urlstringOptional HTTPS URL after checkout.
escrowbooleanDefault true. false = direct collection (no seller, no release step) — see the Escrow product pages.
release_window_hoursinteger1–1440, default 168. Only used when escrow is true.
metadataobjectOptional key/value bag.

Example

cURL
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

JSON
{
  "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.