Check Status by Reference

curl --request GET \
  --url https://api.oneclickdz.com/v3/mobile/check-ref/{ref} \
  --header 'X-Access-Token: <api-key>'

const options = {method: 'GET', headers: {'X-Access-Token': '<api-key>'}};

fetch('https://api.oneclickdz.com/v3/mobile/check-ref/{ref}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.oneclickdz.com/v3/mobile/check-ref/{ref}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Access-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.oneclickdz.com/v3/mobile/check-ref/{ref}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Access-Token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.oneclickdz.com/v3/mobile/check-ref/{ref}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Access-Token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {},
  "meta": {}
}

GET

mobile

check-ref

{ref}

Check Status by Reference

curl --request GET \
  --url https://api.oneclickdz.com/v3/mobile/check-ref/{ref} \
  --header 'X-Access-Token: <api-key>'

const options = {method: 'GET', headers: {'X-Access-Token': '<api-key>'}};

fetch('https://api.oneclickdz.com/v3/mobile/check-ref/{ref}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.oneclickdz.com/v3/mobile/check-ref/{ref}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Access-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.oneclickdz.com/v3/mobile/check-ref/{ref}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Access-Token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.oneclickdz.com/v3/mobile/check-ref/{ref}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Access-Token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {},
  "meta": {}
}

Overview

Track mobile top-up status using the ref parameter you provided when sending the top-up. This is useful when you want to check status using your own order IDs. This endpoint allows you to track orders using the reference you provided when creating the top-up. If you didn’t provide a reference, use the auto-generated one returned in the send response.

See Check by ID documentation for detailed status descriptions and handling guidelines.

Path Parameters

string

required

Your custom reference from /mobile/send request

Response

Response format is identical to Check by ID.

boolean

required

Indicates if the request was successful

object

required

Top-up object with status, details, and refund information (if applicable). See Check by ID for complete field descriptions.

object

required

Metadata with timestamp in ISO 8601 format

Examples

curl https://api.oneclickdz.com/v3/mobile/check-ref/order-12345 \
  -H "X-Access-Token: YOUR_API_KEY"

const orderRef = "order-12345";
const response = await fetch(
  `https://api.oneclickdz.com/v3/mobile/check-ref/${orderRef}`,
  { headers: { "X-Access-Token": "YOUR_API_KEY" } }
);
const { data } = await response.json();

order_ref = 'order-12345'
response = requests.get(
    f'https://api.oneclickdz.com/v3/mobile/check-ref/{order_ref}',
    headers={'X-Access-Token': 'YOUR_API_KEY'}
)
status = response.json()['data']['status']

<?php
$orderRef = 'order-12345';
$url = "https://api.oneclickdz.com/v3/mobile/check-ref/{$orderRef}";
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-Access-Token: YOUR_API_KEY']);
$response = json_decode(curl_exec($ch), true);
?>

Response Example

{
  "success": true,
  "data": {
    "_id": "6901616fe9e88196b4eb64b0",
    "ref": "order-12345",
    "status": "FULFILLED",
    "plan_code": "PREPAID_DJEZZY",
    "MSSIDN": "0778037340",
    "topup_amount": 500,
    "balance_amount": 490,
    "created_at": "2025-10-29T00:35:59.378Z"
  },
  "meta": {
    "timestamp": "2025-10-29T00:36:15.606Z"
  },
  "requestId": "req_1730160975_xyz789"
}

When to Use This Endpoint

User Queries

When users ask about their order using your order ID

Order Management

Integrate with your existing order tracking system

Status Pages

Display order status using customer-facing references

Customer Support

Look up orders by customer reference numbers

Status Values & Handling

See Check by ID for detailed status descriptions and handling instructions.

Error Response

404 - Not Found:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Top-up with reference 'order-12345' not found"
  },
  "requestId": "req_1730160975_abc123"
}

This means no top-up exists with that reference. Possible reasons:

Reference was never submitted
Typo in reference
Reference belongs to different account

Best Practices

Use Meaningful References

Create references that are:

Unique across your system
Easy to identify (e.g., order-{timestamp}-{userId})
URL-safe (no special characters)
Searchable in your database

Store Both IDs

Save both your reference and the API’s topupId:

await db.orders.update({
  orderId: 'order-12345',
  apiTopupId: response.data.topupId,
  apiTopupRef: response.data.topupRef
});

This allows you to track using either identifier.

Handle Missing References

If you forget to provide a ref, the API generates one. Save it:

const response = await sendTopup({ 
  plan_code: 'PREPAID_DJEZZY',
  MSSIDN: '0778037340',
  amount: 500
  // No ref provided
});

// API returns: { topupRef: "auto-gen-1730160975" }
await db.orders.update({
  orderId: order.id,
  apiRef: response.data.topupRef
});

Check by ID

Track using internal top-up ID

Send Top-Up

Create a new top-up

List Top-Ups

View all top-ups

API Reference

Core

Account

Mobile Top-Ups

Internet Top-Ups

Gift Cards

Navio

Check Status by Reference

Overview

Path Parameters

Response

Examples

Response Example

When to Use This Endpoint

User Queries

Order Management

Status Pages

Customer Support

Status Values & Handling

Error Response

Best Practices

Check by ID

Send Top-Up

List Top-Ups

​Overview

​Path Parameters

​Response

​Examples

​Response Example

​When to Use This Endpoint

User Queries

Order Management

Status Pages

Customer Support

​Status Values & Handling

​Error Response

​Best Practices

​Related Endpoints

Check by ID

Send Top-Up

List Top-Ups

Overview

Path Parameters

Response

Examples

Response Example

When to Use This Endpoint

Status Values & Handling

Error Response

Best Practices

Related Endpoints