Validate API Key

curl --request GET \
  --url https://billapi.oneclickdz.com/v3/validate \
  --header 'X-Access-Token: <api-key>'

const options = {method: 'GET', headers: {'X-Access-Token': '<api-key>'}};

fetch('https://billapi.oneclickdz.com/v3/validate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billapi.oneclickdz.com/v3/validate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Access-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billapi.oneclickdz.com/v3/validate"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Access-Token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://billapi.oneclickdz.com/v3/validate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Access-Token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "account": {
      "id": "<string>",
      "status": "<string>",
      "currency": "<string>"
    },
    "key": {
      "type": "<string>"
    }
  },
  "meta": {
    "timestamp": "<string>"
  },
  "requestId": "<string>"
}

GET

validate

Validate API Key

curl --request GET \
  --url https://billapi.oneclickdz.com/v3/validate \
  --header 'X-Access-Token: <api-key>'

const options = {method: 'GET', headers: {'X-Access-Token': '<api-key>'}};

fetch('https://billapi.oneclickdz.com/v3/validate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billapi.oneclickdz.com/v3/validate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Access-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billapi.oneclickdz.com/v3/validate"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Access-Token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://billapi.oneclickdz.com/v3/validate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Access-Token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "account": {
      "id": "<string>",
      "status": "<string>",
      "currency": "<string>"
    },
    "key": {
      "type": "<string>"
    }
  },
  "meta": {
    "timestamp": "<string>"
  },
  "requestId": "<string>"
}

Overview

Verifies your Bill Payment API key and echoes back who you are and which environment the key is bound to. It is the first call to make in a new integration and the safest way to prove, before you move any money, that you are pointed at sandbox rather than production.

Each key is bound to exactly one environment — SANDBOX or PRODUCTION. The environment is a property of the key we issue you. Never derive it from the text or the prefix of the key; read key.type from this endpoint.

Bill Payment lives on https://billapi.oneclickdz.com, not on the base URL used by the rest of the platform. The header is the same one you already use: X-Access-Token.

Response

boolean

required

true when the key was verified.

object

required

Show properties

object

required

Show properties

string

required

Your partner account identifier.

string

required

ACTIVE for a key that passed verification.

string

required

Always DZD.

object

required

Show properties

string

required

SANDBOX or PRODUCTION. The only reliable statement of which environment this key acts in.

object

required

Show properties

string

required

Response time, ISO 8601 UTC.

string

required

Correlation identifier, also sent as the X-Request-Id response header.

Examples

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

const response = await fetch("https://billapi.oneclickdz.com/v3/validate", {
  headers: { "X-Access-Token": process.env.ONECLICKDZ_API_KEY },
});

const body = await response.json();

if (!body.success) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

console.log(`Account ${body.data.account.id} — ${body.data.key.type}`);

import os
import requests

response = requests.get(
    'https://billapi.oneclickdz.com/v3/validate',
    headers={'X-Access-Token': os.getenv('ONECLICKDZ_API_KEY')}
)

body = response.json()

if not body['success']:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")

print(f"Account {body['data']['account']['id']} — {body['data']['key']['type']}")

<?php
$ch = curl_init('https://billapi.oneclickdz.com/v3/validate');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Access-Token: ' . getenv('ONECLICKDZ_API_KEY')
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);

if (!$body['success']) {
    throw new Exception($body['error']['code'] . ': ' . $body['error']['message']);
}

echo "Account {$body['data']['account']['id']} — {$body['data']['key']['type']}";
?>

Success Response

{
  "success": true,
  "data": {
    "account": {
      "id": "partner_7f21",
      "status": "ACTIVE",
      "currency": "DZD"
    },
    "key": {
      "type": "SANDBOX"
    }
  },
  "meta": {
    "timestamp": "2026-08-31T10:15:32.194Z"
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

Error Responses

401 — Missing access token

The X-Access-Token header was not sent.

{
  "success": false,
  "error": {
    "code": "MISSING_ACCESS_TOKEN",
    "message": "X-Access-Token header is required."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

What to do: add the header. Bill Payment accepts the key in that header only — never in a query string or a request body.

401 — Invalid access token

The key was rejected.

{
  "success": false,
  "error": {
    "code": "INVALID_ACCESS_TOKEN",
    "message": "The provided access token is invalid."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

What to do: check for a copy-and-paste error, then contact support. Retrying the same key will not change the answer.

503 — Authentication unavailable

We could not verify your key in time. Your key is not the problem.

{
  "success": false,
  "error": {
    "code": "AUTH_UNAVAILABLE",
    "message": "Authentication is temporarily unavailable. Please retry shortly."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

What to do: wait for the Retry-After header (5 seconds) and retry. Never surface this to your customer as an invalid-credentials error, and never disable the key because of it.

503 — Service unavailable

The Bill Payment API is in planned maintenance.

{
  "success": false,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "The service is temporarily unavailable. Please retry shortly."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

What to do: honour Retry-After and retry.

Confirming your environment before go-live

Run this check at start-up, and again in your deployment pipeline. A single line of output tells you whether the key in that environment’s configuration is the one you meant to ship.

async function assertEnvironment(expected) {
  const response = await fetch("https://billapi.oneclickdz.com/v3/validate", {
    headers: { "X-Access-Token": process.env.ONECLICKDZ_API_KEY },
  });

  const body = await response.json();

  if (!body.success) {
    throw new Error(`Key check failed: ${body.error.code}`);
  }

  if (body.data.key.type !== expected) {
    throw new Error(
      `Wrong key: expected ${expected}, got ${body.data.key.type}`,
    );
  }

  return body.data.account.id;
}

// In your sandbox deployment
await assertEnvironment("SANDBOX");

A sandbox key and a production key are interchangeable in shape but not in effect. A production key moves real money on the first successful payment. Verify key.type before you enable the payment path.

What this endpoint does not return

Bill Payment keys have no scopes, no expiry field and no per-key balance, so none of those appear here. account, key.type, meta and requestId are the whole response.

Best Practices

Call it at start-up

One call at boot proves the key works and names the environment, before any customer traffic reaches the payment path.

Never log the key

Log account.id and key.type instead. The key itself belongs in a secret store, never in application logs.

Separate the two keys

Keep the sandbox and production keys in different configuration stores so neither can be reached from the other environment.

Treat 503 as transient

AUTH_UNAVAILABLE means we could not answer in time. Retry after Retry-After; do not roll the key.

List Partners

Check which partners are available

Discover Bills

Start a bill discovery

Bill Payment Overview

How the whole flow fits together

Sandbox Testing

Test every outcome before go-live

API Reference

Core

Account

Mobile Top-Ups

Internet Top-Ups

Gift Cards

Navio

Bill Payment

Validate API Key

Overview

Response

Examples

Success Response

Error Responses

Confirming your environment before go-live

What this endpoint does not return

Best Practices

Call it at start-up

Never log the key

Separate the two keys

Treat 503 as transient

List Partners

Discover Bills

Bill Payment Overview

Sandbox Testing

​Overview

​Response

​Examples

​Success Response

​Error Responses

​Confirming your environment before go-live

​What this endpoint does not return

​Best Practices

Call it at start-up

Never log the key

Separate the two keys

Treat 503 as transient

​Related Endpoints

List Partners

Discover Bills

Bill Payment Overview

Sandbox Testing

Overview

Response

Examples

Success Response

Error Responses

Confirming your environment before go-live

What this endpoint does not return

Best Practices

Related Endpoints