SaukiMart Developers | Telecom Data, Wallet & Vending API Reference

Architecture & Overview

Single Unified REST Contract

The SaukiMart Developer API standardizes mobile data recharges for MTN, Airtel, Glo, and 9Mobile. Regardless of network carrier, the request schema, status codes, and callback signatures are completely uniform.

Base Production URL	https://saukimart.com
Sandbox Base URL	https://saukimart.com/api/v1/test
Data Format	JSON (Content-Type: application/json)
Authentication	Header: x-api-key: sm_live_... / sm_test_...
Default Rate Limit	90 requests / minute per API key

Quickstart

4 Steps to Integration

Go from registration to live data fulfillment in under 5 minutes.

STEP 11. Get Your Key

STEP 22. Query Plans

Call GET /api/v1/data-plans to get wholesale plan codes, validity, and discounted developer rates.

STEP 33. Execute Purchase

Send a POST to /api/v1/purchase-data with the target phone, planCode, network, and idempotencyKey.

STEP 44. Receive Webhook

Optionally register a webhook endpoint to receive real-time completion callbacks.

🤖Explain or generate code with your favorite AI:

Ready to delegate integration?Copy the full API integration prompt with all endpoint specs, error codes, and idempotency rules.

Quickstart Sample · curl

# 1. Fetch available data plans across MTN, Airtel, Glo & 9Mobile
curl -X GET "https://saukimart.com/api/v1/data-plans" \
  -H "x-api-key: sm_live_9a8b7c6d5e4f..."

# 2. Purchase data bundle with idempotency protection
curl -X POST "https://saukimart.com/api/v1/purchase-data" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sm_live_9a8b7c6d5e4f..." \
  -d '{
    "phoneNumber": "08012345678",
    "planCode": 23,
    "network": 1,
    "idempotencyKey": "req_8f19e7a2b"
  }'

Security & Auth

API Key Authentication

All API requests must include your secret API key in the x-api-key HTTP header. Keys are prefixed with sm_live_ for production and sm_test_ for sandbox environments.

Header	Format	Description
x-api-key	sm_live_<prefix>_<secret>	Production key — debits live wallet balance
x-api-key	sm_test_<prefix>_<secret>	Sandbox key — ₦0 simulated transactions
Content-Type	application/json	Required for all POST/PUT request bodies

Header Authentication Format

$curl -X GET "https://saukimart.com/api/v1/data-plans" \
-H "x-api-key: sm_live_9a8b7c6d5e4f..."

Error Response — Invalid or Missing Key (401)

401 Unauthorized · application/json

{
  "success": false,
  "error": "A valid API key is required. Pass your key in the x-api-key header.",
  "code": "INVALID_API_KEY",
  "statusCode": 401,
  "requestId": "req_a1b2c3d4"
}

Available Scopes

Scope	Grants Access To
`read:plans`	GET /api/v1/data-plans, GET /api/v1/me, GET /api/v1/wallet/balance
`write:purchases`	POST /api/v1/purchase-data
`read:transactions`	GET /api/v1/transactions, GET /api/v1/transactions/:id

Endpoint 01 · Account

Get User Profile

Returns the authenticated developer's profile details, account status, and API key metadata. Use this endpoint to verify authentication and display user information in your integration dashboard.

GET/api/v1/me

Scope: read:plans

GET /api/v1/me (CURL)

$curl -X GET "https://saukimart.com/api/v1/me" \
-H "x-api-key: sm_live_9a8b7c6d5e4f..."

Example Response Payload (200 OK)

200 OK · application/json

{
  "success": true,
  "version": "2026-04-17",
  "requestId": "req_a1b2c3d4",
  "user": {
    "id": "usr_uuid_12345",
    "firstName": "David",
    "lastName": "Adeleke",
    "phone": "08012345678",
    "isDeveloper": true,
    "developerDiscountPercent": 5,
    "accountNumber": "7821234567",
    "bankName": "SaukiMart (Flutterwave)",
    "phoneVerified": true,
    "phoneVerifiedAt": "2026-06-15T10:30:00Z",
    "createdAt": "2026-05-01T08:00:00Z"
  },
  "environment": "live",
  "keyName": "production-server",
  "scopes": [
    "read:plans",
    "write:purchases",
    "read:transactions"
  ]
}

Parameters & Schema Guide

