Refills the sandbox wallet back to ₦1,000,000. Requires an amg_test_ token — live tokens get 403 live_token_not_allowed.

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 } }

Mode follows the token: amg_live_… reads your live wallet, amg_test_… reads the sandbox. There's no cross-mode peek with one token. Response is never cached — it always reflects the latest debit, credit, or refund.

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"
  }
}

Body:

{
  "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
  "reference":     "MYAPP-TXN-123" // OPTIONAL — your own reference. If you retry
                                   // the same reference after a timeout you get
                                   // the cached response instead of a second vend,
                                   // and you can look it up later via
                                   // /api/data/status/?client_ref=MYAPP-TXN-123
}

Body parameters

<?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,"reference":"MYAPP-TXN-123"}'

Success response (200)

{
  "success":          true,
  "reference":        "AMG-20260713215802-ad5475",   // Amigo's reference — save this
  "client_reference": "MYAPP-TXN-123",               // echoed only if you sent one
  "message":          "Y'ello! You have gifted 2GB to 2348012345678. Share link https://go.mtn.ng/app/Dashboard with 2348012345678 to download the new MyMTN app for exciting offers.",
  "network":          1,
  "plan":             1001,
  "amount_charged":   350.00,
  "status":           "delivered"
}

On delivered transactions the message field is the carrier's own notification text (MTN's "Y'ello!…", Glo's / Airtel's equivalent). If the carrier didn't return one we fall back to a short Amigo-authored line like "2GB delivered to 09012345678 successfully.". Failed transactions always use the Amigo-authored copy so nothing carrier-branded ever pairs with a failed status.

Lookup: send exactly one of ?ref= (the Amigo reference we returned) or ?client_ref= (the reference you sent in the original POST body). Response shape is identical either way.

Scope: a token only sees purchases owned by its own client. Requests for a reference that belongs to another client return a clean 404 — same shape as "doesn't exist anywhere" — so reference enumeration is blocked.

# Look up by Amigo's reference
curl "https://amigo.ng/api/data/status/?ref=AMG-20260618215802-ad5475" \
  -H "X-API-Key: $TOKEN"

# Or look up by YOUR reference (from the "reference" field in POST /api/data/)
curl "https://amigo.ng/api/data/status/?client_ref=MYAPP-TXN-123" \
  -H "X-API-Key: $TOKEN"

# →
{
  "success": true,
  "data": {
    "reference":             "AMG-20260618215802-ad5475",
    "client_reference":      "MYAPP-TXN-123",           // only if you sent one
    "status":                "delivered",
    "network":               1,
    "mobile_number":         "09064703618",
    "plan":                  3333,
    "amount_charged":        900,
    "message":               "Y'ello! You have gifted 3GB to 2349064703618. Share link https://go.mtn.ng/app/Dashboard with 2349064703618 to download the new MyMTN app for exciting offers.",
    "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,
    "vendor_response": {                                 // success only
      "server_message": "Records Successfully Fetched",
      "status":         true,
      "data": {
        "message":         "Request processed",
        "reference":       260618215802,
        "recipient_phone": "2349064703618",
        "bundle":          "3000",
        "data": {
          "data": {
            "notification": "Y'ello! You have gifted 3GB to 2349064703618…",
            "unit":         "MB",
            "productId":    "1622"
          }
        }
      }
    }
  }
}

Error responses