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
FieldTypeNotes
reasonstringOptional. 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
FieldTypeNotes
typestring"bvn" for identity, "account_name" for a bank account.
bvn, first_name, last_namestringFor type=bvn. The customer authorises the check with their bank.
bank_code, account_numberstringFor type=account_name.
redirect_urlstringOptional. 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.