Field	Description
`user.id`stringRequired	Unique user identifier (UUID)
`user.firstName`stringRequired	Developer first name
`user.lastName`stringRequired	Developer last name
`user.phone`stringRequired	11-digit registered phone number
`user.isDeveloper`booleanRequired	Whether developer mode is enabled
`user.developerDiscountPercent`numberRequired	Wholesale discount rate applied to purchases
`user.accountNumber`string \| null	Virtual bank account number for wallet funding
`user.bankName`string \| null	Bank name for the virtual account
`user.phoneVerified`booleanRequired	Phone verification status
`user.createdAt`ISO 8601Required	Account creation timestamp
`environment`stringRequired	Key environment — "live" or "test"
`scopes`string[]Required	Permissions granted to the API key

Endpoint 02 · Account

Fetch Wallet Balance

Returns the current wallet balance for the authenticated developer. Use this before executing purchases to verify sufficient funds and prevent 402 INSUFFICIENT_FUNDS errors.

GET/api/v1/wallet/balance

Scope: read:plans

GET /api/v1/wallet/balance (CURL)

$curl -X GET "https://saukimart.com/api/v1/wallet/balance" \
-H "x-api-key: sm_live_9a8b7c6d5e4f..."

Example Response Payload (200 OK)

200 OK · application/json

{
  "success": true,
  "version": "2026-04-17",
  "requestId": "req_e5f6g7h8",
  "wallet": {
    "balance": 125430.5,
    "currency": "NGN",
    "lastUpdated": "2026-08-19T14:30:00Z"
  },
  "environment": "live"
}

Parameters & Schema Guide

Field	Description
`wallet.balance`numberRequired	Current wallet balance in NGN (Nigerian Naira)
`wallet.currency`stringRequired	Currency code — always "NGN"
`wallet.lastUpdated`ISO 8601Required	Timestamp of the last wallet mutation

💡 Developer Integration Tip:

Call this endpoint before every purchase to pre-flight check available balance.
Fund your wallet via bank transfer to the virtual account number shown in GET /api/v1/me.

Plan Catalog

Current Wholesale & Developer Rates

Updated in real-time. Pass the numeric planCode into your API purchase calls.

GET

MTN

CODE	SIZE	DAYS	PRICE
`201`	500MB	30d	₦284.05
`202`	1GBPopular	30d	₦407.55
`203`	2GB	30d	₦759.05
`204`	3GB	30d	₦1,234.05
`205`	5GB	30d	₦1,709.05
`206`	7GB	30d	₦2,374.05

GLO

CODE	SIZE	DAYS	PRICE
`301`	200MB	30d	₦94.05
`302`	500MB	30d	₦189.05
`303`	1GBPopular	30d	₦379.05
`304`	2GB	30d	₦759.05
`305`	3GB	30d	₦1,139.05
`306`	5GB	30d	₦1,899.05

AIRTEL

CODE	SIZE	DAYS	PRICE
`401`	500MB	7d	₦521.55
`402`	1GBPopular	30d	₦722.00
`403`	2GB	30d	₦1,358.50
`404`	3GB	30d	₦2,108.05
`405`	4GB	30d	₦2,488.05
`406`	10GB	30d	₦3,704.05

Endpoint 03 · Core Data API

Fetch Available Data Plans

Returns the active mobile data bundle catalog across all supported Nigerian carriers (MTN, Airtel, Glo, 9Mobile) with real-time wholesale developer pricing calculated for your account.

GET/api/v1/data-plans

Scope: read:plans

GET /api/v1/data-plans (CURL)

$curl -X GET "https://saukimart.com/api/v1/data-plans" \
-H "x-api-key: sm_live_9a8b7c6d5e4f..."

Example Response Payload (200 OK)

200 OK · application/json

