Build with SaukiMart
data infrastructure.

Overview

One API. Four Nigerian networks.

The SaukiMart API is a small, focused REST interface for automating data purchases across MTN, Airtel, Glo, and 9Mobile. The request format is identical across all four networks - no per-network adapters, no separate contracts.

Quickstart

Ship your first data purchase in minutes.

Follow these four steps to go from zero to a working integration.

# 1. Fetch available data plans
curl -X GET "https://saukimart.com/api/v1/data-plans" \
  -H "x-api-key: sm_live_XXXX_...your_key_here"

# 2. Purchase data
curl -X POST "https://saukimart.com/api/v1/purchase-data" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sm_live_XXXX_...your_key_here" \
  -d '{
    "phoneNumber": "08012345678",
    "planCode": 23,
    "network": 1,
    "idempotencyKey": "your-unique-request-id"
  }'

Authentication

Send your API key with every request.

All protected endpoints require your API key in the x-api-key request header. Live keys start with sm_live_ and test keys start with sm_test_. Store your key server-side - never in client-side code or public repositories.

You can restrict each key to specific scopes, IP addresses, and webhook URLs from the developer dashboard. Keep your API key private. If a key is ever compromised, rotate it immediately from the dashboard.

Data Plans

Curated live catalog preview.

These rows are pulled from the public plan catalog so developers can inspect current availability before signing in. Account-specific developer pricing is confirmed inside the developer dashboard.

Plan Efficiency

Helping your users choose the best plan.

The catalog can return daily, weekly, monthly, and promotional bundles across four networks. Keep your interface flexible - new plan types and promotional bundles are added periodically.

Test Mode

Test your integration safely before going live.

There are two ways to run sandbox requests: use a test key (sm_test_...) or use the sandbox phone number 08012345678 with a live key. Both methods return a full success-shaped response so your code can parse receipts, handle balances, and validate your integration without touching real funds.

{
  "success": true,
  "status": "sandbox",
  "transactionId": "uuid",
  "sandbox": true,
  "deducted": false,
  "data": {
    "planCode": 23,
    "network": "MTN",
    "phoneNumber": "08012345678",
    "deliveryReference": "SANDBOX-NO-DELIVERY"
  },
  "newBalance": 4650
}

Idempotency

Send idempotencyKey on every purchase request.

Networks are unreliable. A request may time out after being received but before a response is returned, leaving you uncertain whether the purchase went through. Generate a unique key per purchase attempt and reuse the same key if you retry the exact same request.

{
  "phoneNumber": "08012345678",
  "planCode": 23,
  "network": 1,
  "idempotencyKey": "unique-request-id-123"
}

Errors

All errors return JSON with an actionable error code.

Client-side errors use 4xx status codes, while server-side errors use 5xx. Every error response includes a machine-readable code, a human-readable description, and optionally a details object.

{
  "success": false,
  "version": "2026-04-17",
  "requestId": "req_82a3bc9f",
  "error": {
    "code": "insufficient_balance",
    "message": "Wallet balance is too low for this purchase.",
    "details": {
      "required": 322,
      "available": 150
    }
  }
}

Retry Behaviour

Retry safely without creating duplicates or missed events.

For API request retries, always reuse the same idempotencyKey on a retry of the same purchase. Apply exponential backoff and query /api/v1/transactions before creating new order records. For webhook delivery, SaukiMart will retry failed requests with exponential backoff.

Register Webhook

Receive real-time delivery events for your purchases.

Instead of polling /api/v1/transactions for updates, configure a webhook URL. SaukiMart will make an HTTP POST request to your endpoint every time a transaction status updates.

{
  "event": "developer.purchase.completed",
  "transactionId": "uuid",
  "status": "success",
  "planCode": 23,
  "phoneNumber": "08012345678",
  "amount": 322
}

Manage Webhooks

Update URLs and secrets without downtime.

Webhook configuration is scoped per API key. You can update the callback URL, set or rotate the signing secret, or assign webhooks to a different environment key at any time from the dashboard. Changes take effect instantly.

Event Reference

Webhook event types and schemas.

Verify Webhooks

Secure your endpoint by validating incoming requests.

When a signing secret is configured for your webhook, SaukiMart sends it as a plain-text token in the X-SaukiMart-Webhook-Secret header. Confirm this header matches your secret exactly before trusting the request.

app.post('/webhook', (req, res) => {
  const secretHeader = req.headers['x-saukimart-webhook-secret'];
  
  if (secretHeader !== process.env.SAUKIMART_WEBHOOK_SECRET) {
    return res.status(401).json({ error: 'Unauthorized - invalid webhook secret token' });
  }

  const { event, transactionId, status } = req.body;
  // Process payload...
  
  res.sendStatus(200);
});

API Terminal

Run live or sandbox requests directly in your browser.

The API Terminal lets you paste a key, select an endpoint, edit the request body, and inspect the response - all without leaving the docs page. It is useful for quick validation only; do not store your live API key in the browser long term.

{
  "success": true,
  "docs": {
    "purchaseEndpoint": "/api/v1/purchase-data",
    "transactionsEndpoint": "/api/v1/transactions"
  },
  "plans": [
    {
      "code": 23,
      "network": "MTN",
      "dataSize": "1GB",
      "developerPrice": 322
    }
  ]
}