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

# Quickstart

> Send your first top-up in under 5 minutes

## Get Your API Key

<Steps>
  <Step title="Sign Up">
    Create a free account at [enterprise.oneclickdz.com](https://app.oneclickdz.com/)
  </Step>

  <Step title="Generate API Keys">
    Go to [Settings](https://enterprise.oneclickdz.com/api-keys) → API Section → Generate API Key

    You'll receive two keys:

    * **Sandbox**: Test without real transactions
    * **Production**: Live transactions
  </Step>

  <Step title="Secure Your Keys">
    Store keys securely in environment variables. Never expose them in client-side code or version control.
  </Step>
</Steps>

<Warning>
  Always start with **Sandbox** mode to test your integration safely.
</Warning>

## Verify Your API Key

Test your API key with the validate endpoint:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.oneclickdz.com/v3/validate \
    -H "X-Access-Token: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.oneclickdz.com/v3/validate", {
    headers: { "X-Access-Token": "YOUR_API_KEY" },
  });
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.oneclickdz.com/v3/validate",
      headers={"X-Access-Token": "YOUR_API_KEY"}
  )
  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.oneclickdz.com/v3/validate");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Access-Token: YOUR_API_KEY"]);
  $response = curl_exec($ch);
  echo $response;
  ?>
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "username": "+213665983439",
    "apiKey": {
      "type": "SANDBOX",
      "scope": "READ-WRITE",
      "isEnabled": true
    }
  }
}
```

<Check>If you see `"success": true`, your API key is working correctly!</Check>

## Step 1: Send a Mobile Top-Up

Send a 500 DZD top-up to a Djezzy number:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.oneclickdz.com/v3/mobile/send \
    -X POST \
    -H "Content-Type: application/json" \
    -H "X-Access-Token: YOUR_API_KEY" \
    -d '{
      "plan_code": "PREPAID_DJEZZY",
      "MSSIDN": "0778037340",
      "amount": 500,
      "ref": "order-001"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.oneclickdz.com/v3/mobile/send", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Access-Token": "YOUR_API_KEY",
    },
    body: JSON.stringify({
      plan_code: "PREPAID_DJEZZY",
      MSSIDN: "0778037340",
      amount: 500,
      ref: "order-001",
    }),
  });
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.oneclickdz.com/v3/mobile/send',
      headers={
          'Content-Type': 'application/json',
          'X-Access-Token': 'YOUR_API_KEY'
      },
      json={
          'plan_code': 'PREPAID_DJEZZY',
          'MSSIDN': '0778037340',
          'amount': 500,
          'ref': 'order-001'
      }
  )
  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.oneclickdz.com/v3/mobile/send");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Content-Type: application/json",
      "X-Access-Token: YOUR_API_KEY"
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
      'plan_code' => 'PREPAID_DJEZZY',
      'MSSIDN' => '0778037340',
      'amount' => 500,
      'ref' => 'order-001'
  ]));
  $response = curl_exec($ch);
  echo $response;
  ?>
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "topupId": "6901616fe9e88196b4eb64b0",
    "topupRef": "order-001"
  }
}
```

## Step 2: Check Top-Up Status

Check the status of your top-up using the reference:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.oneclickdz.com/v3/mobile/check-ref/order-001 \
    -H "X-Access-Token: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.oneclickdz.com/v3/mobile/check-ref/order-001",
    { headers: { "X-Access-Token": "YOUR_API_KEY" } }
  );
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.oneclickdz.com/v3/mobile/check-ref/order-001',
      headers={'X-Access-Token': 'YOUR_API_KEY'}
  )
  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.oneclickdz.com/v3/mobile/check-ref/order-001");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Access-Token: YOUR_API_KEY"]);
  $response = curl_exec($ch);
  echo $response;
  ?>
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "status": "FULFILLED",
    "MSSIDN": "0778037340",
    "topup_amount": 500
  }
}
```

<Check>Status flow: `PENDING` (5s) → `HANDLING` (15s) → `FULFILLED` ✅</Check>

## Step 3: Try Internet Top-Up

Recharge an ADSL line with a 1000 DZD card:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.oneclickdz.com/v3/internet/send \
    -X POST \
    -H "Content-Type: application/json" \
    -H "X-Access-Token: YOUR_API_KEY" \
    -d '{
      "type": "ADSL",
      "number": "036362608",
      "value": 1000,
      "ref": "internet-001"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.oneclickdz.com/v3/internet/send", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Access-Token": "YOUR_API_KEY",
    },
    body: JSON.stringify({
      type: "ADSL",
      number: "036362608",
      value: 1000,
      ref: "internet-001",
    }),
  });
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.oneclickdz.com/v3/internet/send',
      headers={
          'Content-Type': 'application/json',
          'X-Access-Token': 'YOUR_API_KEY'
      },
      json={
          'type': 'ADSL',
          'number': '036362608',
          'value': 1000,
          'ref': 'internet-001'
      }
  )
  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.oneclickdz.com/v3/internet/send");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Content-Type: application/json",
      "X-Access-Token: YOUR_API_KEY"
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
      'type' => 'ADSL',
      'number' => '036362608',
      'value' => 1000,
      'ref' => 'internet-001'
  ]));
  $response = curl_exec($ch);
  echo $response;
  ?>
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "topupId": "6901616fe9e88196b4eb64b1",
    "topupRef": "internet-001"
  }
}
```

