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
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
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
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
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.