Smile Airtime, Data & Voice API

Integrate using a secure HTTPS GET API. Responses are returned in JSON.

GET HTTPS JSON

Your Credentials

UserID

APIKey

********************************

Endpoints

Buy Smile Airtime, Data or Voice

APISmileV1.asp

https://www.nellobytesystems.com/APISmileV1.asp?UserID=your_userid&APIKey=your_apikey&MobileNetwork=smile-direct&DataPlan=dataplan_code&MobileNumber=smile_account_id&RequestID=request_id&CallBackURL=callback_url

Verify Smile Account

APIVerifySmileV1.asp

https://www.nellobytesystems.com/APIVerifySmileV1.asp?UserID=your_userid&APIKey=your_apikey&MobileNetwork=smile-direct&MobileNumber=smile_account_id

Query Transaction

By OrderID

https://www.nellobytesystems.com/APIQueryV1.asp?UserID=your_userid&APIKey=your_apikey&OrderID=order_id

By RequestID

https://www.nellobytesystems.com/APIQueryV1.asp?UserID=your_userid&APIKey=your_apikey&RequestID=request_id

Available Smile Packages (JSON)

Retrieve available Smile packages and variation codes:

APISmilePackagesV2.asp

https://www.nellobytesystems.com/APISmilePackagesV2.asp?UserID=

Try It (Quick Test)

Build a request URL for any Smile service. Sending a purchase uses your wallet balance; copying a URL does not submit it.

UserID

APIKey

MobileNetwork

Smile uses smile-direct as the network code.

Smile service

DataPlan (variation_code)

Get valid codes from APISmilePackagesV2.

MobileNumber (Smile Account ID)

RequestID (recommended)

CallBackURL (optional)

Idle

Request URL

—

Response

—

Operational Notes

Verify the Smile Account ID first using APIVerifySmileV1.
Use a unique RequestID to support safe retries and reconciliation.
Use APIQueryV1 to confirm final status for queued/processing transactions.
Cancellation is allowed only for ORDER_RECEIVED or ORDER_ONHOLD.

Request Parameters

Parameter	Description
UserID	Your account UserID.
APIKey	Your API key used to authenticate requests.
MobileNetwork	Smile network code: `smile-direct`.
DataPlan	`airtime` for an amount-based recharge, or a current data/voice package code from `APISmilePackagesV2`.
Amount	Required only when `DataPlan=airtime`: N100 to N50,000, digits with up to two decimal places. Omit for data/voice bundles; their server-side package price is used even if Amount is supplied.
MobileNumber	Recipient Smile Account ID. Despite the parameter name, supply the verified account ID, not an unrelated contact phone number.
RequestID	Unique request ID (recommended).
CallBackURL	Callback URL for asynchronous transaction status updates.
OrderID	Returned after request is received. Used for query/cancel operations.

Three services, one purchase endpoint

Keep MobileNetwork=smile-direct for airtime, data and SmileVoice. No new product-type request parameter is required.

Service	DataPlan	Amount
Airtime credit	`airtime`	Required: N100-N50,000
Data bundle	Current data package code	Omit; server uses package price
SmileVoice bundle	Current voice package code	Omit; server uses package price

Airtime adds credit; SmileVoice buys a specific minutes bundle. Verify the Smile Account ID first. Existing authentication and purchase-PIN requirements still apply.

Airtime example:

https://www.nellobytesystems.com/APISmileV1.asp?UserID=YOUR_USER_ID&APIKey=YOUR_API_KEY&MobileNetwork=smile-direct&DataPlan=airtime&Amount=2000&MobileNumber=SMILE_ACCOUNT_ID&RequestID=UNIQUE_REQUEST_ID

Voice example: code 804 is an example from the current catalogue; always refresh available codes.

https://www.nellobytesystems.com/APISmileV1.asp?UserID=YOUR_USER_ID&APIKey=YOUR_API_KEY&MobileNetwork=smile-direct&DataPlan=804&MobileNumber=SMILE_ACCOUNT_ID&RequestID=UNIQUE_REQUEST_ID

Examples

Sample: Buy a Smile data bundle (example code 843). Fetch the current catalogue before purchase.

Replace credentials with yours

https://www.nellobytesystems.com/APISmileV1.asp?UserID=CK123&APIKey=456&MobileNetwork=smile-direct&DataPlan=843&MobileNumber=1234567890&RequestID=789&CallBackURL=http://www.your-website.com

Immediate response (sample)

