API Reference

The NaafiPay REST API is the same API our dashboard uses. Every dashboard action — from creating a checkout to issuing a refund — is available through an HTTPS endpoint that returns JSON. The API is designed to be predictable: resource-oriented URLs, standard HTTP verbs, standard response codes, and consistent error envelopes. This overview covers everything you need to know before reading the per-endpoint pages: where the API lives, how to authenticate, how errors look, and how rate limits work.

Base URL

All requests go to:

Base URL

1https://naafipay.com/api/public/v1

There is no separate sandbox URL — test mode and live mode are distinguished by the API key prefix (pg_test_ versus pg_live_). Use the same endpoints for both. A machine-readable OpenAPI 3.0 spec is published at/api/public/v1/openapi — import it into Postman or use it to generate a client for any language.

Authentication

Every request must include your API key as a bearer token in theAuthorization header. Requests without a valid key return401 Unauthorized. Keys are SHA-256 hashed at rest and are scoped to a single brand; optionally restrict a key to specific IPs from the dashboard.

Required headers

Field	Type	Required	Description
Authorization	string	required	Bearer token: your test or live API key from Settings → API Keys. Example: `Bearer pg_live_a1b2c3d4e5`
Content-Type	string	required	Set to application/json for all POST and PUT requests. Example: `application/json`

WarningNever expose live keys client-side

Live API keys must stay on your server. Calling the NaafiPay API from a browser, a mobile app, or any device the customer controls exposes the key to anyone who opens DevTools. If a live key ever leaks, rotate it from the dashboard immediately.

Errors

Every error response shares this shape:

Error envelope

1{
2  "error": {
3    "code": "invalid_amount",
4    "message": "The amount must be greater than 0.",
5    "status": 400,
6    "param": "amount"
7  }
8}

See Error Codes for the full list of error.code values you may encounter.

Pagination

List endpoints accept these query parameters:

page — 1-indexed page number, default 1
limit — items per page, default 25, maximum 100

Responses include a pagination object with page, limit, total, and has_more.

Rate limits

Default limits are 100 requests per minute per API key for read endpoints and 60 requests per minute for write endpoints. Exceeding the limit returns 429 Too Many Requests with a Retry-After header.

TipIdempotency

Pass an Idempotency-Key header (a unique string per logical request) on any POST request to safely retry network failures. NaafiPay caches the response for the same key for 24 hours, so a retry returns the original result instead of creating a duplicate payment.

Versioning

The API is currently at version v1. Breaking changes will ship under v2 with at least six months of overlap. Non-breaking additions (new fields, new endpoints) ship without a version bump.