{
  "success": true,
  "version": "2026-04-17",
  "requestId": "req_dp_10293847",
  "discountPercent": 5,
  "plans": [
    {
      "code": 23,
      "network": "MTN",
      "networkId": 1,
      "planId": 201,
      "dataSize": "1GB",
      "validity": "30 Days",
      "appPrice": 350,
      "developerPrice": 332.5
    },
    {
      "code": 24,
      "network": "MTN",
      "networkId": 1,
      "planId": 202,
      "dataSize": "2GB",
      "validity": "30 Days",
      "appPrice": 700,
      "developerPrice": 665
    },
    {
      "code": 31,
      "network": "GLO",
      "networkId": 2,
      "planId": 301,
      "dataSize": "1GB",
      "validity": "30 Days",
      "appPrice": 399,
      "developerPrice": 379.05
    },
    {
      "code": 41,
      "network": "AIRTEL",
      "networkId": 4,
      "planId": 401,
      "dataSize": "1GB",
      "validity": "30 Days",
      "appPrice": 760,
      "developerPrice": 722
    }
  ]
}

Parameters & Schema Guide

Field	Description
`code`integerRequired	Unique numeric identifier of the plan to pass into /purchase-data
`network`stringRequired	Telecom carrier name (MTN, AIRTEL, GLO, 9MOBILE)
`networkId`integerRequired	Numeric carrier ID: 1=MTN, 2=Glo, 3=9Mobile, 4=Airtel
`dataSize`stringRequired	Bundle data allowance (e.g. 500MB, 1GB, 2GB, 5GB)
`validity`stringRequired	Bundle validity duration (e.g. "30 Days", "7 Days")
`developerPrice`numberRequired	Wholesale cost in NGN deducted from your wallet balance
`appPrice`numberRequired	Standard retail price in NGN before developer discount

💡 Developer Integration Tip:

Cache the plan catalog locally for 5–15 minutes to reduce API latency in your checkout flows.
Always use the integer "code" field as the plan identifier in your purchase requests.

Endpoint 04 · Core Data API

Purchase Mobile Data Bundle

Executes instant, automated data delivery to the specified Nigerian phone number. Guaranteed atomic wallet deduction with idempotency protection to eliminate double debit risks.

POST/api/v1/purchase-data

Scope: write:purchases

POST /api/v1/purchase-data (CURL)

$curl -X POST "https://saukimart.com/api/v1/purchase-data" \
-H "Content-Type: application/json" \
-H "x-api-key: sm_live_9a8b7c6d5e4f..." \
-d '{
    "phoneNumber": "08012345678",
    "planCode": 23,
    "network": 1,
    "idempotencyKey": "order_uuid_98f12a4c"
  }'

Example Response Payload (200 OK)

200 OK · application/json

{
  "success": true,
  "status": "success",
  "transactionId": "tx_a8f9c0e2_1948",
  "idempotencyKey": "order_uuid_98f12a4c",
  "data": {
    "planCode": 23,
    "network": "MTN",
    "phoneNumber": "08012345678",
    "dataSize": "1GB",
    "deliveryReference": "AMG-987654321"
  },
  "developerPrice": 332.5,
  "newBalance": 125098,
  "timestamp": "2026-08-21T14:30:00Z"
}

Parameters & Schema Guide

Field	Description
`phoneNumber`stringRequired	11-digit recipient Nigerian phone number (e.g. "08012345678")
`planCode`integerRequired	Bundle plan code obtained from GET /api/v1/data-plans
`network`integerRequired	Numeric carrier ID: 1 for MTN, 2 for Glo, 3 for 9Mobile, 4 for Airtel
`idempotencyKey`stringRequired	Unique UUIDv4 per customer order to prevent duplicate charges

💡 Developer Integration Tip:

Always supply a unique idempotencyKey per customer order. If network timeouts occur, retry with the EXACT SAME idempotencyKey.
Sandbox testing: Recipient number 08012345678 will simulate instant delivery with ₦0 wallet debit.

Endpoint 05 · Reconciliation

Query Transaction History

Fetch paginated developer transaction logs, carrier delivery receipts, and reconciliation records. Filter by status or idempotency key.

GET/api/v1/transactions

Scope: read:transactions

GET /api/v1/transactions (CURL)

$curl -X GET "https://saukimart.com/api/v1/transactions?limit=20&status=success" \
-H "x-api-key: sm_live_9a8b7c6d5e4f..."

Example Response Payload (200 OK)

200 OK · application/json

{
  "success": true,
  "version": "2026-04-17",
  "requestId": "req_tx_query_9812",
  "transactions": [
    {
      "id": "dev_tx_01",
      "transactionId": "tx_a8f9c0e2_1948",
      "status": "success",
      "phoneNumber": "08012345678",
      "network": "MTN",
      "planCode": "1-201",
      "planName": "MTN 1GB (30 Days)",
      "developerPrice": 332.5,
      "appPrice": 350,
      "idempotencyKey": "order_uuid_98f12a4c",
      "amigoReference": "AMG-987654321",
      "createdAt": "2026-08-21T14:30:00Z"
    }
  ]
}

