Check Status by ID

Overview

Track mobile top-up status using the topupId returned from the send endpoint. Generally, our servers will process your request in about 5-30 seconds.

Important: It’s mandatory to understand all possible statuses to properly handle updating and notifying your users.

Path Parameters

string

required

Internal top-up ID from /mobile/send response

Response

success

boolean

required

Indicates if the request was successful

data

object

required

Show properties

_id

string

required

Top-up identifier

ref

string

Your custom reference (if provided)

status

string

required

Current status: PENDING, HANDLING, FULFILLED, REFUNDED, or UNKNOWN_ERROR

plan_code

string

required

Plan code used

MSSIDN

string

required

Phone number

topup_amount

number

required

Top-up amount in DZD

balance_amount

number

required

Amount deducted from your balance

created_at

string

required

Creation timestamp (ISO 8601)

refund_message

string

Arabic message for end-user (only if REFUNDED or UNKNOWN_ERROR)

suggested_offers

array

Alternative plans if plan mismatch (only if REFUNDED)

Show properties

typename

string

Display name of the suggested plan

plan_code

string

Plan code to use

amount

number

Suggested amount

follow_orderid

string

Follow-up order ID if order was redirected

retry_orderid

string

Retry order ID if order was retried

Status Values

PENDING

The PENDING status indicates that the order has been created and is currently in the queue, awaiting processing by one of our servers. It will be processed as soon as possible.Typical duration: 2-15 secondsAction: Continue polling every 5-10 seconds

HANDLING

The HANDLING status indicates that the order is currently being processed by one of our servers.Typical duration: 3-8 secondsAction: Continue polling every 5-10 seconds

FULFILLED

The FULFILLED status indicates that the mobile top-up has been successfully sent. ✅Action: Update order status to completed, notify user

REFUNDED

The REFUNDED status indicates that the mobile top-up has been refunded. ❌Fields available:

refund_message: Show this to user (in Arabic)
suggested_offers: Alternative plans (if plan mismatch)

Action: Refund user, display message, offer alternatives

UNKNOWN_ERROR

The UNKNOWN_ERROR status indicates that the mobile top-up might have been successful or failed. The status will update within 1 to 12 hours to either FULFILLED or REFUNDED after manual check by our support team. We will be notified immediately and no action from your part is required. ⚠️Such errors happen due to the nature of AT Commands and unexpected behaviors from operators (new messages, network issues, etc.).

YOU SHOULD NOT REFUND THE AMOUNT to your user at this status!

Action:

Show refund_message to user
DO NOT refund immediately
Set a daily cronjob to check UNKNOWN_ERROR orders and update to FULFILLED or REFUNDED
Check again after 24 hours
Then handle refunds if status becomes REFUNDED

Examples

curl https://api.oneclickdz.com/v3/mobile/check-id/6901616fe9e88196b4eb64b0 \
  -H "X-Access-Token: YOUR_API_KEY"

Fulfilled Response

{
  "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_abc123"
}

Refunded Response

{
  "success": true,
  "data": {
    "_id": "6901616fe9e88196b4eb64b0",
    "ref": "order-12345",
    "status": "REFUNDED",
    "plan_code": "PREPAID_DJEZZY",
    "MSSIDN": "0778037340",
    "topup_amount": 500,
    "balance_amount": 490,
    "created_at": "2025-10-29T00:35:59.378Z",
    "refund_message": "الرصيد المطلوب غير متوفر لهذا الرقم"
  },
  "meta": {
    "timestamp": "2025-10-29T00:36:15.606Z"
  },
  "requestId": "req_1730160975_def456"
}

Refunded with Suggested Offers

When the plan code doesn’t match the phone number type, you’ll receive suggested alternatives:

{
  "success": true,
  "data": {
    "_id": "6901616fe9e88196b4eb64b0",
    "ref": "order-12345",
    "status": "REFUNDED",
    "plan_code": "PREPAID_DJEZZY",
    "MSSIDN": "0778037340",
    "topup_amount": 500,
    "balance_amount": 490,
    "created_at": "2025-10-29T00:35:59.378Z",
    "refund_message": "هذا العرض غير متوافق مع هذا الرقم جرب فاتورة",
    "suggested_offers": [
      {
        "typename": "📋 FACTURE | فاتورة",
        "plan_code": "FACTURE_DJEZZY",
        "amount": 500
      }
    ]
  },
  "meta": {
    "timestamp": "2025-10-29T00:36:15.606Z"
  },
  "requestId": "req_1730160975_ghi789"
}

