Request & Response Format

All NadaPay API requests and responses follow a consistent structure. This page documents the conventions so you know what to expect from every endpoint.

Base URL

All endpoints are versioned under /v1.

Authentication header

Every request must include your API key in the x-api-key header:

x-api-key: YOUR_API_KEY

⚠️

NadaPay uses x-api-key — not Authorization: Bearer. Requests using the wrong header format will return 401 Unauthorized.

Required headers

Request format

All request bodies are JSON. Always set Content-Type: application/json on POST and PATCH requests.

curl --request POST \
  --url https://sandbox.api.nadapay.com/v1/beneficiaries \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  --data '{
    "name": "John Doe",
    "type": "individual",
    "currency": "NGN"
  }'

Response format

All responses return JSON. Successful responses include a data object. Error responses include an error object.

Successful response:

{
  "statusCode": 200,
	"message": "Successful"
  "data": {
    "id": "ben_01HXXXXXXXXXXXXXXXXXX",
    "name": "John Doe",
    "type": "individual",
    "status": "active",
    "created_at": "2025-01-01T00:00:00Z"
  }
}

Error response:

{
"statusCode": 400,
"message": "Error"
  "data": {}
}

Pagination

List endpoints return paginated results using cursor-based pagination.

Request:

GET /v1/beneficiaries?limit=20&after=ben_01HXXXXXXXXXXXXXXXXXX

Response:

{
  "data": [ ... ],
  "pagination": {
    "has_more": true,
    "next_cursor": "ben_01HYYYYYYYYYYYYYYYYYY"
  }
}

Timestamps

All timestamps are returned in ISO 8601 format in UTC:

2025-01-01T00:00:00Z

HTTP status codes

Rate limits

NadaPay applies rate limits per API key. When exceeded, you will receive a 429 Too Many Requests response with a Retry-After header indicating when you can retry.

📘

See Rate Limits in the API Reference for specific limits per endpoint group.

What's next