Developers / API Reference

API Reference

One Bearer-authenticated REST endpoint to initiate an escrow-backed checkout. The buyer pays through our licensed payment partner, funds are held in escrow, and your platform is notified via signed webhooks.

Base URL

https://harrenapay.com/api/public/v1

Authentication

Every request must include an Authorization header with a Bearer key generated from the in-app Developers tab. Keys are server-side only, never embed them in browser or mobile bundles.

HTTP

Authorization: Bearer hpay_live_xxxxxxxxxxxxxxxx

POST /escrow/initiate

Creates an escrow transaction and returns a hosted checkout URL. Calling twice with the same reference returns the same checkout (idempotent).

Request body

Field	Type	Notes
reference	string	Your unique order id. Idempotency key. 1–120 chars.
amount	integer	Amount in kobo (1 NGN = 100 kobo). Minimum 10000 (₦100).
currency	string	Must be `NGN`.
customer_email	string	Buyer email. Used for payment receipt.
callback_url	string	HTTPS endpoint to receive signed webhooks. Optional if already registered.
return_url	string	HTTPS URL we bounce the buyer to after payment.
metadata	object	Optional. Echoed back to you on webhooks.

Example

cURL

curl -X POST https://harrenapay.com/api/public/v1/escrow/initiate \
  -H "Authorization: Bearer hpay_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order_4821",
    "amount": 2500000,
    "currency": "NGN",
    "customer_email": "buyer@example.com",
    "callback_url": "https://yourapp.com/api/harrenapay-webhook",
    "return_url": "https://yourapp.com/orders/4821",
    "metadata": { "order_id": "4821" }
  }'

Node.js

const res = await fetch("https://harrenapay.com/api/public/v1/escrow/initiate", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.HARRENAPAY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    reference: order.id,
    amount: order.total_kobo,            // integer, kobo (NGN * 100)
    currency: "NGN",
    customer_email: order.buyer_email,
    callback_url: "https://yourapp.com/api/harrenapay-webhook",
    return_url: `https://yourapp.com/orders/${order.id}`,
    metadata: { order_id: order.id },
  }),
});
const { checkout_url, reference } = await res.json();
// Redirect the buyer to checkout_url

200 OK

JSON

{
  "checkout_url": "https://checkout.paystack.com/nk4p04cddqzw69s",
  "reference": "order_4821",
  "escrow_id": "efe94427-9c6c-4f4a-a3a2-8a1d0c8e6f62"
}

Redirect the buyer to checkout_url. After payment they are sent to your return_urlwith ?status=success or ?status=failed appended.

Errors

401 — missing, invalid, or revoked Bearer key
400 — validation failed (bad amount, missing fields, wrong currency)
5xx — upstream payment partner error. Safe to retry with the same reference.

Next: receive events

Webhooks reference

harrenapay is operated by Harrena Africa Synergy LTD. harrenapay is not a bank. Payment processing is provided by Paystack, our CBN-regulated licensed partner.