PLEASE NOTE: suggested_offers is an array and can contain multiple items, for example when you send GETMENU plans.

Polling Strategy

Syncing Our API with Your Backend

Start Polling

Begin checking status immediately after sending top-up. One simple approach is setting an interval of 5-10 seconds on your frontend to check the status. Once the status is FULFILLED, REFUNDED, or UNKNOWN_ERROR, clear the interval and stop sending requests.

const topupId = response.data.topupId;
const status = await pollStatus(topupId);

Poll Interval

Check every 5-10 seconds while PENDING or HANDLING. This approach will keep requests minimal (5-10 per transaction).On each GET request from your users, you can read the status in your database. Only if the status is not FULFILLED, REFUNDED, or UNKNOWN_ERROR, send a check request to our API, update your database, then reply to your user.

async function pollStatus(topupId, maxAttempts = 60) {
  for (let i = 0; i < maxAttempts; i++) {
    const { data } = await checkTopupStatus(topupId);
    
    if (['FULFILLED', 'REFUNDED', 'UNKNOWN_ERROR'].includes(data.status)) {
      return data;
    }
    
    await sleep(5000); // Wait 5 seconds
  }
  throw new Error('Timeout');
}

Handle Result

Update order based on final status

if (status === 'FULFILLED') {
  await markOrderComplete(orderId);
} else if (status === 'REFUNDED') {
  await refundUser(orderId);
  await notifyUser(refund_message);
} else if (status === 'UNKNOWN_ERROR') {
  await markForReview(orderId);
  // DO NOT refund yet - wait for daily cronjob
}

Complete Polling Example

