Failed. Order completely failed. fulfilled_quantity === 0. Full refund issued automatically.
Sandbox Testing
Use sandbox mode to test without spending real balance:
Test Failed Order
Use TEST_REFUND as type ID → Simulates failed order (REFUNDED status)
Test Partial Success
Use TEST_PARTIAL as type ID → Simulates 50% fulfillment (PARTIALLY_FILLED
status)
Sandbox Example
// Test different scenarios without real chargesconst testScenarios = [ { productId: "507f1f77bcf86cd799439011", typeId: "TEST_REFUND", // Will fail and refund quantity: 2, }, { productId: "507f1f77bcf86cd799439011", typeId: "TEST_PARTIAL", // Will deliver 50% of cards quantity: 4, },];// Place test orderconst order = await placeOrder( testScenarios[0].productId, testScenarios[0].typeId, testScenarios[0].quantity);// Poll for resultsconst result = await pollOrderUntilComplete(order.orderId);console.log("Test result:", result.status);
Basic Status Check
async function checkOrderStatus(orderId) { const response = await fetch( `https://api.oneclickdz.com/v3/gift-cards/checkOrder/${orderId}`, { headers: { "X-Access-Token": process.env.API_KEY, }, } ); if (!response.ok) { throw new Error(`Failed to check order: ${response.status}`); } const result = await response.json(); return result.data;}// Usageconst orderId = "6901616fe9e88196b4eb64b3";const order = await checkOrderStatus(orderId);console.log(`Status: ${order.status}`);console.log(`Quantity: ${order.quantity}`);if (order.cards) { console.log(`Cards delivered: ${order.cards.length}`);}
async function pollOrderUntilComplete(orderId, maxAttempts = 60) { for (let attempt = 1; attempt <= maxAttempts; attempt++) { console.log(`Checking order status (${attempt}/${maxAttempts})...`); const order = await checkOrderStatus(orderId); // Order is complete if (["FULFILLED", "PARTIALLY_FILLED", "REFUNDED"].includes(order.status)) { console.log(`Order completed: ${order.status}`); return order; } // Wait 5 seconds before next check if (attempt < maxAttempts) { await new Promise((resolve) => setTimeout(resolve, 5000)); } } throw new Error("Order still processing after timeout");}// Usagetry { const order = await pollOrderUntilComplete("6901616fe9e88196b4eb64b3"); if (order.status === "FULFILLED") { console.log("Success! Cards:", order.cards); } else if (order.status === "PARTIALLY_FILLED") { console.log( `Partial delivery: ${order.fulfilled_quantity}/${order.quantity}` ); } else { console.log("Order failed and refunded"); }} catch (error) { console.error("Error:", error.message);}
import timedef poll_order_until_complete(order_id, max_attempts=60): for attempt in range(1, max_attempts + 1): print(f"Checking order status ({attempt}/{max_attempts})...") order = check_order_status(order_id) # Order is complete if order['status'] in ['FULFILLED', 'PARTIALLY_FILLED', 'REFUNDED']: print(f"Order completed: {order['status']}") return order # Wait 5 seconds before next check if attempt < max_attempts: time.sleep(5) raise Exception('Order still processing after timeout')# Usagetry: order = poll_order_until_complete('6901616fe9e88196b4eb64b3') if order['status'] == 'FULFILLED': print(f"Success! Cards: {len(order['cards'])}") elif order['status'] == 'PARTIALLY_FILLED': print(f"Partial delivery: {order['fulfilled_quantity']}/{order['quantity']}") else: print('Order failed and refunded')except Exception as e: print(f"Error: {e}")
<?phpfunction pollOrderUntilComplete($orderId, $apiKey, $maxAttempts = 60) { for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) { echo "Checking order status ({$attempt}/{$maxAttempts})...\n"; $order = checkOrderStatus($orderId, $apiKey); // Order is complete $finalStates = ['FULFILLED', 'PARTIALLY_FILLED', 'REFUNDED']; if (in_array($order['status'], $finalStates)) { echo "Order completed: {$order['status']}\n"; return $order; } // Wait 5 seconds before next check if ($attempt < $maxAttempts) { sleep(5); } } throw new Exception('Order still processing after timeout');}// Usagetry { $order = pollOrderUntilComplete('6901616fe9e88196b4eb64b3', getenv('API_KEY')); if ($order['status'] === 'FULFILLED') { echo "Success! Cards: " . count($order['cards']) . "\n"; } elseif ($order['status'] === 'PARTIALLY_FILLED') { echo "Partial delivery: {$order['fulfilled_quantity']}/{$order['quantity']}\n"; } else { echo "Order failed and refunded\n"; }} catch (Exception $e) { echo "Error: " . $e->getMessage() . "\n";}?>
Handling Different Results
function handleOrderResult(order) { switch (order.status) { case "FULFILLED": console.log(`✅ Success: ${order.fulfilled_quantity} cards delivered`); console.log(`Cost: ${order.fulfilled_amount} DA`); // Process each card order.cards.forEach((card, index) => { console.log(`Card ${index + 1}: ${card.value}`); // Encrypt and deliver to customer }); break; case "PARTIALLY_FILLED": console.log( `⚠️ Partial: ${order.fulfilled_quantity}/${order.quantity} cards` ); console.log(`Charged: ${order.fulfilled_amount} DA`); const refund = (order.quantity - order.fulfilled_quantity) * order.price_per_card; console.log(`Refunded: ${refund} DA`); // Deliver available cards order.cards.forEach((card) => { console.log(`Delivered: ${card.value}`); }); break; case "REFUNDED": console.log("❌ Order failed - full refund issued"); break; }}
def handle_order_result(order): if order['status'] == 'FULFILLED': print(f"✅ Success: {order['fulfilled_quantity']} cards delivered") print(f"Cost: {order['fulfilled_amount']} DA") # Process each card for i, card in enumerate(order['cards']): print(f"Card {i + 1}: {card['value']}") # Encrypt and deliver to customer elif order['status'] == 'PARTIALLY_FILLED': print(f"⚠️ Partial: {order['fulfilled_quantity']}/{order['quantity']} cards") print(f"Charged: {order['fulfilled_amount']} DA") refund = (order['quantity'] - order['fulfilled_quantity']) * order['price_per_card'] print(f"Refunded: {refund} DA") # Deliver available cards for card in order['cards']: print(f"Delivered: {card['value']}") elif order['status'] == 'REFUNDED': print('❌ Order failed - full refund issued')
<?phpfunction handleOrderResult($order) { switch ($order['status']) { case 'FULFILLED': echo "✅ Success: {$order['fulfilled_quantity']} cards delivered\n"; echo "Cost: {$order['fulfilled_amount']} DA\n"; // Process each card foreach ($order['cards'] as $index => $card) { echo "Card " . ($index + 1) . ": {$card['value']}\n"; // Encrypt and deliver to customer } break; case 'PARTIALLY_FILLED': echo "⚠️ Partial: {$order['fulfilled_quantity']}/{$order['quantity']} cards\n"; echo "Charged: {$order['fulfilled_amount']} DA\n"; $refund = ($order['quantity'] - $order['fulfilled_quantity']) * $order['price_per_card']; echo "Refunded: {$refund} DA\n"; // Deliver available cards foreach ($order['cards'] as $card) { echo "Delivered: {$card['value']}\n"; } break; case 'REFUNDED': echo "❌ Order failed - full refund issued\n"; break; }}?>
Complete Polling Example
async function processOrder(productId, typeId, quantity) { try { // 1. Place order console.log("Placing order..."); const order = await placeOrder(productId, typeId, quantity); console.log(`Order placed: ${order.orderId}`); // 2. Poll for completion console.log("Waiting for fulfillment..."); const result = await pollOrderUntilComplete(order.orderId); // 3. Handle result handleOrderResult(result); return result; } catch (error) { console.error("Order processing failed:", error.message); throw error; }}// Usageawait processOrder("507f1f77bcf86cd799439011", "type_001", 2);
Best Practices
Poll Every 5 Seconds
Balance between responsiveness and API load
Set Timeout
Stop polling after 5 minutes (60 attempts)
Handle All States
Process FULFILLED, PARTIALLY_FILLED, and REFUNDED
Test First
Use sandbox mode with TEST_REFUND and TEST_PARTIAL