AidaPay API Documentation

Introduction

The AidaPay API lets you programmatically purchase airtime, data bundles, pay for cable TV, electricity tokens, and other bill payment services. It uses standard REST conventions with JSON request and response bodies.

Use POST to create objects (buy services, requery). Use GET to retrieve objects (account info, providers, packages, transaction status).

All responses follow this format:

JSON

{
  "success": true | false,
  "message": "description",
  "data": { ... }
}

Access tokens are long-lived and expire after 15 years.

Getting Started

Create a Business Account — Sign up at aidapay.ng/business with your phone number and email.

Verify Your Identity — Complete BVN and NIN verification to reach Level 3 in your Business dashboard under Settings → Upgrade & Limits.

Activate Agent Account — Complete the onboarding process to unlock API access, commissions, and the full platform.

Generate API Token — In your Business dashboard, go to Settings → API Settings to generate your token and set your webhook URL.

Fund Your Wallet — Generate a virtual bank account under Deposits and fund via bank transfer.

Start Building — Use the endpoints below with your Bearer token. Need help? Our 24/7 support team is available in your dashboard.

Authentication

Pass these headers with every request:

HEADERS

Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_API_TOKEN

Security: Never expose your token in client-side code. You can configure IP whitelisting in Account Settings → API Settings for added protection.

GET/my_accountGet Account Info▼

Returns your account details and wallet balances.

Response

JSON

{
  "success": true,
  "message": "success",
  "data": {
    "names": "John Doe",
    "email": "[email protected]",
    "phone": "08012345678",
    "balance": 15000.00,
    "commission_balance": 250.50
  }
}

Bearer Token

RESPONSE

Response will appear here...

GET/service/{slug}Get Providers▼

Get all available providers for a service type.

Path Parameters

Name	Description
slug REQUIRED	`airtime-topup` `data-bundle-sme` `cable-tv-subscription` `meter-token` `education` `internet`

Response

JSON

{
  "success": true,
  "data": [
    {
      "provider_name": "MTN",
      "provider_code": "mtn-airtime",
      "min_amount": 50,
      "max_amount": 50000,
      "provider_info": "...",
      "provider_image_url": "https://..."
    }
  ]
}

Bearer Token Service Slug

RESPONSE

Response will appear here...

GET/packages/{provider_code}Get Packages▼

Get packages for a provider (data plans, cable TV bouquets, etc). Use the provider_code from the providers endpoint.

Name	Description
provider_code REQUIRED	Provider code e.g. `mtn-data`

Response

JSON

{
  "success": true,
  "data": [
    {
      "package_name": "1GB - 30 Days",
      "package_amount": 300,
      "package_original_amount": 300,
      "package_api_code": "DATA-01",
      "provider_code": "mtn-data"
    }
  ]
}

Bearer Token Provider Code

RESPONSE

Response will appear here...

GET/validation/{provider_code}/{recipient}Validate Recipient▼

Validate a recipient before buying. For phone numbers, validates the network. For cable TV / electricity, verifies the smartcard/meter number and returns the customer name.

Name	Description
provider_code REQUIRED	Provider code
recipient REQUIRED	Phone / smartcard / meter number

Response

JSON

{
  "success": true,
  "data": {
    "success": true,
    "verified": true,
    "message": "Verified : JOHN DOE"
  }
}

Bearer Token Provider Code Recipient

RESPONSE

Response will appear here...

POST/buyBuy Service▼

Purchase airtime, data, cable TV, electricity, or other services. After a successful call, use the transaction_hash to check status, or receive updates via webhook.

Request Body

Name	Type	Description
recipient	string REQUIRED	Phone / smartcard / meter number
provider_code	string REQUIRED	Provider code from providers endpoint
account_pin	string REQUIRED	Your 4-digit account PIN
ref	string REQUIRED	Unique transaction reference (min 5 chars)
amount	string optional	Amount (for airtime, electricity)
package_code	string optional	Package code (for data, cable TV)
isPorted	string optional	Set to "yes" to skip network validation for ported numbers

Success Response

JSON

