Read live limits and your rate from
GET /api/flexy/operators: do not hard-code them.
How an order works
Top-ups are asynchronous. You submit, we debit your wallet and answer202, the top-up is sent in the background, and the order ends as success or failed. A failed order is refunded to your wallet automatically.
Typical time is 5 to 20 seconds. Poll
GET /api/flexy/status/{id} every 3 to 5 seconds. Never retry a top-up that is still processing: you could deliver twice.
Idempotency
Send anidempotency_key (max 64 characters, unique per order in your system, for example your order ID) on every top-up. Re-sending the same key returns the original order with "idempotent": true and never charges twice. Use it for network retries and timeouts.
Send a top-up
1
Read operators and your rate
Response
2
Submit
Response (202)
amount is what the recipient receives. price is what leaves your wallet.3
Poll until final
Offers
Offers depend on the number. Fetch them right before ordering and do not cache them across numbers. You can only order an offer that/flexy/offers returned for that number in the last 15 minutes (the price comes from that list).
topup_type: "offer", the offer’s amount, and its offer_id, offer_name, offer_category and menu_number.
Offer ids are only unique inside a category (for example Mobilis has a
MIX offer 1 and a NET offer 1), and 0 is a valid id. Always send offer_category with offer_id, or send the key of the offer (CATEGORY:id) as offer_key. An offer_id that appears in several categories is refused without a category.Ooredoo unpaid balance
For Ooredooprepaid and offer top-ups, call POST /api/flexy/ooredoo-debt-check first (it stays valid for about 9 minutes). If has_debt is true you choose: pay_debt: true adds the debt to the price, pay_debt: false skips it. Skipping the check returns a validation error.
Bulk top-ups
Send up to 100 numbers in one call. The list is checked as a whole (your wallet must cover every valid line), then processed in the background, line by line. Each line is an ordinary Flexy order: its own status and its own automatic refund.202) holds the batch id. Poll GET /api/flexy/bulk/{id} until final is true: each line shows queued, processing, success or failed. Add "dry_run": true to check a list and see every price without charging anything. Items accept topup_type prepaid (default) or international (Mobilis only). Ooredoo unpaid balances are skipped in bulk. Re-sending the same idempotency_key returns the original batch.
History
GET /api/flexy/history lists your top-ups (per_page up to 100, page, status, target_number). Use it to reconcile with your own orders every day.
Errors
Large and bulk volumes. Each top-up is limited to 4,999 DA and each bulk list to 100 numbers. If you send many numbers or large amounts every day, contact us on WhatsApp +213 770 07 64 90 or open a support ticket: we set up wholesale rates and bulk handling for your account.