Merchant API v1

POST /transactions/initialize

Create a transaction and get the hosted-checkout authorization_url.

Returns 200 with authorization_url, access_code, reference, amount, mode, expires_at (the checkout stays payable for 30 minutes). Re-posting an identical open reference replays the same data; a completed or amount-changed reference returns 409 duplicate_reference.

GET /transactions/verify/{reference}

The state of one transaction (the transaction object). Fulfil only when data.status === "success" and data.amount is what you expected. Unknown references (or references belonging to the other mode) return 404 transaction_not_found.

GET /transactions

{
  "status": true,
  "message": "Transactions retrieved",
  "data": [ { …transaction… }, { …transaction… } ],
  "meta": { "page": 1, "per_page": 50, "total": 132, "total_pages": 3 }
}

POST /transactions/{reference}/requery

Force a fresh sweep of the bank confirmation for a transaction that is awaiting_transfer, then return its current state. Useful in a support tool ("customer says they've paid"). Settlement is idempotent — a requery can never double-settle.

GET /merchant

Your merchant profile as the platform sees it: merchant_code, business_name, status, live_enabled, the key's mode, your webhook URL, your effective fee schedule (percent, flat_kobo, cap_kobo) and lifetime live totals. Handy as a smoke test and for dashboards.

GET /webhooks

Your 50 most recent webhook deliveries — event, status (pending | delivered | failed), attempt count, last HTTP status and error. Debug your endpoint without asking support.

POST /webhooks/test

Queues a signed ping event to your webhook URL. Requires a webhook URL on your profile (422 no_webhook_url otherwise).

The transaction object

{
  "reference": "order-8021",          // your unique reference
  "amount": 500000,                   // kobo
  "currency": "NGN",
  "status": "success",                // pending | awaiting_transfer | success | failed | expired
  "gateway_ref": "IBGW-…",            // IbejuPay's bank-session reference (null until a bank is picked)
  "channel": "fidelity",              // fidelity | access | test | null
  "fee": 7500,                        // kobo — your agreed fee for this charge
  "net_amount": 492500,               // kobo — amount minus fee (what settles to you)
  "paid_amount": 500000,              // kobo — what actually landed (null until paid)
  "mode": "live",                     // live | test
  "description": "Order #8021",
  "customer": { "name": "…", "email": "…", "phone": "234…" },
  "metadata": { … },                  // echoed back exactly as you sent it
  "merchant_code": "IBM-9F3C2A1B",
  "created_at": "2026-07-30T12:35:22+01:00",
  "paid_at": "2026-07-30T12:38:41+01:00",   // null until paid
  "expires_at": "2026-07-30T13:05:22+01:00"
}

Webhook payload

Deliveries are POSTs with these headers:

Content-Type: application/json
User-Agent: IbejuPay-Webhook/1.0
X-IbejuPay-Event: charge.success
X-IbejuPay-Signature: <hex HMAC-SHA512 of the raw body, keyed with your whsec_… secret>

The body is {event, event_id, created_at, data} where data is the transaction object (for charge.success) or a simple message (for ping). Verify the signature over the raw body, respond 2xx fast, and de-duplicate by event_id — full details in the guide.

Error codes

Questions? info@ibejulekki.lg.gov.ng