async function pollTopupStatus(topupId) {
  const maxAttempts = 60; // 5 minutes max
  const pollInterval = 5000; // 5 seconds

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.oneclickdz.com/v3/mobile/check-id/${topupId}`,
      { headers: { "X-Access-Token": process.env.API_KEY } }
    );

    const { data } = await response.json();

    // Final states
    if (["FULFILLED", "REFUNDED", "UNKNOWN_ERROR"].includes(data.status)) {
      return data;
    }

    // Still processing
    console.log(`Attempt ${i + 1}: Status is ${data.status}`);
    await new Promise((resolve) => setTimeout(resolve, pollInterval));
  }

  throw new Error("Polling timeout after 5 minutes");
}

// Usage
try {
  const result = await pollTopupStatus("6901616fe9e88196b4eb64b0");
  console.log("Final status:", result.status);
} catch (error) {
  console.error("Polling failed:", error.message);
}

Handling UNKNOWN_ERROR

Do NOT refund immediately when status is UNKNOWN_ERROR!

The UNKNOWN_ERROR status indicates uncertainty about whether the top-up succeeded or failed. This happens due to the nature of AT Commands and unexpected behaviors from operators (new messages, network issues, etc.).

Show Message

Display refund_message to user explaining the delayExample message: “هذه العملية حالتها غير معروفة، يرجى التأكد مع عميلك، ولن نتحمل أي مسؤولية عن أي خسائر. إذا فشلت العملية بالفعل، فلا تقلق، سيتم استرداد أموالك خلال 24 ساعة”

Mark for Review

Flag the order for manual review or automated recheck. We will be notified immediately and no action from your part is required.

Automated Recheck

Set up daily cronjob to check uncertain orders. The status will update within 1-12 hours (up to 24h) to either FULFILLED or REFUNDED after manual check by our support team.

// Daily at midnight
cron.schedule('0 0 * * *', async () => {
  const uncertainOrders = await db.orders.find({
    status: 'UNKNOWN_ERROR',
    createdAt: { $lt: new Date(Date.now() - 24*60*60*1000) }
  });
  
  for (const order of uncertainOrders) {
    const status = await checkTopupStatus(order.apiTopupId);
    await updateOrderStatus(order.id, status.data.status);
    
    // Now handle refund if status is REFUNDED
    if (status.data.status === 'REFUNDED') {
      await processRefund(order);
    }
  }
});

Final Resolution

Status will update to FULFILLED or REFUNDED within 24 hours. Only then should you process refunds if the final status is REFUNDED.

Best Practices

Cache Status

Store status in your database to minimize API calls. Only query our API when status is not final (PENDING/HANDLING).

Stop on Final State

Don’t poll after FULFILLED, REFUNDED, or UNKNOWN_ERROR

Timeout Protection

Set maximum polling attempts (typically 60 = 5 minutes)

Error Handling

Handle network errors with retry logic

Show Arabic Messages

Always display refund_message to users - it’s in Arabic and explains the issue

Offer Alternatives

When suggested_offers is present, update your UI to show these plans instead of all plans

Handling Refunds

A refund_message (Arabic message) will be added to the top-up operation, and you should show it as-is to your client. Example scenarios:

Wrong Phone Number

If your client types a wrong phone number:

refund_message: "رقم الهاتف خاطئ، يرجى التأكد مع العميل"

Plan Mismatch

If trying to send PREPAID_DJEZZY to a facture (postpaid) phone number:

{
  "refund_message": "هذا العرض غير متوافق مع هذا الرقم جرب فاتورة",
  "suggested_offers": [
    {
      "typename": "📋 FACTURE | فاتورة",
      "plan_code": "FACTURE_DJEZZY",
      "amount": 500
    }
  ]
}

Suggested Offers Array

The suggested_offers array shows the correct plans for the phone number. Update your app UI to represent these new plans instead of showing all plans.

suggested_offers is an array and can contain multiple items, especially when you send GETMENU requests.

Sandbox Testing

Enable the sandbox at your settings page to test requests without affecting your balance. All operations will emulate a real operation:

Normal Flow

Any normal phone number:

First 5 seconds: status PENDING
First 15 seconds: status HANDLING
Then: status FULFILLED

After integrating the fulfilled flow, proceed to test other statuses.

Test Refund with Message

Phone: 0600000001Test REFUNDED status with refund_message that should be shown to client

Test Refund with Suggestions

Phone: 0600000002Test REFUNDED status with refund_message and suggested_offers

Test Unknown Error

Phone: 0600000003Test UNKNOWN_ERROR status to ensure your daily cronjob logic works correctly

Check by Reference

Track using your custom reference

Send Top-Up

Create a new top-up

API Reference

Core

Account

Mobile Top-Ups

Internet Top-Ups

Gift Cards

Overview

Path Parameters

Response

Status Values

Examples

Fulfilled Response

Refunded Response

Refunded with Suggested Offers

Polling Strategy

Syncing Our API with Your Backend

Complete Polling Example

Handling UNKNOWN_ERROR

Best Practices

Cache Status

Stop on Final State

Timeout Protection

Error Handling

Show Arabic Messages

Offer Alternatives

Handling Refunds

Wrong Phone Number

Plan Mismatch

Suggested Offers Array

Sandbox Testing

Check by Reference

Send Top-Up

API Reference

Core

Account

Mobile Top-Ups

Internet Top-Ups

Gift Cards

​Overview

​Path Parameters

​Response

​Status Values

​Examples

​Fulfilled Response

​Refunded Response

​Refunded with Suggested Offers

​Polling Strategy

​Syncing Our API with Your Backend

​Complete Polling Example

​Handling UNKNOWN_ERROR

​Best Practices

Cache Status

Stop on Final State

Timeout Protection

Error Handling

Show Arabic Messages

Offer Alternatives

​Handling Refunds

​Wrong Phone Number

​Plan Mismatch

​Suggested Offers Array

​Sandbox Testing

​Related Endpoints

Check by Reference

Send Top-Up

Overview

Path Parameters

Response

Status Values

Examples

Fulfilled Response

Refunded Response

Refunded with Suggested Offers

Polling Strategy

Syncing Our API with Your Backend

Complete Polling Example

Handling UNKNOWN_ERROR

Best Practices

Handling Refunds

Wrong Phone Number

Plan Mismatch

Suggested Offers Array

Sandbox Testing

Related Endpoints