Skip to main content

Overview

Best practices for polling API endpoints to track order status efficiently.

Basic Polling Pattern

Service-Specific Polling

Mobile Top-Ups (5 minutes max)

Internet Top-Ups (5 minutes max)

Gift Cards (10 minutes max)

Bill Payment (5 minutes max)

Bill Payment runs on https://api.oneclickdz.com and has two phases: a discovery that settles quickly, and a payment that takes longer. Poll the transaction by its identifier.
UNKNOWN is not a final state and not a failure — it means the outcome has not been confirmed yet, and it resolves on its own to SUCCESS or REFUNDED. The review is manual and can take up to 24 hours, so polling faster changes nothing: slow the poll to about 30 seconds while it lasts, hand it to a background job if your foreground timeout expires, and never refund your customer or resend the payment in the meantime.
Full Bill Payment polling guide →

Best Practices

Set Timeouts

Always set maximum polling duration

Handle Errors

Catch and handle polling timeouts

Log Progress

Track polling attempts for debugging

Final States

Define clear terminal states

Mobile Top-Up Guide

Complete mobile integration workflow

Error Handling

Handle errors properly

Webhooks

Real-time status notifications

Best Practices

Security best practices