Skip to main content
GET
/
v3
/
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>'
{
  "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

​
ref
string
required
Your custom reference from /mobile/send request

​
Response

Response format is identical to Check by ID.
​
success
boolean
required
Indicates if the request was successful
​
data
object
required
Top-up object with status, details, and refund information (if applicable). See Check by ID for complete field descriptions.
​
meta
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"

​
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

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
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.
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