{
  "success": true,
  "message": "success",
  "data": {
    "success": true,
    "message": "Transaction Sent For Processing...",
    "transaction_data": {
      "transaction_hash": "TXabc123def456",
      "status": "Processing",
      "amount": 100,
      "recipient": "08012345678",
      "amount_paid": 100,
      "commission": 2.50,
      "special_message": "",
      "discount": 0
    }
  }
}

Bearer Token Request Body (JSON)

JSON

RESPONSE

Response will appear here...

GET/transaction/{transaction_hash}Transaction Status▼

Get the current status of a transaction. You can pass either the transaction_hash or your ref.

Name	Description
transaction_hash REQUIRED	Transaction hash or your ref

Response

JSON

{
  "success": true,
  "message": "success",
  "data": {
    "transaction_hash": "TXabc123def456",
    "ref": "TXN-20240101-001",
    "status": "Completed",
    "amount": 100,
    "amount_paid": 100,
    "commission": 2.50,
    "recipient": "08012345678",
    "package": null,
    "provider": "MTN",
    "service": "Airtime TopUp",
    "meter_token": null,
    "meter_unit": null,
    "serial_no": null,
    "pin": null,
    "expires": null
  }
}

Note: For electricity (meter-token), meter_token and meter_unit will contain the token and units purchased. For internet, serial_no, pin, and expires will be populated.

Bearer Token Transaction Hash or Ref

RESPONSE

Response will appear here...

Product Pricing

View all active providers, packages, and your commission rates. Enter your API token to load your personalised pricing.

Endpoint: GET /pricing — Requires Bearer token

Enter your token above and click "Load Pricing" to see your rates.

Webhooks

AidaPay sends webhook notifications to your URL whenever a transaction status changes. When you generate your API token in Account Settings → API Settings, you can add your webhook URL there.

Every webhook request includes a Signature header that you should verify using your access token as the HMAC key to ensure the request is authentic.

Transaction Webhook Payload

JSON

{
  "type": "transaction",
  "transaction_hash": "TXabc123def456",
  "ref": "TXN-20240101-001",
  "status": "Completed",
  "amount": 1000,
  "amount_paid": 1000,
  "commission": 20,
  "recipient": "08012345678",
  "package": null,
  "provider": "MTN",
  "meter_token": null,
  "meter_unit": null,
  "serial_no": null,
  "pin": null,
  "expires": null
}

Verifying the Webhook Signature (PHP)

Always verify the signature before processing the webhook to prevent spoofed requests:

PHP

<?php

// Your AidaPay access token (same one used for API calls)
$access_token = "your_aidapay_access_token";

// Read the raw POST body
$payload = file_get_contents("php://input");

// Generate local signature
$local_signature = hash_hmac('sha256', $payload, $access_token);

// Get the remote signature from headers
$headers = getallheaders();
$remote_signature = $headers['Signature'] ?? $headers['signature'] ?? '';

// Verify
if ($local_signature === $remote_signature) {
    $data = json_decode($payload, true);

    if ($data['type'] === 'transaction') {
        $hash   = $data['transaction_hash'];
        $status = $data['status'];
        $ref    = $data['ref'];
        $amount = $data['amount'];
        // ... process the transaction update
    }
} else {
    // Invalid signature - reject
    http_response_code(403);
    exit("Invalid signature");
}
?>

Important: Your webhook endpoint should return a 200 status code to acknowledge receipt. If you return an error, AidaPay may retry the webhook.

Error Handling

Errors return JSON with "success": false and a descriptive message:

JSON

{
  "success": false,
  "message": "Description of the error"
}

Common Errors

Code	Message	Cause
401	Unauthorized	Invalid or missing Bearer token
403	User is not agent	Account not upgraded to Agent
403	user is blocked	Account blocked by admin
403	maintenance is in progress	System under maintenance, retry later
403	transaction reference number already exist	Duplicate `ref` value
403	invalid account pin	Wrong 4-digit account PIN
403	Insufficient balance	Wallet balance too low for the transaction
403	Package is not available	Invalid or disabled package code
403	Provider's packages not available	Invalid provider code or provider disabled
403	Invalid recipient number	Recipient failed network validation
403	transaction ref must be greater than 5 characters	Ref too short

Tip: Always check the success field in every response. When false, the message tells you what went wrong.

Support

For API integration help, bug reports, or feature requests:

[email protected]