{
  "orderid": "789",
  "statuscode": "100",
  "status": "ORDER_RECEIVED"
}

Query by OrderID

https://www.nellobytesystems.com/APIQueryV1.asp?UserID=CK123&APIKey=456&OrderID=789

Query response (sample)

{
  "date": "17th-Mar-2019",
  "orderid": "798",
  "requestid": "",
  "statuscode": "200",
  "status": "ORDER_COMPLETED",
  "remark": "TRANSACTION SUCCESSFUL",
  "ordertype": "1GB Flexi for 1days - 300 Naira",
  "mobilenumber": "1234567890",
  "amountcharged": "2000",
  "walletbalance": "863210.1"
}

Cancel an Order (OrderID 789)

https://www.nellobytesystems.com/APICancelV1.asp?UserID=CK123&APIKey=456&OrderID=789

Cancel response (sample)

{
  "status": "ORDER_CANCELLED",
  "orderid": "789"
}

Note: You can only cancel transactions whose status is ORDER_RECEIVED or ORDER_ONHOLD.

Verify Smile Account

Verify the Smile Account ID before purchase. A successful verification returns the account holder name.

Verify request

https://www.nellobytesystems.com/APIVerifySmileV1.asp?UserID=CK123&APIKey=456&MobileNetwork=smile-direct&MobileNumber=1234567890

Verify response (success)

{
  "customer_name": "BALOGUN SUNDAY LIV LADORITE"
}

Verify response (error)

{
  "customer_name": "INVALID_ACCOUNTNO"
}

Callback (CallBackURL)

After processing, we will call your CallBackURL with the OrderID, StatusCode, OrderStatus, and OrderRemark. You can also use APIQueryV1 to confirm final status.

Callback example (query string)

https://your_callback_url?orderdate=22th-Jul-2023&orderid=6501321715&statuscode=200&orderstatus=ORDER_COMPLETED&orderremark=TRANSACTION%20SUCCESSFUL

Callback example (JSON)

{
  "orderdate": "22th-Jul-2023",
  "orderid": "6501321715",
  "requestid": "",
  "statuscode": "200",
  "orderstatus": "ORDER_COMPLETED",
  "orderremark": "TRANSACTION SUCCESSFUL"
}

Status Codes

Common responses are listed below. For the full list, use: View full list of Status Code and Descriptions

STATUS	DESCRIPTION
`INVALID_CREDENTIALS`	The UserID and API key combination is not correct.
`MISSING_CREDENTIALS`	The URL format is not valid.
`MISSING_USERID`	UserID is empty.
`MISSING_APIKEY`	APIKey is empty.
`MISSING_MOBILENETWORK`	MobileNetwork is empty.
`MISSING_DATAPLAN`	DataPlan is empty.
`INVALID_AIRTIME_AMOUNT`	Airtime requires Amount between N100 and N50,000, with up to two decimal places.
`INVALID_PRODUCT_AMOUNT`	Package price is unavailable or invalid; refresh the catalogue.
`INVALID_ACCOUNTNO`	An invalid Smile Account ID was entered.
`DATAPLAN_NOT_AVAILABLE`	Selected data plan is not currently available.
`ORDER_RECEIVED`	Your order has been received.

Since we use a GET API, responses are returned in JSON.

Smile Packages (Optional Display)

Each product retains its existing fields and adds PRODUCT_TYPE (airtime, data, voice) and boolean AMOUNT_REQUIRED. MINAMOUNT/MAXAMOUNT apply to customer-entered airtime amounts only. Mixed bundles remain under data; use the full product name for details.

{"PACKAGE_ID":"airtime","PACKAGE_NAME":"Buy Airtime","PACKAGE_AMOUNT":"0.00","PRODUCT_TYPE":"airtime","AMOUNT_REQUIRED":true,"MINAMOUNT":100,"MAXAMOUNT":50000}

This abbreviated example omits the unchanged discount fields. Zero is the airtime catalogue marker, not a free purchase. An unavailable catalogue returns an error; do not submit a guessed code or price.

You can display Smile package codes and names server-side (as you do with APIVTPassServiceVariations), or call APISmilePackagesV2 to retrieve packages in JSON format. For performance, consider caching results briefly (e.g., 5–15 minutes).

Packages endpoint

https://www.nellobytesystems.com/APISmilePackagesV2.asp?UserID=

Smile Airtime, Data & Voice API

Latest Posts

Useful Links

Contact Us