i4pay

i4pay API

Accept payments from your website, app or portal in three calls. All amounts are integers in kobo (₦1,500.00 = 150000).

Authentication

Send your secret key in the Authorization header. Keys starting sk_test_ use the sandbox (no real money); sk_live_ keys move real money and are issued once your business is approved. Never put a secret key in a browser or mobile app.

Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Content-Type: application/json

Base URL: https://i4pay.i4datanation.com.ng/api/v1 · Every response is {"status": true|false, "message": "...", "data": ...}.

1. Initialize a payment

POST /transactions/initialize — returns a checkout_url. Redirect your customer there.

curl https://i4pay.i4datanation.com.ng/api/v1/transactions/initialize \ -H "Authorization: Bearer sk_test_..." -H "Content-Type: application/json" \ -H "Idempotency-Key: order-1001-attempt-1" \ -d '{ "amount": 4500000, "email": "[email protected]", "customer_name": "Amina Bello", "reference": "INV-2026-1001", "description": "First term school fees", "callback_url": "https://yourschool.com/payment/return", "metadata": {"student_id": "1234"} }'
FieldRequiredNotes
amountYesKobo, whole number. Send the clean amount you want to receive — do not add your own gateway or convenience charges, because i4pay adds its charge on top at checkout and your customer would pay twice.
channelNocard, transfer or ussd to fix the payment method. Leave it out and the customer chooses on i4pay's checkout, where each method shows its exact total (bank transfer has the lowest fee).
emailYesCustomer's email (receipt goes here).
referenceRecommendedYour unique order reference. Re-using a pending reference returns the same payment.
callback_urlNoWhere we send the customer afterwards, with ?reference=…&status=…. Defaults to the URL in your dashboard.
fee_bearerNoLeave it out and the customer pays the charge: it is added on top at checkout and you receive the full amount. Send merchant to absorb the fee yourself (deducted from your settlement) where your account allows it.
customer_name, customer_phone, description, metadataNoStored and returned with the transaction and webhooks.
{ "status": true, "message": "Payment initialized", "data": { "reference": "INV-2026-1001", "i4pay_reference": "I4P-7K2Q9XAB3MHD", "checkout_url": "https://i4pay.i4datanation.com.ng/pay/I4P-7K2Q9XAB3MHD", "amount": 4500000, "fee": 107500, "charged": 4607500, "fee_bearer": "customer", "channel": null, "fees_by_channel": { "card": {"fee": 107500, "charged": 4607500, "merchant_net": 4500000}, "transfer": {"fee": 77938, "charged": 4577938, "merchant_net": 4500000}, "ussd": {"fee": 107500, "charged": 4607500, "merchant_net": 4500000} }, "mode": "test" } }

Until the customer picks a method, fee and charged show the highest (card) price. The final figures are in the verify response and webhooks.

2. Verify the payment

GET /transactions/verify/{reference} — always verify on your server before giving value. Give value only when data.status is success and data.amount matches your order.

curl https://i4pay.i4datanation.com.ng/api/v1/transactions/verify/INV-2026-1001 -H "Authorization: Bearer sk_test_..."

Statuses: pending, success, failed, abandoned, reversed.

3. Webhooks

Set your webhook URL under API keys & webhooks. We POST JSON events: charge.success, charge.failed, refund.processed. Verify the signature, answer with HTTP 200 quickly, then process. We retry failed deliveries with back-off for about two days.

<?php $raw = file_get_contents('php://input'); $expected = hash_hmac('sha512', $raw, 'whsec_your_webhook_secret'); if (!hash_equals($expected, $_SERVER['HTTP_X_I4PAY_SIGNATURE'] ?? '')) { http_response_code(401); exit; } http_response_code(200); $event = json_decode($raw, true); if ($event['event'] === 'charge.success') { // verify with GET /transactions/verify/{reference}, then mark the order paid (once) }

Other endpoints

MethodPathWhat it does
GET/transactionsList payments. Filters: status, from, to (YYYY-MM-DD), page, per_page.
GET/transactions/{reference}One payment (no gateway re-check).
GET/fees?amount=4500000Fee quote before you charge: what the customer will pay and what you will receive.
POST/refunds{"reference": "...", "amount": 100000, "reason": "..."} — reviewed by our finance team.
GET/balanceWhat we owe you, reserves and payments awaiting settlement.
GET/settlementsYour settlement history.
GET/banksBank names and codes.

Good practice