| Developer API Documentation

TopupNaija API Reference

Build payments, airtime vending, data recharge, electricity token procurement, and educational exam pin delivery directly into your applications with our robust, secure, and developer-friendly fintech API infrastructure.

Request Production API Access Explore Endpoints

⚠️ Production Access Policy: Access to production API servers requires a completed business KYB verification. Sandbox environments and credentials are available immediately upon onboarding.

API Authentication

The TopupNaija API protects operations using a dual-token authentication scheme to ensure security for partner funds and sensitive data transactions:

1

JWT Bearer Token

Acquired dynamically by submitting credential parameters to the /api/v1/auth/login endpoint. Pass this token inside the standard header wrapper for all authorized operations:

Authorization: Bearer <your_jwt_token>
2

Partner API Key

Issued directly to your profile page. Sandbox testing keys are available immediately. Production keys are provisioned following corporate KYB approval. Pass this key in the header:

X-API-Key: <your_partner_api_key>

Ready for Production API Access?

Provide your business registration details, utility bills, and identity proofs via the developer portal. Approvals and production credential provisioning are generally processed within 48 business hours.

Submit KYB Verification

Environments & Sandbox Testing

TopupNaija provides separated sandboxed testing networks and live production networks. Ensure your configurations reference the appropriate base host endpoint:

Environment Base Host URL Access Credentials
Sandbox (Test) https://sandbox.api.topupnaija.ng Instant sandbox API key and sandbox JWT
Production (Live) https://api.topupnaija.ng Approved production API key and live JWT

Expected Error Response Codes

Verify that your error parsers accommodate the following standard API response codes:

  • 401 Unauthorized: The provided JWT token has expired or is invalid.
  • 403 Forbidden: The client lacks the required permissions, has an unapproved KYB status, or has an invalid API Key.
  • 409 Conflict: An operation with a duplicate Idempotency-Key was submitted while the original execution is still processing.
  • 429 Too Many Requests: Client rate limits have been exceeded. Contact support to request custom rate limiting tiers.

Interactive API Reference