API Documentation

Information

The 2FAST Business API lets you integrate airtime top-ups, data purchases, MTN FibreX activations, AirtimeToCash conversions and transaction history into your own product. Every endpoint speaks JSON, returns standard HTTP status codes, and authenticates with your API key.

All amounts are Naira (NGN). All timestamps are ISO 8601 UTC.

Environment

Live base URL	`https://2fast.com.ng/api`
Test base URL	`https://sanbox.2fast.com.ng/api` coming soon
Content-Type	`application/json`

Authorization

Every request must carry your API key in the Authorization header:

Authorization: Bearer <YOUR_API_KEY>

Requests without a valid API key are rejected with 401 Unauthorized.

Errors

All errors follow the same JSON shape:

{
  "status": "error",
  "message": "A human-readable description of what went wrong."
}

200	Request succeeded.
400	Invalid input (bad plan_id, missing field, wrong format).
401	Missing or invalid API key.
402	Insufficient wallet balance.
404	Resource not found (e.g. unknown transaction reference).
500	Unexpected server error. Safe to retry after a delay.
502	Upstream telecom error. Safe to retry.

GET/get-wallet-balance

Get Wallet Balance

Returns your current 2FAST wallet balance in NGN.

Request

curl -X GET https://2fast.com.ng/api/get-wallet-balance \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Response

{
  "status": "success",
  "balance": 12500.75,
  "currency": "NGN"
}

GET/ (reference)

Get Network ID

Every request that targets a network uses a numeric network ID. These IDs are fixed.

1	MTN
2	Airtel
3	Glo
4	9mobile

GET/verify-fibrex/{fibrexNumber}

Verify FibreX

Verifies a FibreX customer ID (e.g. FN12345) using an MTN FibreX-enabled SIM on your account (Sim route) or the platform pool (Wallet route), and returns the registered customer name and address.

Request

curl -X GET https://2fast.com.ng/api/verify-fibrex/FN12345 \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Response

{
  "status": "success",
  "message": "Fibrex customer found.",
  "customerName": "John Doe",
  "customerAddress": "12 Example Street, Ikeja, Lagos"
}

POST/data-plans

Get Data Plan

Fetches the list of active data plans for a given network. Pass the network ID or its label (MTN / AIRTEL / GLO).

Request

curl -X POST https://2fast.com.ng/api/data-plans \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"network": 1}'

Response

{
  "status": "success",
  "network": "MTN",
  "count": 42,
  "data": [
    {
      "plan_id": "1001",
      "volume": "1GB",
      "type": "GIFTING",
      "validity": "30 Days",
      "our_price": 260,
      "telecom_price": 250,
      "description": "MTN 1GB gifting bundle",
      "sim": "Yes",
      "wallet": "Yes",
      "device": "No",
      "status": "Active"
    }
  ]
}

GET/fibrex-plan

Get FibreX Plan

Fetches the list of active MTN FibreX plans.

Request

curl -X GET https://2fast.com.ng/api/fibrex-plan \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Response

{
  "status": "success",
  "count": 6,
  "data": [
    {
      "volume": "50Mbps",
      "plan_id": "FX-50-30D",
      "our_price": 27500,
      "telecom_price": 27000,
      "description": "FibreX Monthly Data Only - 50Mbps",
      "status": "Active"
    }
  ]
}

POST/data

Sell Data

Sells data (or activates a FibreX plan) to a beneficiary. For FibreX, pass the FibreX ID as phoneNumber.

networkId	Numeric ID (see Get Network ID).
planId	plan_id from Get Data Plan or Get FibreX Plan.
phoneNumber	Beneficiary MSISDN, or FibreX ID for FibreX plans.
reference	Unique idempotency key you generate. Reuse of the same reference returns the original result.

Request

curl -X POST https://2fast.com.ng/api/data \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "networkId": 1,
    "planId": "1001",
    "phoneNumber": "08012345678",
    "reference": "ORD-1727530000-abc123"
  }'

Response

{
  "status": "success",
  "message": "Gifted 1GB to 2348012345678. It will expire on 27 Oct 2026."
}

POST/airtime

Sell Airtime

Sells airtime to a beneficiary. Type is VTU by default; MTN also supports Share & Sell and AWOOF variants.

networkId	Numeric network ID.
type	VTU (default), or MTN Share & Sell / AWOOF where enabled.
amount	Positive integer in NGN.
phoneNumber	Beneficiary MSISDN.
reference	Unique idempotency key.

Request

curl -X POST https://2fast.com.ng/api/airtime \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "networkId": 1,
    "type": "VTU",
    "amount": 500,
    "phoneNumber": "08012345678",
    "reference": "AIR-1727530000-abc123"
  }'

Response

{
  "status": "success",
  "message": "You have successfully vended N500 to 2348012345678."
}

POST/Airtime-To-Cash

Automated AirtimeToCash · Step 1 (Request OTP)

