Developer docs
Create escrow
POST /escrow/initiate — create an escrow funded by bank transfer to a virtual account.
HTTP
POST https://www.harrenapay.com/api/public/v1/escrow/initiateBody
| Field | Type | Notes |
|---|---|---|
| reference | string | Your order id. Idempotency key. 1–120 chars. |
| amount | integer | Kobo. Positive; max ₦10,000,000 (1_000_000_000 kobo). |
| currency | string | Defaults to NGN. |
| customer_email | string | Buyer email (required). Buyer must sign in with this address on /checkout. |
| customer_name | string | Optional buyer name. |
| seller_email | string | Optional. Sends seller an accept invite. |
| seller_name | string | Optional seller display name. |
| description | string | Optional. Max 500 chars. |
| return_url | string | Required HTTPS URL after checkout. |
| callback_url | string | Optional. Prefer registered webhooks. |
| release_window_hours | integer | 1–1440. Default 168 (7 days). Delivery deadline clock from accept/fund. |
| delivery_mode | string | "self_managed" (default) or "managed". Self-managed requires dispatch proof on deliver. |
| metadata | object | Optional key/value bag. |
Example
cURL
curl -X POST https://www.harrenapay.com/api/public/v1/escrow/initiate \
-H "Authorization: Bearer hpay_live_…" \
-H "Content-Type: application/json" \
-d '{
"reference": "order_4821",
"amount": 2500000,
"customer_email": "buyer@example.com",
"return_url": "https://yourstore.com/orders/4821",
"release_window_hours": 168
}'200 response
JSON
{
"checkout_url": "https://www.harrenapay.com/checkout/order_4821",
"account_number": "90……",
"bank_name": "…",
"amount_kobo": 2500000,
"expires_at": "…",
"reference": "order_4821",
"escrow_id": "uuid"
}Redirect the buyer to checkout_url. Idempotent retries with the same reference return the existing checkout when a funding account already exists.