Developer docs
Refunds & verification
Give the money back the right way, and check who you are dealing with.
Refunding a collection
HTTP
POST https://www.harrenapay.com/api/public/v1/collections/{reference}/refund| Field | Type | Notes |
|---|---|---|
| reason | string | Optional. Max 300 chars. |
cURL
curl -X POST https://www.harrenapay.com/api/public/v1/collections/order_4821/refund \
-H "Authorization: Bearer hpay_live_…" \
-H "Content-Type: application/json" \
-d '{ "reason": "Customer cancelled" }'Where the money goes
Back to the customer — never to you. Your balance is reversed first (the collection credit and the fee), and then:
- If the customer has a HarrenaPay account, they are credited to their wallet immediately (
status: "credited"). - If they paid from outside HarrenaPay we do not hold their bank details, so the payout is queued for our team (
status: "pending_payout"). You are told it is pending — it is never credited to you in the meantime.
JSON (201)
{
"refund": {
"id": "ref_m1a2b3c4_d5e6",
"reference": "order_4821",
"amount_kobo": 2475000,
"fee_kobo": 25000,
"status": "credited",
"reason": "Customer cancelled",
"created_at": "2026-11-12T10:00:00.000Z"
},
"collection": { "reference": "order_4821", "status": "refunded" },
"note": "The customer has been credited to their HarrenaPay balance."
}You also get a collection.refunded webhook. A collection can only be refunded once — a second attempt returns 409.
Verifying a customer
HTTP
POST https://www.harrenapay.com/api/public/v1/verifications| Field | Type | Notes |
|---|---|---|
| type | string | "bvn" for identity, "account_name" for a bank account. |
| bvn, first_name, last_name | string | For type=bvn. The customer authorises the check with their bank. |
| bank_code, account_number | string | For type=account_name. |
| redirect_url | string | Optional. Where the bank returns the customer after consent. |
cURL
# bank account name
curl -X POST https://www.harrenapay.com/api/public/v1/verifications \
-H "Authorization: Bearer hpay_live_…" \
-H "Content-Type: application/json" \
-d '{ "type": "account_name", "bank_code": "057", "account_number": "0123456789" }'
# BVN
curl -X POST https://www.harrenapay.com/api/public/v1/verifications \
-H "Authorization: Bearer hpay_live_…" \
-H "Content-Type: application/json" \
-d '{
"type": "bvn",
"bvn": "01234567891",
"first_name": "Ada",
"last_name": "Obi",
"redirect_url": "https://yourstore.com/kyb/done"
}'For BVN you get a consent_url: send the customer there, they authorise the check with their bank, and you read the outcome from GET /v1/verifications/{id}.
JSON (201)
{
"id": "bvn_ref_123",
"type": "bvn",
"status": "pending",
"consent_url": "https://…",
"note": "Send the customer to consent_url. Poll GET /verifications/{id} for the result."
}See also collections, webhooks and errors.