Registers the sender SIM and asks the network to send an OTP to it. network is 1 for MTN or 2 for Airtel. If the SIM was already verified before, no OTP is sent: the reply carries skip_otp together with the identifier, and you go straight to step 3.

network	1 = MTN, 2 = Airtel.
step	1
phone_number	Sender MSISDN that holds the airtime.

Request

curl -X POST https://2fast.com.ng/api/Airtime-To-Cash \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "network": 1,
    "step": 1,
    "phone_number": "08012345678"
  }'

Response

// OTP sent
{
  "status": "success",
  "message": "OTP sent successfully."
}

// SIM already verified - skip step 2
{
  "status": "success",
  "message": "This SIM is already active. Please proceed to convert airtime.",
  "identifier": "1f4a9c62-1f2b-4c0e-9a1f-9b0c0f7a51d3",
  "skip_otp": true
}

// Failure
{
  "status": "error",
  "message": "MTN OTP request failed."
}

POST/Airtime-To-Cash

Automated AirtimeToCash · Step 2 (Verify OTP)

Verifies the OTP the sender received. On success the SIM is stored as Active and the reply returns the identifier you must send in step 3, plus the sender's current airtime balance.

network	1 = MTN, 2 = Airtel.
step	2
phone_number	Same sender MSISDN used in step 1.
otp	6 digits for MTN, 4 digits for Airtel.

Request

curl -X POST https://2fast.com.ng/api/Airtime-To-Cash \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "network": 1,
    "step": 2,
    "phone_number": "08012345678",
    "otp": "123456"
  }'

Response

// Success
{
  "status": "success",
  "message": "OTP verified successfully. Your airtime balance is NGN 4500.",
  "identifier": "1f4a9c62-1f2b-4c0e-9a1f-9b0c0f7a51d3",
  "airtime_balance": 4500
}

// Failure
{
  "status": "error",
  "message": "MTN OTP verification failed."
}

POST/Airtime-To-Cash

Automated AirtimeToCash · Step 3 (Convert)

Moves the airtime off the sender SIM. On the Sim route the airtime is shared to one of your own receiver SIMs and only the fee is charged to your wallet; on the Wallet route the airtime goes to a platform SIM and your wallet is credited with the amount less the agreed rate. Each reference may only be used once.

network	1 = MTN, 2 = Airtel.
step	3
identifier	Value returned by step 1 (skip_otp) or step 2.
reference	Unique idempotency key you generate.
amount	NGN to convert. Maximum 10,000 on MTN and 20,000 on Airtel.
sender	Sender MSISDN holding the airtime.
pin	MTN Share & Sell PIN, or Airtel Me2U PIN.

Request

curl -X POST https://2fast.com.ng/api/Airtime-To-Cash \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "network": 1,
    "step": 3,
    "identifier": "1f4a9c62-1f2b-4c0e-9a1f-9b0c0f7a51d3",
    "reference": "A2C-1727530000-abc123",
    "amount": 1000,
    "sender": "08012345678",
    "pin": "1234"
  }'

Response

// Sim route success (balance lines appear only when enabled in your settings)
{
  "status": "success",
  "message": "Airtime of NGN 1000 shared successfully. Sender's New Balance: NGN 3500. Receiver's New Balance: NGN 12000."
}

// Wallet route success
{
  "status": "success",
  "message": "Airtime of NGN 1000 converted to wallet successfully."
}

// Failures
{
  "status": "error",
  "message": "Duplicate reference. This transaction has already been processed."
}
{
  "status": "error",
  "message": "Insufficient wallet balance to cover the transaction fee."
}
{
  "status": "error",
  "message": "No available receiver SIM can accept this amount at the moment."
}
{
  "status": "error",
  "message": "MTN transfer failed. Your fee has been refunded."
}

POST/transaction-history

Get Transaction History

Look up any transaction by its reference. Searches wallet history first, then Datashare history.

Request

curl -X POST https://2fast.com.ng/api/transaction-history \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"reference": "ORD-1727530000-abc123"}'

Response

{
  "status": "success",
  "source": "wallet_history",
  "data": {
    "reference": "ORD-1727530000-abc123",
    "network": "MTN",
    "type": "GIFTING",
    "volume": "1GB",
    "beneficiary": "2348012345678",
    "amount": 260,
    "fee": 0,
    "balance_before": 12760.75,
    "balance_after": 12500.75,
    "status": "Successful",
    "response": "Gifted 1GB to 2348012345678.",
    "date": "2026-09-28T15:20:00Z"
  }
}

Webhook · Introduction

Configure a single HTTPS callback URL under Settings → Webhook. After every telecom transaction finalises (success or failure), 2FAST POSTs a small JSON payload to your URL:

POST <your webhook URL>
Content-Type: application/json

{
  "request-id": "ORD-1727530000-abc123",
  "status": "success",
  "api_response": "Gifted 1GB to 2348012345678."
}

request-id is the reference you sent on the original request.
status is either success or fail.
api_response is the same human-readable message returned from the API.

Respond with a 2xx status within 10 seconds. Non-2xx responses are logged for review.