Parameters & Schema Guide

Field	Description
`limit`query integer	Maximum records to return (default: 50, max: 200)
`status`query string	Filter by status: "success", "pending", "failed"
`idempotencyKey`query string	Filter by original request idempotency key
`transactionId`query string	Filter by specific SaukiMart transaction ID

💡 Developer Integration Tip:

Use query filtering to automate end-of-day reconciliation with your accounting ledgers.

Endpoint 06 · Reconciliation

Query Individual Transaction

Look up a single transaction by its SaukiMart Transaction ID, Internal DB UUID, or your original Idempotency Key. Critical for timeout recovery and polling pending fulfillment states.

GET/api/v1/transactions/:id

Scope: read:transactions

GET /api/v1/transactions/:id (CURL)

$curl -X GET "https://saukimart.com/api/v1/transactions/order_uuid_98f12a4c" \
-H "x-api-key: sm_live_9a8b7c6d5e4f..."

Example Response Payload (200 OK)

200 OK · application/json

{
  "success": true,
  "version": "2026-04-17",
  "requestId": "req_single_tx_5544",
  "transaction": {
    "id": "dev_tx_uuid_1029",
    "transactionId": "tx_a8f9c0e2_1948",
    "status": "success",
    "transactionStatus": "COMPLETED",
    "phoneNumber": "08012345678",
    "network": "MTN",
    "planCode": "1-201",
    "planName": "MTN 1GB (30 Days)",
    "developerPrice": 332.5,
    "appPrice": 350,
    "idempotencyKey": "order_uuid_98f12a4c",
    "amigoReference": "AMG-987654321",
    "rawStatus": "SUCCESSFUL",
    "endpoint": "/api/v1/purchase-data",
    "message": "Data bundle successfully delivered to recipient",
    "createdAt": "2026-08-21T14:30:00Z"
  },
  "environment": "live"
}

Parameters & Schema Guide

Field	Description
`:id (path)`stringRequired	SaukiMart Transaction ID, Internal UUID, or your request idempotencyKey
`transaction.status`stringRequired	Standardized delivery status: "success", "pending", or "failed"
`transaction.amigoReference`string \| null	Upstream telecom carrier reference code
`transaction.developerPrice`numberRequired	Exact amount in NGN deducted for this transaction
`transaction.idempotencyKey`string \| null	Original client idempotency key

💡 Developer Integration Tip:

If a POST /purchase-data call times out on your end, do NOT immediately retry with a new key. Call this endpoint with your idempotencyKey to inspect whether the initial purchase succeeded.
If the status is "pending", poll this endpoint with exponential backoff (e.g. 5s, 15s, 30s) or rely on incoming webhooks.

Webhooks & Events

Real-time Delivery Webhooks

Instead of polling the API, configure an HTTPS webhook URL in your developer dashboard. SaukiMart sends automated HTTP POST event dispatches whenever asynchronous telecom fulfillment completes or fails.

Incoming Webhook POST Event Payload

POST /api/webhooks/saukimart · application/json

{
  "event": "developer.purchase.completed",
  "transactionId": "tx_a8f9c0e2_1948",
  "status": "success",
  "planCode": 23,
  "network": "MTN",
  "phoneNumber": "08012345678",
  "dataSize": "1GB",
  "amount": 332.5,
  "idempotencyKey": "order_uuid_98f12a4c",
  "timestamp": "2026-08-21T14:30:05.000Z"
}

Webhook Event Catalog

Event	Trigger Condition	Expected Action
`developer.purchase.completed`	Carrier confirmed data bundle delivered to recipient	Mark order completed in your system and notify end-user
`developer.purchase.failed`	Carrier rejected fulfillment or invalid number	Refund end-user or prompt to re-enter phone number
`developer.wallet.low_balance`	Developer wallet balance fell below threshold (₦5,000)	Alert finance team to fund developer wallet

🔒 Webhook Signature Verification

If you configure a webhook signing secret in your dashboard, every webhook dispatch includes the X-SaukiMart-Webhook-Secret header. Verify this header matches your secret to protect against replay attacks.

