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

https://core.nadapay.io

Use this base URL for both sandbox and production. Your API key determines which mode handles the request.

The 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

Terminology

Use these terms consistently when you read the rest of the docs:

• mode: sandbox or production behavior selected by the API key
• rail: the transfer method, such as ACH, Bank Transfer, Mobile Money, or Crypto
• network: the routing identifier used for some payout methods
• provider: the named service provider used for some rails

Terminology

Use these terms consistently when you read the rest of the docs:

• mode: sandbox or production behavior selected by the API key
• rail: the transfer method, such as ACH, Bank Transfer, Mobile Money, or Crypto
• network: the routing identifier used for some payout methods
• provider: the named service provider used for some rails

Request format

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

curl --request POST \
  --url https://core.nadapay.io/v1/beneficiaries \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-key: a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  --data '{
    "name": "John Doe",
    "currency": "NGN",
    "type": "EXTERNAL_BANK",
    "details": {
      "accountNumber": "0123456789",
      "accountName": "John Doe",
      "networkId": "ntwk_01HXXXXXXXXXXXXXXXXXX",
      "rail": "Bank Transfer",
      "country": "NG"
    }
  }'

Response format

All responses return JSON. Successful response shapes are defined per endpoint in the API Reference. Error responses include statusCode and message.

Successful response:

{
  "statusCode": 200,
  "message": "Successful",
  "data": {}
}

Error response:

{
  "statusCode": 500,
  "message": "Internal server error"
}

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.

What's next