harrenapay

Developer docs

Quickstart

Get from API key to a funded escrow in a few steps. 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). Copy the secret once — it is not shown again.

2. Create an escrow

cURL
curl -X POST https://www.harrenapay.com/api/public/v1/escrow/initiate \
  -H "Authorization: Bearer hpay_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order_1001",
    "amount": 2500000,
    "currency": "NGN",
    "customer_email": "buyer@example.com",
    "customer_name": "Ada Obi",
    "seller_email": "seller@example.com",
    "seller_name": "Ada Store",
    "description": "Order 1001 — wireless earbuds",
    "return_url": "https://yourstore.com/orders/1001",
    "release_window_hours": 168
  }'

Response includes checkout_url (hosted page at /checkout/{reference}), account_number, bank_name, and escrow_id. Retries with the same reference are idempotent.

3. Send the buyer to checkout

Redirect to checkout_url. The buyer signs in with the same customer_email, then transfers to the virtual account. When the inward credit lands, status becomes funded and you receive escrow.funded.

4. Mark delivered

cURL
curl -X POST https://www.harrenapay.com/api/public/v1/escrow/order_1001/deliver \
  -H "Authorization: Bearer hpay_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_number": "GIG123456",
    "courier_name": "GIG",
    "proof_photo_url": "https://cdn.example.com/proof.jpg"
  }'

Self-managed escrows require tracking + photo URL. This sets seller_delivered_at and starts the inspection window (default 24 hours). Status stays funded until release.

5. Release (or wait for auto-release)

cURL
curl -X POST https://www.harrenapay.com/api/public/v1/escrow/order_1001/release \
  -H "Authorization: Bearer hpay_live_YOUR_KEY"

Release requires the seller to have accepted the escrow and have payout details on file. See Release funds.

6. Listen for webhooks

Register an HTTPS endpoint under Merchant → Webhooks, then follow signature verification.