Introduction
Integrate mobile top-up functionality for Algerian operators (Mobilis, Djezzy, Ooredoo, Pixx) in 4 simple steps. This overview explains the integration workflow—detailed implementation with code examples in Node.js, Python, PHP, and cURL are in the step-by-step guides below.How It Works
4-Step Integration Process
1
Load Plans
Get available top-up plans with pricing and cache them locally.→ See Step 1: Loading Plans
2
Validate Input
Verify phone numbers (10 digits, correct operator prefix) and amounts before sending.→ See Step 2: Validation
3
Send Top-Up
Submit the top-up request with a unique reference for tracking.→ See Step 3: Sending Top-Ups
4
Poll Status
Check the order status every 5-10 seconds until it’s complete (FULFILLED, REFUNDED, or UNKNOWN_ERROR).→ See Step 4: Status Polling
What You Need to Know
Plan Types
The API supports 3 types of plans:- Dynamic Plans: Flexible amounts (e.g., 50-5000 DA for Djezzy Prepaid)
- Fixed Plans: Specific amounts (e.g., Pixx 500 DA)
- GetMenu Plans: Fetch personalized offers for a phone number
Order Status
Orders progress through these states:PENDING/HANDLING→ Keep pollingFULFILLED→ Success! ✅REFUNDED→ Failed, refund issued ❌UNKNOWN_ERROR→ Wait 24h before refunding ⚠️
Phone Format
Phone numbers must be 10 digits:0[567][0-9]{8}
- Mobilis:
06... - Djezzy:
07... - Ooredoo:
05...
Pricing
The API returns wholesale prices. Apply your markup before showing to customers. Example:cost: 0.98 for 1000 DA → You pay 980 DA → Sell at 1029 DA (5% markup) → Profit: 49 DA
→ Pricing strategies in Step 1
Key Points
Always Use Unique References
Always Use Unique References
Generate unique
ref for each request to prevent duplicates and enable tracking.→ Implementation in Step 3Cache Plans Locally
Cache Plans Locally
Plans rarely change. Cache them to reduce API calls and improve speed.→ Caching strategy in Step 1
Handle UNKNOWN_ERROR Carefully
Handle UNKNOWN_ERROR Carefully
Never refund immediately! Wait up to 24 hours for status to resolve.→ Error handling in Step 4
Show Arabic Error Messages
Show Arabic Error Messages
Display the
refund_message field (in Arabic) to customers—it explains what went wrong.→ Message handling in Step 4API Reference
For complete endpoint specifications:List Mobile Plans
GET /v3/mobile/plans
Send Top-Up
POST /v3/mobile/send
Check by Reference
GET /v3/mobile/check-ref/:ref
Check by ID
GET /v3/mobile/check-id/:id
Testing
Use sandbox mode to test without real money. Test with these special numbers:- Normal numbers → Success flow
0600000001→ Refund scenario0600000002→ Suggested offers0600000003→ Unknown error
Start Integrating
Begin with Step 1: Loading Plans
Get started by loading and caching mobile plans with code examples