Skip to main content

​
Overview

After sending an internet top-up order, poll the /check-id endpoint to track status and retrieve card details when fulfilled. Most orders complete within 3-45 seconds, but some may be QUEUED for 12-48 hours.
Poll every 5-10 seconds until order reaches a final state: FULFILLED, REFUNDED, or QUEUED.

​
API Reference

GET /v3/internet/check-id/{id}

Complete endpoint documentation

​
Order Status Values

Order is processing with the operator. Typical time: 3-45 seconds. Continue polling every 5-10 seconds.
Success! Card delivered. card_code, num_trans, and date_traitement available. Deliver to customer immediately.
Scheduled for later. Order will be processed within 12-48 hours. Not a failure - schedule recheck after 24 hours and inform customer.
Failed. Order cancelled and refunded automatically. Notify customer of failure.

​
Basic Status Check

async function checkTopupStatus(topupId) {
  const response = await fetch(
    `https://api.oneclickdz.com/v3/internet/check-id/${topupId}`,
    {
      headers: {
        "X-Access-Token": process.env.API_KEY,
      },
    }
  );

  if (!response.ok) {
    throw new Error(`Failed to check status: ${response.status}`);
  }

  const result = await response.json();
  return result.data;
}

// Usage
const topupId = "6901616fe9e88196b4eb64b2";
const order = await checkTopupStatus(topupId);

console.log(`Status: ${order.status}`);
console.log(`Type: ${order.type}`);
console.log(`Number: ${order.number}`);

if (order.card_code) {
  console.log(`Card Code: ${order.card_code}`);
  console.log(`Transaction: ${order.num_trans}`);
}

​
Response Examples

​
Handling (Processing)

{
  "success": true,
  "data": {
    "_id": "6901616fe9e88196b4eb64b2",
    "ref": "order-123456",
    "status": "HANDLING",
    "type": "ADSL",
    "number": "036362608",
    "topup_amount": 1000,
    "created_at": "2025-11-01T12:00:00.000Z"
  }
}

​
Fulfilled (Success)

{
  "success": true,
  "data": {
    "_id": "6901616fe9e88196b4eb64b2",
    "ref": "order-123456",
    "status": "FULFILLED",
    "type": "ADSL",
    "number": "036362608",
    "topup_amount": 1000,
    "card_code": "123456789012",
    "num_trans": "AT-2025-12345",
    "date_traitement": "2025-11-01T12:00:45.000Z",
    "created_at": "2025-11-01T12:00:00.000Z"
  }
}

​
Queued (Scheduled)

{
  "success": true,
  "data": {
    "_id": "6901616fe9e88196b4eb64b2",
    "ref": "order-123456",
    "status": "QUEUED",
    "type": "ADSL",
    "number": "036362608",
    "topup_amount": 1000,
    "created_at": "2025-11-01T12:00:00.000Z"
  }
}

​
Basic Polling Implementation

async function pollTopupUntilComplete(topupId, maxAttempts = 60) {
  const pollInterval = 5000; // 5 seconds
  
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    console.log(`Polling attempt ${attempt}/${maxAttempts}`);
    
    const order = await checkTopupStatus(topupId);
    
    // Check if order reached final state
    const finalStates = ['FULFILLED', 'REFUNDED', 'QUEUED'];
    if (finalStates.includes(order.status)) {
      console.log(`Order completed with status: ${order.status}`);
      return order;
    }
    
    // Wait before next poll
    if (attempt < maxAttempts) {
      await new Promise(resolve => setTimeout(resolve, pollInterval));
    }
  }
  
  throw new Error('Polling timeout - order still processing');
}

// Usage
try {
  const order = await pollTopupUntilComplete('6901616fe9e88196b4eb64b2');
  
  if (order.status === 'FULFILLED') {
    console.log('✅ Card delivered:', order.card_code);
  } else if (order.status === 'QUEUED') {
    console.log('⏰ Order scheduled for later');
  } else if (order.status === 'REFUNDED') {
    console.log('❌ Order failed and refunded');
  }
} catch (error) {
  console.error('Polling failed:', error.message);
}

​
Adaptive Polling Strategy

