Overview

Accept payments in Nigeria with card, bank transfer, USSD and Pay with Nablr.

Nablr for Business API 1.0.0

The public API of Nablr for Business (Pay with Nablr). Your server calls it with your secret key to start payments, check them, manage payment links and webhook endpoints, and read customers and settlements.

Conventions

JSON in, JSON out. Send Content-Type: application/json with every body. Unknown fields in a request body are refused (VALIDATION_FAILED, detail code unknown), so a misspelt field never goes unnoticed.
Every success is {"data": …, "meta": {"request_id": "…"}}. Lists add meta.next (a cursor, or null on the last page) and meta.has_more.
Every error is {"error": {"message", "code", "title", "details"?, "meta"?}, "meta": {"request_id"}}. Branch on error.code, show error.message.
Money is an integer in minor units (kobo): 500000 is ₦5,000.00. The only currency is NGN.
Times are RFC 3339 in UTC, for example 2026-10-01T09:30:00Z.
Ids carry a prefix: pay_, cus_, lnk_, evt_, whe_, whd_, stl_, mer_, key_. An id with the wrong prefix is a 404.
An unknown path is 404 NOT_FOUND; a method a path does not take is 405 METHOD_NOT_ALLOWED with an Allow header. Both use the error envelope.
A field of the wrong JSON type is VALIDATION_FAILED with detail code type, naming the field and what to send (for example Send a whole number.).

Test and live. The key decides the mode. A sk_test_ key only ever sees test data and a sk_live_ key only live data; the two never mix. Test mode runs on a simulator, so no money moves.

Rate limits. With your secret key, 1,000 requests a minute per business per mode, however many of your servers share one IP address. Account-name enquiry (POST /banks/resolve) has a tighter limit of its own: 30 a minute per key (or per dashboard user). Browser traffic (the checkout, payment links, your publishable key) is limited to 300 a minute per IP address. Responses carry X-RateLimit-Limit and X-RateLimit-Remaining; a refusal is 429 RATE_LIMITED with Retry-After.

Information

OpenAPI version: 3.1.0

Authentication

secretKey

Your secret key, from Developers in the dashboard: Authorization: Bearer sk_test_…. Keep it on your server. A publishable key (pk_…) is refused with 403 SECRET_KEY_REQUIRED everywhere except POST /checkout/initialize.

Security scheme type: http

Bearer format: sk_test_… or sk_live_…

publishableKey

Your publishable key, from Developers in the dashboard. Safe to put in a web page or app: it can only start a checkout (POST /checkout/initialize). Every other request needs the secret key.