Get started

The Data API lets you sell mobile-data top-ups across every Nigerian network — MTN, Glo, Airtel, and 9mobile — straight from your backend. Token auth, IP whitelisting, idempotent retries, and a shared wallet that any of your apps can debit.

Your first call — buy 1GB of MTN data:

curl --location 'https://amigo.ng/api/data/' \
--header 'X-API-Key: YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "network": 1,
  "mobile_number": "09012345678",
  "plan": 1001,
  "Ported_number": true
}'

Overview

Amigo Developers gives you a single API to sell mobile-data top-ups:

• Data API — buy mobile data on MTN, Glo, Airtel, and 9mobile. Per-plan pricing, idempotent retries, real-time efficiency scores.
• Wallet balance New — a lightweight GET /api/wallet/ that returns your current live or test balance, so your backend can check funds before queuing a buy.

Base URL: https://amigo.ng/api. All responses are JSON. Money is Naira (the wallet endpoint returns up to 2 decimals; the data endpoints use whole-naira amounts) and most responses include a pre-formatted display string like "₦4,000".

Authentication

Pass your token in any of these headers — whichever your HTTP client makes easiest:

X-API-Key: amg_live_xxxxxxxxxxxxxxxx
# --or--
Authorization: Token amg_live_xxxxxxxxxxxxxxxx
# --or--
Authorization: Bearer amg_live_xxxxxxxxxxxxxxxx

Each token belongs to a single Amigo user + API client. The user_id identifies whose wallet gets debited; the client_id identifies which merchant owns the resulting work.

Test mode New

Build and integrate against a sandbox before touching real money. Test-mode tokens are intentionally familiar (Stripe-style) — the token prefix decides the environment:

Total isolation. A test token only sees test orders and test webhook endpoints; a live token only sees live ones. The two namespaces never cross. Every webhook payload includes a livemode boolean so subscribers can route or filter.

Refill the sandbox wallet:

curl -X POST "https://amigo.ng/api/commerce/sandbox/reset-balance/" \
  -H "X-API-Key: $TEST_TOKEN"

# → { "success": true, "data": { "test_balance": 1000000, "display": "₦1,000,000", "livemode": false } }

Wallet balance New

Check the balance your token can spend, in the current mode. Useful for showing a low-balance warning in your dashboard, gating a data buy before you call /api/data/, or reconciling against your own ledger.

curl "https://amigo.ng/api/wallet/" \
  -H "X-API-Key: $TOKEN"

# →
{
  "success": true,
  "data": {
    "balance":  168.50,
    "display":  "₦168.50",
    "currency": "NGN",
    "livemode": true,
    "mode":     "live"
  }
}

Errors

Every non-2xx response uses the same envelope:

{
  "success": false,
  "error":   "insufficient_balance",
  "message": "Wallet balance is below the order total."
}

Idempotency

The Data API accepts an Idempotency-Key header on every state-changing POST. Retry with the same key and you get back the original response — no double-debit, no duplicate work.

curl -X POST https://amigo.ng/api/data/ \
  -H "X-API-Key: $TOKEN" \
  -H "Idempotency-Key: data-2026-05-17-7f3a" \
  -H "Content-Type: application/json" \
  --data @buy.json

Keys are opaque strings up to 80 chars. Scope is per-token; reuse across tokens has no effect. Cache TTL is 24h.

Data API Mobile data top-ups

One endpoint: POST /api/data/. Pick a plan from the live catalog below, send it with the customer's mobile number, and we route the top-up through the carrier.

POST /api/data/

{
  "network":       1,              // 1=MTN, 2=Glo, 4=Airtel, 3=9mobile
  "mobile_number": "09012345678",
  "plan":          1001,           // from /plans_catalog.php
  "Ported_number": true            // if MNP'd
}

<?php
$ch = curl_init('https://amigo.ng/api/data/');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'X-API-Key: YOUR_API_TOKEN',
    'Content-Type: application/json',
    'Idempotency-Key: '.bin2hex(random_bytes(16))
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'network'       => 1,
    'mobile_number' => '09012345678',
    'plan'          => 1001,
    'Ported_number' => true
  ])
]);
echo curl_exec($ch);

fetch('https://amigo.ng/api/data/', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_TOKEN',
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({
    network: 1,
    mobile_number: '09012345678',
    plan: 1001,
    Ported_number: true
  })
}).then(r => r.json()).then(console.log);

curl -X POST https://amigo.ng/api/data/ \
  -H "X-API-Key: $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data '{"network":1,"mobile_number":"09012345678","plan":1001,"Ported_number":true}'

Live plan catalog

These tables refresh on every page load from the same plan APIs your integration can use. Use the Plan ID column when calling POST /data/.

Status (requery) New

Look up the current state of a single data purchase you already made. Use this when the original POST /api/data/ response was delayed or you want to reconcile against your own ledger before refunding a customer.

curl "https://amigo.ng/api/data/status/?ref=AMG-20260618215802-ad5475" \
  -H "X-API-Key: $TOKEN"

# →
{
  "success": true,
  "data": {
    "reference":             "AMG-20260618215802-ad5475",
    "status":                "delivered",
    "network":               1,
    "mobile_number":         "09064703618",
    "plan":                  3333,
    "amount_charged":        900,
    "message":               "3GB delivered to 09064703618 successfully.",
    "purchased_at":          "2026-06-18T21:58:02+00:00",
    "queried_at":            "2026-06-21T11:34:59+00:00",
    "duration_ms":           2672,
    "original_http_status":  200
  }
}

Plan efficiency

Reliability scores so you can pick plans that are safer for production traffic. A score ≥ 98% is excellent; < 75% is poor and we recommend avoiding.