Adjust polling frequency based on elapsed time: 
async function pollTopupAdaptive(topupId, maxDuration = 5 * 60 * 1000) {
  const startTime = Date.now();
  let pollInterval = 3000; // Start with 3 seconds
  
  while (Date.now() - startTime < maxDuration) {
    const order = await checkTopupStatus(topupId);
    
    // Check for final state
    const finalStates = ['FULFILLED', 'REFUNDED', 'QUEUED'];
    if (finalStates.includes(order.status)) {
      return order;
    }
    
    // Adaptive interval: increase as time passes
    const elapsed = Date.now() - startTime;
    if (elapsed > 60000) {
      pollInterval = 10000; // 10 seconds after 1 minute
    } else if (elapsed > 30000) {
      pollInterval = 5000; // 5 seconds after 30 seconds
    }
    
    await new Promise(resolve => setTimeout(resolve, pollInterval));
  }
  
  throw new Error('Order processing timeout');
}

// Usage
const order = await pollTopupAdaptive('6901616fe9e88196b4eb64b2');

​
Handling Order Results

async function handleTopupResult(topupId, order) {
  switch (order.status) {
    case 'FULFILLED':
      console.log(`✅ Order fulfilled`);
      console.log(`Card: ${order.card_code}`);
      console.log(`Transaction: ${order.num_trans}`);
      
      // Update database
      await db.internetOrders.updateOne(
        { topupId },
        { 
          $set: { 
            status: 'FULFILLED',
            cardCode: order.card_code,
            numTrans: order.num_trans,
            dateTraitement: order.date_traitement,
            fulfilledAt: new Date()
          } 
        }
      );
      
      // Deliver card to customer
      await deliverCard(order);
      break;
    
    case 'QUEUED':
      console.log(`⏰ Order scheduled for later delivery`);
      
      // Update database
      await db.internetOrders.updateOne(
        { topupId },
        { 
          $set: { 
            status: 'SCHEDULED',
            message: 'Card will be delivered within 48 hours',
            nextCheckAt: new Date(Date.now() + 24 * 60 * 60 * 1000)
          } 
        }
      );
      
      // Schedule recheck after 24 hours
      await scheduleRecheck(topupId, 24 * 60 * 60 * 1000);
      
      // Notify customer
      await notifyCustomer(order, 
        'Your order is scheduled and will be delivered within 48 hours.'
      );
      break;
    
    case 'REFUNDED':
      console.log(`❌ Order failed and refunded`);
      
      // Update database
      await db.internetOrders.updateOne(
        { topupId },
        { 
          $set: { 
            status: 'REFUNDED',
            refundedAt: new Date()
          } 
        }
      );
      
      // Notify customer of failure
      await notifyCustomer(order, 
        'Your order could not be completed. A full refund has been issued.'
      );
      break;
  }
}

​
Handling QUEUED Status

QUEUED orders are not failures! They’re scheduled for delivery within 12-48 hours.
async function scheduleRecheck(topupId, delayMs) {
  // Using a job queue (e.g., Bull)
  await recheckQueue.add(
    'recheck-topup',
    { topupId },
    {
      delay: delayMs,
      attempts: 3,
      backoff: {
        type: 'exponential',
        delay: 3600000, // 1 hour
      },
    }
  );
  
  console.log(`Scheduled recheck for ${topupId} in ${delayMs / 1000 / 60 / 60} hours`);
}

// Worker to process rechecks
recheckQueue.process('recheck-topup', async (job) => {
  const { topupId } = job.data;
  
  const order = await checkTopupStatus(topupId);
  
  if (order.status === 'QUEUED') {
    // Still queued, schedule another check
    await scheduleRecheck(topupId, 12 * 60 * 60 * 1000); // 12 hours
  } else {
    // Order completed
    await handleTopupResult(topupId, order);
  }
});

​
Best Practices

Poll Every 5-10 Seconds

Balance between responsiveness and API load

Handle QUEUED Properly

Don’t treat QUEUED as failure - schedule rechecks

Set Timeout Limits

Fail gracefully after 5 minutes of polling

Update Database

Store status changes and card details

​
Next Steps

Deliver Cards

Securely deliver card codes to customers

Send Top-Ups

Submit orders with validation

API Reference

Complete endpoint documentation

Overview

Back to integration overview

Validate Numbers

Verify phone numbers

Load Products

Fetch available cards