Status Tracking & Polling - OneClickDz Flexy API

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

HANDLING

Order is processing with the operator. Typical time: 3-45 seconds. Continue polling every 5-10 seconds.

FULFILLED

Success! Card delivered. card_code, num_trans, and date_traitement available. Deliver to customer immediately.

QUEUED

Scheduled for later. Order will be processed within 12-48 hours. Not a failure - schedule recheck after 24 hours and inform customer.

REFUNDED

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}`);
}

import requests
import os

def check_topup_status(topup_id):
    response = requests.get(
        f'https://api.oneclickdz.com/v3/internet/check-id/{topup_id}',
        headers={'X-Access-Token': os.getenv('API_KEY')}
    )
    
    response.raise_for_status()
    return response.json()['data']

# Usage
topup_id = '6901616fe9e88196b4eb64b2'
order = check_topup_status(topup_id)

print(f"Status: {order['status']}")
print(f"Type: {order['type']}")
print(f"Number: {order['number']}")

if 'card_code' in order:
    print(f"Card Code: {order['card_code']}")
    print(f"Transaction: {order['num_trans']}")

<?php

function checkTopupStatus($topupId) {
    $url = "https://api.oneclickdz.com/v3/internet/check-id/{$topupId}";
    
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'X-Access-Token: ' . getenv('API_KEY')
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode !== 200) {
        throw new Exception("Failed to check status: " . $httpCode);
    }
    
    $result = json_decode($response, true);
    return $result['data'];
}

// Usage
$topupId = '6901616fe9e88196b4eb64b2';
$order = checkTopupStatus($topupId);

echo "Status: {$order['status']}\n";
echo "Type: {$order['type']}\n";
echo "Number: {$order['number']}\n";

if (isset($order['card_code'])) {
    echo "Card Code: {$order['card_code']}\n";
    echo "Transaction: {$order['num_trans']}\n";
}
?>

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

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);
}

import time

def poll_topup_until_complete(topup_id, max_attempts=60):
    poll_interval = 5  # 5 seconds
    
    for attempt in range(1, max_attempts + 1):
        print(f"Polling attempt {attempt}/{max_attempts}")
        
        order = check_topup_status(topup_id)
        
        # Check if order reached final state
        final_states = ['FULFILLED', 'REFUNDED', 'QUEUED']
        if order['status'] in final_states:
            print(f"Order completed with status: {order['status']}")
            return order
        
        # Wait before next poll
        if attempt < max_attempts:
            time.sleep(poll_interval)
    
    raise Exception('Polling timeout - order still processing')

# Usage
try:
    order = poll_topup_until_complete('6901616fe9e88196b4eb64b2')
    
    if order['status'] == 'FULFILLED':
        print(f"✅ Card delivered: {order['card_code']}")
    elif order['status'] == 'QUEUED':
        print('⏰ Order scheduled for later')
    elif order['status'] == 'REFUNDED':
        print('❌ Order failed and refunded')
except Exception as e:
    print(f"Polling failed: {e}")

<?php

function pollTopupUntilComplete($topupId, $maxAttempts = 60) {
    $pollInterval = 5; // 5 seconds
    
    for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
        error_log("Polling attempt {$attempt}/{$maxAttempts}");
        
        $order = checkTopupStatus($topupId);
        
        // Check if order reached final state
        $finalStates = ['FULFILLED', 'REFUNDED', 'QUEUED'];
        if (in_array($order['status'], $finalStates)) {
            error_log("Order completed with status: {$order['status']}");
            return $order;
        }
        
        // Wait before next poll
        if ($attempt < $maxAttempts) {
            sleep($pollInterval);
        }
    }
    
    throw new Exception('Polling timeout - order still processing');
}

// Usage
try {
    $order = pollTopupUntilComplete('6901616fe9e88196b4eb64b2');
    
    if ($order['status'] === 'FULFILLED') {
        echo "✅ Card delivered: {$order['card_code']}\n";
    } elseif ($order['status'] === 'QUEUED') {
        echo "⏰ Order scheduled for later\n";
    } elseif ($order['status'] === 'REFUNDED') {
        echo "❌ Order failed and refunded\n";
    }
} catch (Exception $e) {
    echo "Polling failed: " . $e->getMessage() . "\n";
}
?>

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;
  }
}

from datetime import datetime, timedelta

async def handle_topup_result(topup_id, order):
    if order['status'] == 'FULFILLED':
        print('✅ Order fulfilled')
        print(f"Card: {order['card_code']}")
        print(f"Transaction: {order['num_trans']}")
        
        # Update database
        db.internet_orders.update_one(
            {'topupId': topup_id},
            {
                '$set': {
                    'status': 'FULFILLED',
                    'cardCode': order['card_code'],
                    'numTrans': order['num_trans'],
                    'dateTraitement': order['date_traitement'],
                    'fulfilledAt': datetime.now()
                }
            }
        )
        
        # Deliver card to customer
        await deliver_card(order)
    
    elif order['status'] == 'QUEUED':
        print('⏰ Order scheduled for later delivery')
        
        # Update database
        db.internet_orders.update_one(
            {'topupId': topup_id},
            {
                '$set': {
                    'status': 'SCHEDULED',
                    'message': 'Card will be delivered within 48 hours',
                    'nextCheckAt': datetime.now() + timedelta(hours=24)
                }
            }
        )
        
        # Schedule recheck after 24 hours
        await schedule_recheck(topup_id, 24 * 60 * 60 * 1000)
        
        # Notify customer
        await notify_customer(order, 
            'Your order is scheduled and will be delivered within 48 hours.'
        )
    
    elif order['status'] == 'REFUNDED':
        print('❌ Order failed and refunded')
        
        # Update database
        db.internet_orders.update_one(
            {'topupId': topup_id},
            {
                '$set': {
                    'status': 'REFUNDED',
                    'refundedAt': datetime.now()
                }
            }
        )
        
        # Notify customer of failure
        await notify_customer(order, 
            'Your order could not be completed. A full refund has been issued.'
        )

<?php

function handleTopupResult($topupId, $order) {
    switch ($order['status']) {
        case 'FULFILLED':
            error_log('✅ Order fulfilled');
            error_log("Card: {$order['card_code']}");
            error_log("Transaction: {$order['num_trans']}");
            
            // Update database
            updateOrderStatus($topupId, 'FULFILLED', [
                'cardCode' => $order['card_code'],
                'numTrans' => $order['num_trans'],
                'dateTraitement' => $order['date_traitement'],
                'fulfilledAt' => date('Y-m-d H:i:s')
            ]);
            
            // Deliver card to customer
            deliverCard($order);
            break;
        
        case 'QUEUED':
            error_log('⏰ Order scheduled for later delivery');
            
            // Update database
            updateOrderStatus($topupId, 'SCHEDULED', [
                'message' => 'Card will be delivered within 48 hours',
                'nextCheckAt' => date('Y-m-d H:i:s', time() + 24 * 60 * 60)
            ]);
            
            // Schedule recheck after 24 hours
            scheduleRecheck($topupId, 24 * 60 * 60);
            
            // Notify customer
            notifyCustomer($order, 
                'Your order is scheduled and will be delivered within 48 hours.'
            );
            break;
        
        case 'REFUNDED':
            error_log('❌ Order failed and refunded');
            
            // Update database
            updateOrderStatus($topupId, 'REFUNDED', [
                'refundedAt' => date('Y-m-d H:i:s')
            ]);
            
            // Notify customer of failure
            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);
  }
});

Testing Every Status in Sandbox

With a sandbox key, the number you send decides how the order behaves — so you can test each branch of your polling code without waiting on a real order. Statuses advance on their own as time passes; poll exactly as you would in production.

Number	Timeline	Use it to test
`030000001`	HANDLING → REFUNDED after 3s	Your failure/refund path
`030000002`	HANDLING → QUEUED after 3s → FULFILLED 15s later	Your QUEUED recheck path
any other valid number	HANDLING → FULFILLED after 3s	The happy path and card delivery
`030000000`	rejected at `/send` with `ERR_PHONE`	Your validation error path

// Same polling loop as production — only the number changes
const { data } = await sendTopup({ type: 'ADSL', number: '030000002', value: 1000 });

await pollTopupStatus(data.topupId);
// t=0s   HANDLING
// t=4s   QUEUED      → your recheck scheduler fires here
// t=19s  FULFILLED   card_code: "TESTCARD", num_trans: "TESTTRANS"

A fulfilled sandbox order returns card_code: "TESTCARD" and num_trans: "TESTTRANS" instead of real values. Everything else — response shape, status names, polling behaviour — is identical to production.

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

​Overview

​API Reference

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

​Order Status Values

​Basic Status Check

​Response Examples

​Handling (Processing)

​Fulfilled (Success)

​Queued (Scheduled)

​Basic Polling Implementation

​Adaptive Polling Strategy

​Handling Order Results

​Handling QUEUED Status

​Testing Every Status in Sandbox

​Best Practices

Poll Every 5-10 Seconds

Handle QUEUED Properly

Set Timeout Limits

Update Database

​Next Steps

Deliver Cards

Send Top-Ups

API Reference

Overview

Validate Numbers

Load Products

Overview

API Reference

Order Status Values

Basic Status Check

Response Examples

Handling (Processing)

Fulfilled (Success)

Queued (Scheduled)

Basic Polling Implementation

Adaptive Polling Strategy

Handling Order Results

Handling QUEUED Status

Testing Every Status in Sandbox

Best Practices

Next Steps