Check the internet top-up status:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.oneclickdz.com/v3/internet/check-ref/internet-001 \
    -H "X-Access-Token: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.oneclickdz.com/v3/internet/check-ref/internet-001",
    { headers: { "X-Access-Token": "YOUR_API_KEY" } }
  );
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.oneclickdz.com/v3/internet/check-ref/internet-001',
      headers={'X-Access-Token': 'YOUR_API_KEY'}
  )
  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.oneclickdz.com/v3/internet/check-ref/internet-001");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Access-Token: YOUR_API_KEY"]);
  $response = curl_exec($ch);
  echo $response;
  ?>
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "status": "FULFILLED",
    "card_code": "123456789012",
    "num_trans": "AT-2025-001"
  }
}
```

## Step 4: Explore Gift Cards

Get the product catalog to see available gift cards:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.oneclickdz.com/v3/gift-cards/catalog \
    -H "X-Access-Token: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.oneclickdz.com/v3/gift-cards/catalog",
    {
      headers: { "X-Access-Token": "YOUR_API_KEY" },
    }
  );
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.oneclickdz.com/v3/gift-cards/catalog',
      headers={'X-Access-Token': 'YOUR_API_KEY'}
  )
  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.oneclickdz.com/v3/gift-cards/catalog");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Access-Token: YOUR_API_KEY"]);
  $response = curl_exec($ch);
  echo $response;
  ?>
  ```
</CodeGroup>

