OffPay Merchant API

1. Register — log into your OffPay account, go to Me → Merchant API, and submit your business details. This requires a Tier 3 (fully verified) KYC account.
2. Wait for approval — new merchant accounts start under review. You’ll be able to issue API keys once approved.
3. Create an API key — once approved, generate a live key for production or a test key for integration testing, from the same Merchant API page.
4. Set a webhook URL (optional but recommended) — so you’re notified the moment a payment completes, instead of polling.

There is currently no separate signup flow outside the OffPay app/website — your merchant account is tied to your own OffPay user account.

Every request must include your secret key as a Bearer token:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx

Test keys look like sk_test_xxxxxxxxxxxxxxxxxxxx and behave identically, but are intended for integration testing.

Keep your secret key server-side only. It is shown to you exactly once, at creation time — if you lose it, revoke the key and create a new one.

Unauthenticated or invalid requests return 401 Unauthorized. A suspended or under-review merchant account returns 403 Forbidden on every call until it’s active again.

120 requests per minute, per merchant (not per key, not per IP — all your keys share one limit). Exceeding it returns 429 with:

{ "success": false, "message": "Too many requests. Please slow down." }

Errors always look like:

{ "success": false, "message": "Human-readable explanation." }

Common HTTP status codes: 400 (bad request — check message), 401 (missing/invalid key), 403 (account not active), 404 (not found), 409 (conflict — e.g. paying an already-paid charge), 429 (rate limited).

This is the other half of the API — creating a request for payment (“charge”) that anyone can pay, whether or not they have an OffPay account.

{
  "reference": "order-4471",
  "amount": 12000,
  "narration": "Order #4471",
  "expiresInMinutes": 30
}

{
  "success": true,
  "data": {
    "id": "8f2a1c3e-...",
    "reference": "order-4471",
    "amount": 12000,
    "currency": "NGN",
    "status": "pending",
    "checkoutUrl": "https://offpay.4go.com.ng/pay/8f2a1c3e-...",
    "expiresAt": "2026-09-14T10:30:00Z",
    "createdAt": "2026-09-14T10:00:00Z"
  }
}

{ "success": true, "data": { "id": "8f2a1c3e-...", "reference": "order-4471", "status": "success", "amount": 12000, "currency": "NGN", "completedAt": "2026-09-14T10:04:12Z" } }

Set your webhook URL from Me → Merchant API in the app. Every event is a POST with this shape:

{
  "event": "payment.success",
  "data": { "...": "..." },
  "timestamp": "2026-09-14T10:00:01Z"
}

Every event’s data also includes "livemode": true (or false for test-mode activity — see §8).

Events

Verifying the signature

Every webhook request includes an X-OffPay-Signature header — an HMAC-SHA256 of the raw JSON body, using your webhook secret (shown once at creation, and again each time you rotate it from the Merchant API page). Always verify this before trusting a webhook’s contents.

const crypto = require('crypto');

function isValidSignature(rawBody, signatureHeader, webhookSecret) {
  const expected = crypto.createHmac('sha256', webhookSecret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

Delivery and retries

A webhook that doesn’t respond 2xx is retried automatically. Your endpoint should be idempotent — use the reference in the payload to ignore an event you’ve already processed, rather than assuming every delivery is new.

Webhook delivery failures never affect the underlying payment — by the time a webhook fires, the money has already moved (or definitively failed). The webhook is a notification, not part of the transaction itself.

Keys are environment-scoped (sk_live_... / sk_test_...) and fully isolated from each other:

• Test mode has its own balance, entirely separate from your live balance, seeded with 100,000 (fake) NGN so you can test payouts right away.
• A live key never sees test data and a test key never sees live data — GET /balance, GET /payments, GET /payments/:reference, and GET /charges/:reference are all scoped to whichever key made the request.
• Test payments never move real money. A POST /payments made with a test key debits your test balance and is recorded as an immediate simulated success — it never credits a real OffPay user’s real wallet and never calls a real bank payout.
• Test charges are never payable with real money either. A charge created with a test key can’t be paid via a real OffPay wallet or a real card/bank transfer — instead, complete it with:

{ "success": true, "message": "Test payment simulated.", "data": { "id": "8f2a1c3e-...", "reference": "order-4471", "status": "success" } }

Webhooks include "livemode": false on every event fired from test activity (and true for live), the same convention Stripe and Paystack use, so your handler can tell them apart without tracking which key created the underlying payment.

Use small amounts for live-key integration testing regardless — the separation above only applies to test keys.

Questions or issues — reach out via Me → Support in the app, or your account contact if you have one.