> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneclickdz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mobile Top-Up Integration Overview

> Learn how to integrate mobile top-up for Algerian operators

## 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

```mermaid theme={null}
sequenceDiagram
    participant User
    participant YourApp
    participant API as OneClickDz API

    YourApp->>API: 1. Load available plans
    API-->>YourApp: Plans with pricing
    
    User->>YourApp: Select plan & enter phone
    YourApp->>YourApp: 2. Validate input
    
    YourApp->>API: 3. Send top-up request
    API-->>YourApp: Order ID
    
    loop Until Complete
        YourApp->>API: 4. Check status
        API-->>YourApp: Status update
    end
    
    YourApp->>User: Notify success/failure
```

## 4-Step Integration Process

<Steps>
  <Step title="Load Plans">
    Get available top-up plans with pricing and cache them locally.

    → [See Step 1: Loading Plans](/en/mobile-topup-guides/1-loading-plans)
  </Step>

  <Step title="Validate Input">
    Verify phone numbers (10 digits, correct operator prefix) and amounts before sending.

    → [See Step 2: Validation](/en/mobile-topup-guides/2-validation)
  </Step>

  <Step title="Send Top-Up">
    Submit the top-up request with a unique reference for tracking.

    → [See Step 3: Sending Top-Ups](/en/mobile-topup-guides/3-sending-topups)
  </Step>

  <Step title="Poll Status">
    Check the order status every 5-10 seconds until it's complete (FULFILLED, REFUNDED, or UNKNOWN\_ERROR).

    → [See Step 4: Status Polling](/en/mobile-topup-guides/4-status-polling)
  </Step>
</Steps>

## 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

→ [Learn more in Step 1](/en/mobile-topup-guides/1-loading-plans)

### Order Status

Orders progress through these states:

* `PENDING` / `HANDLING` → Keep polling
* `FULFILLED` → Success! ✅
* `REFUNDED` → Failed, refund issued ❌
* `UNKNOWN_ERROR` → **Wait 24h before refunding** ⚠️

→ [Detailed status handling in Step 4](/en/mobile-topup-guides/4-status-polling)

### Phone Format

Phone numbers must be **10 digits**: `0[567][0-9]{8}`

* Mobilis: `06...`
* Djezzy: `07...`
* Ooredoo: `05...`

→ [Validation code in Step 2](/en/mobile-topup-guides/2-validation)

### 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](/en/mobile-topup-guides/1-loading-plans)

## Key Points

<AccordionGroup>
  <Accordion title="Always Use Unique References" icon="fingerprint">
    Generate unique `ref` for each request to prevent duplicates and enable tracking.

    → [Implementation in Step 3](/en/mobile-topup-guides/3-sending-topups)
  </Accordion>

  <Accordion title="Cache Plans Locally" icon="database">
    Plans rarely change. Cache them to reduce API calls and improve speed.

    → [Caching strategy in Step 1](/en/mobile-topup-guides/1-loading-plans)
  </Accordion>

  <Accordion title="Handle UNKNOWN_ERROR Carefully" icon="triangle-exclamation">
    **Never refund immediately!** Wait up to 24 hours for status to resolve.

    → [Error handling in Step 4](/en/mobile-topup-guides/4-status-polling)
  </Accordion>

  <Accordion title="Show Arabic Error Messages" icon="language">
    Display the `refund_message` field (in Arabic) to customers-it explains what went wrong.

    → [Message handling in Step 4](/en/mobile-topup-guides/4-status-polling)
  </Accordion>
</AccordionGroup>

## API Reference

For complete endpoint specifications:

<CardGroup cols={2}>
  <Card title="List Mobile Plans" icon="list" href="/en/api-reference/mobile/list-plans">
    GET /v3/mobile/plans
  </Card>

  <Card title="Send Top-Up" icon="paper-plane" href="/en/api-reference/mobile/send-topup">
    POST /v3/mobile/send
  </Card>

  <Card title="Check by Reference" icon="tag" href="/en/api-reference/mobile/check-by-ref">
    GET /v3/mobile/check-ref/:ref
  </Card>

  <Card title="Check by ID" icon="id-card" href="/en/api-reference/mobile/check-by-id">
    GET /v3/mobile/check-id/:id
  </Card>
</CardGroup>

## Testing

Use **sandbox mode** to test without real money. Test with these special numbers:

* Normal numbers → Success flow
* `0600000001` → Refund scenario
* `0600000002` → Suggested offers
* `0600000003` → Unknown error

Enable sandbox in [dashboard settings](https://app.oneclickdz.com/#/settings).

## Start Integrating

<Card title="Begin with Step 1: Loading Plans" icon="play" href="/en/mobile-topup-guides/1-loading-plans" color="#0D9373">
  Get started by loading and caching mobile plans with code examples
</Card>

## Additional Resources

<CardGroup cols={2}>
  <Card title="Quick Start Guide" icon="rocket" href="/en/quickstart">
    Get up and running in 5 minutes
  </Card>

  <Card title="Authentication" icon="key" href="/en/authentication">
    Learn how to authenticate requests
  </Card>

  <Card title="Security Best Practices" icon="shield" href="/en/security-best-practices">
    Secure your integration
  </Card>

  <Card title="Polling Strategies" icon="chart-line" href="/en/polling-strategies">
    Optimize status checking
  </Card>

  <Card title="Webhooks Setup" icon="webhook" href="/en/webhooks">
    Real-time status notifications
  </Card>

  <Card title="Contact Support" icon="headset" href="/en/contact">
    Get help from our team
  </Card>
</CardGroup>