Quickstart

Get Your API Key

Create a free account at enterprise.oneclickdz.com

Generate API Keys

Go to Settings → API Section → Generate API KeyYou’ll receive two keys:

Sandbox: Test without real transactions
Production: Live transactions

Secure Your Keys

Store keys securely in environment variables. Never expose them in client-side code or version control.

Always start with Sandbox mode to test your integration safely.

Verify Your API Key

Test your API key with the validate endpoint:

curl https://api.oneclickdz.com/v3/validate \
  -H "X-Access-Token: YOUR_API_KEY"

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);

import requests

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

<?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;
?>

Response:

{
  "success": true,
  "data": {
    "username": "+213665983439",
    "apiKey": {
      "type": "SANDBOX",
      "scope": "READ-WRITE",
      "isEnabled": true
    }
  }
}

If you see "success": true, your API key is working correctly!

Step 1: Send a Mobile Top-Up

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

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"
  }'

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();

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
$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;
?>

Response:

{
  "success": true,
  "data": {
    "topupId": "6901616fe9e88196b4eb64b0",
    "topupRef": "order-001"
  }
}

Step 2: Check Top-Up Status

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

curl https://api.oneclickdz.com/v3/mobile/check-ref/order-001 \
  -H "X-Access-Token: YOUR_API_KEY"

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);

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
$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;
?>

Response:

{
  "success": true,
  "data": {
    "status": "FULFILLED",
    "MSSIDN": "0778037340",
    "topup_amount": 500
  }
}

Status flow: PENDING (5s) → HANDLING (15s) → FULFILLED ✅

Step 3: Try Internet Top-Up

Recharge an ADSL line with a 1000 DZD card:

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"
  }'

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);

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
$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;
?>

Response:

{
  "success": true,
  "data": {
    "topupId": "6901616fe9e88196b4eb64b1",
    "topupRef": "internet-001"
  }
}

Check the internet top-up status:

curl https://api.oneclickdz.com/v3/internet/check-ref/internet-001 \
  -H "X-Access-Token: YOUR_API_KEY"

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);

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
$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;
?>

Response:

{
  "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:

curl https://api.oneclickdz.com/v3/gift-cards/catalog \
  -H "X-Access-Token: YOUR_API_KEY"

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);

import requests

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

<?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;
?>

Place a gift card order:

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
  }'

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);

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
$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;
?>

Response:

{
  "success": true,
  "data": {
    "orderId": "6901616fe9e88196b4eb64c0"
  }
}

Retrieve gift card codes by checking order status:

curl https://api.oneclickdz.com/v3/gift-cards/checkOrder/6901616fe9e88196b4eb64c0 \
  -H "X-Access-Token: YOUR_API_KEY"

// 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);

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
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);
?>

Response when fulfilled:

{
  "success": true,
  "data": {
    "status": "FULFILLED",
    "cards": [
      {
        "value": "XXXX-XXXX-XXXX-XXXX",
        "serial": "123456789"
      }
    ]
  }
}

Card codes are retrieved from the cards array when status is FULFILLED

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

Each workflow guide includes comprehensive sandbox testing instructions and examples.

Understanding Response Format

All API responses follow this structure:

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

Learn about Response Format →

Next Steps

Mobile Top-Up Guide

Complete integration workflow

Internet Top-Up Guide

ADSL and 4G with sandbox testing

Gift Card Guide

Digital product delivery

Error Handling

Handle errors properly

Authentication

Secure API access patterns

Best Practices

Production-ready security

Need Help? Check our Contact & Support page or email [email protected]

Get Started

Advanced Guides

Get Your API Key

Verify Your API Key

Step 1: Send a Mobile Top-Up

Step 2: Check Top-Up Status

Step 3: Try Internet Top-Up

Step 4: Explore Gift Cards

Sandbox Testing

Understanding Response Format

Next Steps

Mobile Top-Up Guide

Internet Top-Up Guide

Gift Card Guide

Error Handling

Authentication

Best Practices

​Get Your API Key

​Verify Your API Key

​Step 1: Send a Mobile Top-Up

​Step 2: Check Top-Up Status

​Step 3: Try Internet Top-Up

​Step 4: Explore Gift Cards

​Sandbox Testing

​Understanding Response Format

​Next Steps

Mobile Top-Up Guide

Internet Top-Up Guide

Gift Card Guide

Error Handling

Authentication

Best Practices

Get Your API Key

Verify Your API Key

Step 1: Send a Mobile Top-Up

Step 2: Check Top-Up Status

Step 3: Try Internet Top-Up

Step 4: Explore Gift Cards

Sandbox Testing

Understanding Response Format

Next Steps