Place a gift card order:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.oneclickdz.com/v3/gift-cards/placeOrder \
    -X POST \
    -H "Content-Type: application/json" \
    -H "X-Access-Token: YOUR_API_KEY" \
    -d '{
      "productId": "PRODUCT_ID",
      "typeId": "TYPE_ID",
      "quantity": 1
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.oneclickdz.com/v3/gift-cards/placeOrder",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Access-Token": "YOUR_API_KEY",
      },
      body: JSON.stringify({
        productId: "PRODUCT_ID",
        typeId: "TYPE_ID",
        quantity: 1,
      }),
    }
  );
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.oneclickdz.com/v3/gift-cards/placeOrder',
      headers={
          'Content-Type': 'application/json',
          'X-Access-Token': 'YOUR_API_KEY'
      },
      json={
          'productId': 'PRODUCT_ID',
          'typeId': 'TYPE_ID',
          'quantity': 1
      }
  )
  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.oneclickdz.com/v3/gift-cards/placeOrder");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Content-Type: application/json",
      "X-Access-Token: YOUR_API_KEY"
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
      'productId' => 'PRODUCT_ID',
      'typeId' => 'TYPE_ID',
      'quantity' => 1
  ]));
  $response = curl_exec($ch);
  echo $response;
  ?>
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "orderId": "6901616fe9e88196b4eb64c0"
  }
}
```

Retrieve gift card codes by checking order status:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.oneclickdz.com/v3/gift-cards/checkOrder/6901616fe9e88196b4eb64c0 \
    -H "X-Access-Token: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  // Poll order status until fulfilled
  async function getGiftCardCodes(orderId) {
    let status = 'HANDLING';
    
    while (status === 'HANDLING') {
      const response = await fetch(
        `https://api.oneclickdz.com/v3/gift-cards/checkOrder/${orderId}`,
        { headers: { "X-Access-Token": "YOUR_API_KEY" } }
      );
      const { data } = await response.json();
      status = data.status;
      
      if (status === 'FULFILLED') {
        return data.cards; // Array of {value, serial}
      }
      
      await new Promise(r => setTimeout(r, 5000)); // Wait 5 seconds
    }
  }

  const cards = await getGiftCardCodes('6901616fe9e88196b4eb64c0');
  console.log('Card codes:', cards);
  ```

  ```python Python theme={null}
  import time
  import requests

  def get_gift_card_codes(order_id):
      status = 'HANDLING'
      
      while status == 'HANDLING':
          response = requests.get(
              f'https://api.oneclickdz.com/v3/gift-cards/checkOrder/{order_id}',
              headers={'X-Access-Token': 'YOUR_API_KEY'}
          )
          data = response.json()['data']
          status = data['status']
          
          if status == 'FULFILLED':
              return data['cards']  # List of {'value': ..., 'serial': ...}
          
          time.sleep(5)  # Wait 5 seconds

  cards = get_gift_card_codes('6901616fe9e88196b4eb64c0')
  print('Card codes:', cards)
  ```

  ```php PHP theme={null}
  <?php
  function getGiftCardCodes($orderId, $apiKey) {
      $status = 'HANDLING';
      
      while ($status === 'HANDLING') {
          $ch = curl_init("https://api.oneclickdz.com/v3/gift-cards/checkOrder/{$orderId}");
          curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
          curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Access-Token: {$apiKey}"]);
          $response = json_decode(curl_exec($ch), true);
          $status = $response['data']['status'];
          
          if ($status === 'FULFILLED') {
              return $response['data']['cards'];
          }
          
          sleep(5); // Wait 5 seconds
      }
  }

  $cards = getGiftCardCodes('6901616fe9e88196b4eb64c0', 'YOUR_API_KEY');
  print_r($cards);
  ?>
  ```
</CodeGroup>

**Response when fulfilled:**

```json theme={null}
{
  "success": true,
  "data": {
    "status": "FULFILLED",
    "cards": [
      {
        "value": "XXXX-XXXX-XXXX-XXXX",
        "serial": "123456789"
      }
    ]
  }
}
```

<Check>Card codes are retrieved from the `cards` array when status is `FULFILLED`</Check>

## Sandbox Testing

In sandbox mode, test these special scenarios with mobile top-ups:

| Phone Number                           | Behavior                                  | Purpose                       |
| -------------------------------------- | ----------------------------------------- | ----------------------------- |
| Any normal number (e.g., `0778037340`) | Success: PENDING → HANDLING → FULFILLED   | Test successful transactions  |
| `0600000001`                           | REFUNDED with error message               | Test refund handling          |
| `0600000002`                           | REFUNDED with suggested alternative plans | Test plan mismatch            |
| `0600000003`                           | UNKNOWN\_ERROR status                     | Test uncertain state handling |

<Tip>
  Each workflow guide includes comprehensive sandbox testing instructions and examples.
</Tip>

## Understanding Response Format

All API responses follow this structure:

```json theme={null}
{
  "success": true,        // Operation status
  "data": { ... },        // Response data
  "meta": {               // Metadata
    "timestamp": "...",
    "pagination": { ... } // If applicable
  },
  "requestId": "..."      // Unique request identifier
}
```

[Learn about Response Format →](/en/api-reference/response-format)

## Next Steps

<CardGroup cols={2}>
  <Card title="Mobile Top-Up Guide" icon="mobile" href="/en/mobile-topup-guides/overview">
    Complete integration workflow
  </Card>

  <Card title="Internet Top-Up Guide" icon="wifi" href="/en/internet-topup-guides/overview">
    ADSL and 4G with sandbox testing
  </Card>

  <Card title="Gift Card Guide" icon="gift" href="/en/gift-card-guides/overview">
    Digital product delivery
  </Card>

  <Card title="Error Handling" icon="shield" href="/en/api-reference/error-handling">
    Handle errors properly
  </Card>

  <Card title="Authentication" icon="key" href="/en/authentication">
    Secure API access patterns
  </Card>

  <Card title="Best Practices" icon="lightbulb" href="/en/security-best-practices">
    Production-ready security
  </Card>
</CardGroup>

<Note>
  **Need Help?** Check our [Contact & Support](/en/contact) page or email
  [support@oneclickdz.com](mailto:support@oneclickdz.com)
</Note>