Developer docs
Quickstart
From API key to a collected payment and a payout to your bank. Amounts are always in kobo (₦1 = 100 kobo).
1. Get an API key
Start free with sandbox keys (hpay_test_…) from Settings → API sandbox. For production, create live keys (hpay_live_…) under Merchant → API keys (Business plan + approved merchant onboarding). Copy the secret once — it is not shown again.
2. Create a collection
curl -X POST https://www.harrenapay.com/api/public/v1/collections \
-H "Authorization: Bearer hpay_live_YOUR_KEY" \
-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"
}'The response gives you checkout_url (a hosted page) and account_number + bank_name (so you can show the transfer details yourself). It also shows the fee that will be deducted: collection_fee_kobo and net_settlement_kobo.
3. Let the customer pay
Send them to checkout_url, or give them the account details. When the money lands you get a payment.success webhook and the collection moves to funded. How collection accounts work.
4. Check your balance
curl https://www.harrenapay.com/api/public/v1/balances \
-H "Authorization: Bearer hpay_live_YOUR_KEY"available_balance_kobo is what you can pay out. Your collected money minus the fee — never the customer's money itself.
5. Register where the money should go
curl -X PUT https://www.harrenapay.com/api/public/v1/settlement-account \
-H "Authorization: Bearer hpay_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"bank_code": "057",
"account_number": "0123456789"
}'The account must be in your name — we confirm it with the bank. See banks for the directory and the resolve endpoint.
6. Pay out
curl -X POST https://www.harrenapay.com/api/public/v1/transfers \
-H "Authorization: Bearer hpay_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: payout_2026_11_12" \
-d '{ "amount_kobo": 1250000 }'A flat fee, to your registered revenue account. You get a payout.completed webhook when it settles. Transfers out.
7. Listen for webhooks
Register an HTTPS endpoint under Merchant → Webhooks, then follow signature verification.
Selling something that needs delivery first?
Use the escrow product instead: the money is held until you release it, the seller accepts and binds their own payout account, and you can take a commission with split.
Fees: a capped collection fee and a flat payout fee on payouts.