// Express / Node.js Webhook Handler
app.post('/api/webhooks/saukimart', (req, res) => {
  const secret = req.headers['x-saukimart-webhook-secret'];
  if (secret !== process.env.SAUKIMART_WEBHOOK_SECRET) {
    return res.status(401).send('Unauthorized');
  }

  const { event, transactionId, status } = req.body;
  if (event === 'developer.purchase.completed') {
    // Fulfill customer order in your database
  }

  res.status(200).json({ received: true });
});

Reference & Diagnostics

HTTP Status Codes & Error Matrix

Every API failure returns a standard JSON error payload containing machine-readable error codes, human-friendly diagnostics, and an idempotent request tracking ID.

Standard Failure Response Schema

402 Payment Required · application/json

{
  "success": false,
  "error": "Insufficient wallet balance to fulfill purchase",
  "code": "INSUFFICIENT_FUNDS",
  "statusCode": 402,
  "requestId": "req_98f12a",
  "timestamp": "2026-08-21T14:30:00.000Z"
}

HTTP Status	Error Code	Description	Developer Action
200 OK	`SUCCESS`	Purchase executed and bundle vended successfully.	Parse transactionId and store confirmation in your database.
400 Bad Request	`INVALID_PARAMS`	Missing required fields (phoneNumber, planCode, or network).	Ensure request body satisfies schema requirements.
401 Unauthorized	`INVALID_API_KEY`	x-api-key header is missing, expired, or invalid.	Verify your key credentials in the Developer Dashboard.
402 Payment Required	`INSUFFICIENT_FUNDS`	Wallet balance is lower than developer wholesale price.	Fund your Sauki developer wallet via bank transfer.
404 Not Found	`PLAN_NOT_FOUND`	The specified planCode does not exist for this network.	Query GET /api/v1/data-plans for active bundles.
404 Not Found	`TRANSACTION_NOT_FOUND`	No transaction matching the provided ID or idempotency key.	Check reference string or verify transaction belongs to this key.
409 Conflict	`DUPLICATE_IDEMPOTENCY_KEY`	A purchase with this idempotencyKey was already processed.	Query GET /api/v1/transactions/:id to inspect original status.
422 Unprocessable	`INVALID_PHONE_NUMBER`	Recipient phone number is invalid (must be 11-digit Nigerian MSISDN).	Validate 11-digit phone format before sending.
429 Too Many Requests	`RATE_LIMIT_EXCEEDED`	Exceeded 90 requests/minute throughput.	Read Retry-After header and apply exponential backoff.
502 Bad Gateway	`PROVIDER_DOWN`	Upstream telecom carrier switch is temporarily unreachable.	Retry with the EXACT SAME idempotencyKey after a delay.
503 Unavailable	`MAINTENANCE`	Carrier bundle network is undergoing scheduled maintenance.	Check carrier status and retry during operational windows.

Architecture Reference

Rate Limiting & Idempotency Rules

SaukiMart enforces production-grade reliability primitives to guarantee zero double debits and maintain 99.99% infrastructure availability.

🔒 Zero Double Debit Guarantee

Every POST /api/v1/purchase-data request requires an idempotencyKey. If your server encounters a network timeout or 502 Bad Gateway, retrying with the exact same key guarantees your wallet is charged at most once.

⚡ Rate Limits & Response Headers

Production keys are provisioned for 90 requests/minute (custom limits up to 600 req/min available for enterprise). Every response returns:

X-RateLimit-Limit: Max requests allowed per window
X-RateLimit-Remaining: Remaining requests in current window
X-RateLimit-Reset: UTC ISO timestamp when window resets

SDKs & Resources

Developer SDKs & OpenAPI Specification

Accelerate your telecom integration with official code samples, OpenAPI 3.0 schemas, and Postman collections.

OpenAPI 3.0 Schema

Complete machine-readable JSON OpenAPI specification for code generators and Swagger UI.

View OpenAPI Spec

cURL & REST

Direct HTTP calls from any programming language or command-line environment.

View Samples

Node.js / TypeScript

Native Fetch, Axios, or HTTP client integrations with complete TypeScript types.

View Code

Python / Django / FastAPI

Requests and HTTPX client code snippets for instant backend vending.

View Code