Discover Bills

Discover Bills

curl --request POST \
  --url https://billapi.oneclickdz.com/v3/bills/discover \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Token: <api-key>' \
  --data '
{
  "partner": "<string>",
  "account": {},
  "ref": "<string>"
}
'

import requests

url = "https://billapi.oneclickdz.com/v3/bills/discover"

payload = {
    "partner": "<string>",
    "account": {},
    "ref": "<string>"
}
headers = {
    "X-Access-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Access-Token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({partner: '<string>', account: {}, ref: '<string>'})
};

fetch('https://billapi.oneclickdz.com/v3/bills/discover', 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/bills/discover",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'partner' => '<string>',
    'account' => [
        
    ],
    'ref' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://billapi.oneclickdz.com/v3/bills/discover"

	payload := strings.NewReader("{\n  \"partner\": \"<string>\",\n  \"account\": {},\n  \"ref\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Access-Token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://billapi.oneclickdz.com/v3/bills/discover")
  .header("X-Access-Token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"partner\": \"<string>\",\n  \"account\": {},\n  \"ref\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["X-Access-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"partner\": \"<string>\",\n  \"account\": {},\n  \"ref\": \"<string>\"\n}"

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

{
  "success": true,
  "data": {
    "transactionId": "<string>",
    "ref": "<string>",
    "status": "<string>"
  },
  "meta": {
    "timestamp": "<string>"
  },
  "requestId": "<string>"
}

POST

bills

discover

Discover Bills

curl --request POST \
  --url https://billapi.oneclickdz.com/v3/bills/discover \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Token: <api-key>' \
  --data '
{
  "partner": "<string>",
  "account": {},
  "ref": "<string>"
}
'

import requests

url = "https://billapi.oneclickdz.com/v3/bills/discover"

payload = {
    "partner": "<string>",
    "account": {},
    "ref": "<string>"
}
headers = {
    "X-Access-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Access-Token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({partner: '<string>', account: {}, ref: '<string>'})
};

fetch('https://billapi.oneclickdz.com/v3/bills/discover', 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/bills/discover",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'partner' => '<string>',
    'account' => [
        
    ],
    'ref' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://billapi.oneclickdz.com/v3/bills/discover"

	payload := strings.NewReader("{\n  \"partner\": \"<string>\",\n  \"account\": {},\n  \"ref\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Access-Token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://billapi.oneclickdz.com/v3/bills/discover")
  .header("X-Access-Token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"partner\": \"<string>\",\n  \"account\": {},\n  \"ref\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["X-Access-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"partner\": \"<string>\",\n  \"account\": {},\n  \"ref\": \"<string>\"\n}"

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

{
  "success": true,
  "data": {
    "transactionId": "<string>",
    "ref": "<string>",
    "status": "<string>"
  },
  "meta": {
    "timestamp": "<string>"
  },
  "requestId": "<string>"
}

Overview

Asks a biller what a given account currently owes. The response is a transactionId you then poll; when the transaction reaches READY, its bills[] array holds everything that is payable.

200 is an acknowledgement, not an outcome. It means the request was accepted and a transaction was created. The bills arrive later, in the transaction. Never treat this response as “the account owes nothing”.

Discovery does not move money and does not commit you to anything. It is safe to run before you show a customer what they owe.

Request Body

string

required

The biller to query. Exactly one of ADE, SONELGAZ, SEAAL, AADL, Algérie Télécom — accents included.Check List Partners first; an UNAVAILABLE partner answers 503 PARTNER_UNAVAILABLE.

object

required

The account to look up. It must carry exactly one identifier — see Account identifiers below. Zero identifiers, or two, is rejected.

string

required

Your own reference for this discovery. Maximum 100 characters, and unique among your live transactions for that partner.Reusing a ref answers 403 DUPLICATED_REF. It is also how you recover a lost response — see Get Transaction by Reference.

Account identifiers

Send the field that belongs to the partner you are querying. This is also the field the API returns in account on every transaction for that partner.

Partner	Field	Notes
`ADE`	`reference`	Client reference, up to 50 characters
`SEAAL`	`reference`	Client reference, up to 50 characters
`SONELGAZ`	`contractNumber`	Contract number, up to 50 characters
`AADL`	`aadlNumber`	Housing file number, up to 50 characters
`Algérie Télécom`	`phoneNumber`	Algerian landline, `0` or `+213` followed by a digit 2–4 and 7 more digits

Two richer forms are also accepted where the biller needs more than a single number to identify a bill:

sonelgaz — invoice form

All three fields are required together.

{
  "partner": "SONELGAZ",
  "account": {
    "sonelgaz": {
      "invoice_number": "9876543210",
      "amount_without_stamp": "15000",
      "ebb_key": "ABC123"
    }
  },
  "ref": "disc-inv-2026-0042"
}

invoice_number up to 20 characters, amount_without_stamp up to 20, ebb_key up to 30.

ade — invoice form

All four fields are required together.

{
  "partner": "ADE",
  "account": {
    "ade": {
      "sub_id": "000123456789",
      "period": "07/2026",
      "amount": "12000",
      "pay_key": "1234567"
    }
  },
  "ref": "disc-inv-2026-0043"
}

sub_id exactly 12 characters, period in MM/YYYY format, amount up to 20 characters, pay_key exactly 7 characters.

electronic_payment_key — 25-character key

Accepted for ADE and SEAAL as an alternative to reference. It must be exactly 25 characters.

{
  "partner": "ADE",
  "account": { "electronic_payment_key": "0123456789012345678901234" },
  "ref": "disc-inv-2026-0044"
}

Exactly one identifier. reference, contractNumber, aadlNumber and electronic_payment_key count as the same slot, as do phoneNumber and phone_number; sonelgaz and ade are each their own slot. Sending none, or sending two, is rejected with 400.

Response

boolean

required

true when the discovery was accepted.

object

required

Show properties

string

required

The transaction to poll. A 24-character lowercase hexadecimal string.

string

required

The ref you sent, echoed back.

string

required

Always PENDING at this point.

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/bills/discover \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Access-Token: YOUR_API_KEY" \
  -d '{
    "partner": "ADE",
    "account": { "reference": "0123456789012345678901234" },
    "ref": "disc-inv-2026-0042"
  }'

const response = await fetch(
  "https://billapi.oneclickdz.com/v3/bills/discover",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Access-Token": process.env.ONECLICKDZ_API_KEY,
    },
    body: JSON.stringify({
      partner: "ADE",
      account: { reference: "0123456789012345678901234" },
      ref: "disc-inv-2026-0042",
    }),
  },
);

const body = await response.json();

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

// Accepted — the bills are not here yet. Poll this id until READY.
console.log(body.data.transactionId);

import os
import requests

response = requests.post(
    'https://billapi.oneclickdz.com/v3/bills/discover',
    headers={
        'Content-Type': 'application/json',
        'X-Access-Token': os.getenv('ONECLICKDZ_API_KEY')
    },
    json={
        'partner': 'ADE',
        'account': {'reference': '0123456789012345678901234'},
        'ref': 'disc-inv-2026-0042'
    }
)

body = response.json()

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

# Accepted — the bills are not here yet. Poll this id until READY.
print(body['data']['transactionId'])

<?php
$payload = [
    'partner' => 'ADE',
    'account' => ['reference' => '0123456789012345678901234'],
    'ref'     => 'disc-inv-2026-0042'
];

$ch = curl_init('https://billapi.oneclickdz.com/v3/bills/discover');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-Access-Token: ' . getenv('ONECLICKDZ_API_KEY')
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

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

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

// Accepted — the bills are not here yet. Poll this id until READY.
echo $body['data']['transactionId'];
?>

Success Response

{
  "success": true,
  "data": {
    "transactionId": "68b2f4c1a7d3e9f204c81a55",
    "ref": "disc-inv-2026-0042",
    "status": "PENDING"
  },
  "meta": {
    "timestamp": "2026-08-31T10:15:32.194Z"
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

Poll Get Transaction by ID until status is READY, then read bills[]:

{
  "success": true,
  "data": {
    "transactionId": "68b2f4c1a7d3e9f204c81a55",
    "ref": "disc-inv-2026-0042",
    "type": "discovery",
    "status": "READY",
    "partner": "ADE",
    "account": { "reference": "0123456789012345678901234" },
    "bills": [
      {
        "billId": "sbx_bill_68b2f4c1a7d3e9f204c81a55_0",
        "amount": 443.39,
        "fee": 30.00,
        "label": "Facture ADE"
      }
    ],
    "currency": "DZD",
    "createdAt": "2026-08-31T10:15:32.194Z",
    "updatedAt": "2026-08-31T10:15:33.008Z",
    "completedAt": "2026-08-31T10:15:33.008Z"
  },
  "meta": {
    "timestamp": "2026-08-31T10:15:34.120Z"
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

Error Responses

400 — Validation error

The request body did not match the schema.

{
  "success": false,
  "error": {
    "code": "ERR_VALIDATION",
    "message": "ref is required",
    "details": ["ref is required"]
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

details lists every field that failed, not just the first. Common causes: a missing ref, a partner that is not one of the five values, an account with no identifier or with two, an electronic_payment_key that is not exactly 25 characters, a phoneNumber that is not a valid Algerian landline.What to do: fix the request. Retrying it unchanged returns the same error.

400 — Invalid account

The identifier is structurally acceptable but not usable for this partner.

{
  "success": false,
  "error": {
    "code": "INVALID_ACCOUNT",
    "message": "The provided account identifier is invalid."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

What to do: ask the customer to check the number on their bill. This is the error to surface to them; ERR_VALIDATION is one for your logs.

401 — Missing or invalid access token

The key was absent or rejected.

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

A missing header returns MISSING_ACCESS_TOKEN instead, with the same HTTP status.What to do: verify the key with Validate API Key.

403 — Duplicate reference

You have already used this ref for this partner.

{
  "success": false,
  "error": {
    "code": "DUPLICATED_REF",
    "message": "A transaction with this ref already exists for this partner."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

What to do: do not retry with a new ref blindly — you would start a second discovery for the same account. Look the existing one up with Get Transaction by Reference and carry on from its state.

409 — Bill already paid

This account was already paid recently, so a new discovery is refused.

{
  "success": false,
  "error": {
    "code": "BILL_ALREADY_PAID",
    "message": "This bill has already been paid."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

What to do: this is a guard against double payment, not a failure. Find the successful transaction in List Transactions and show the customer that receipt.

409 — Payment in progress

Another payment for this account has not finished yet.

{
  "success": false,
  "error": {
    "code": "PAYMENT_IN_PROGRESS",
    "message": "A payment for this account is currently in progress."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

What to do: wait for that payment to reach a final state, then start again. Do not run both in parallel.

503 — Partner unavailable

The biller cannot be reached, or is currently switched off.

{
  "success": false,
  "error": {
    "code": "PARTNER_UNAVAILABLE",
    "message": "Partner temporarily unavailable — please try again later."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

What to do: refresh List Partners and try again later. No transaction was created and nothing was charged. This response carries no Retry-After; back off on your side.

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 Retry-After (5 seconds) and retry the same request with the same ref.

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 with the same ref.

500 — Internal error

Something failed on our side.

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

What to do: check whether the discovery was created with Get Transaction by Reference before retrying, and send the requestId to support if it persists.

The 200 DZD discovery floor

Bills below 200 DZD are filtered out during discovery and never appear in bills[]. A READY transaction with an empty bills[] therefore means one of two things, and the API does not distinguish between them:

the account owes nothing, or
everything it owes is below the 200 DZD floor.

Word this carefully for your customers. “No bills are payable right now” is accurate; “you owe nothing” is not.

Preventing duplicate requests

ref makes a discovery safe to retry. If a network error hides the response, look the ref up instead of sending a second discovery.

async function discoverSafely(partner, account, ref) {
  try {
    const response = await fetch(
      "https://billapi.oneclickdz.com/v3/bills/discover",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-Access-Token": process.env.ONECLICKDZ_API_KEY,
        },
        body: JSON.stringify({ partner, account, ref }),
      },
    );

    const body = await response.json();

    if (body.success) {
      return body.data.transactionId;
    }

    // Already started earlier — recover it instead of starting a second one.
    if (body.error.code === "DUPLICATED_REF") {
      return await findByRef(ref, partner);
    }

    throw new Error(`${body.error.code}: ${body.error.message}`);
  } catch (networkError) {
    // The request may still have been accepted. Check before retrying.
    const existing = await findByRef(ref, partner).catch(() => null);
    if (existing) return existing;
    throw networkError;
  }
}

async function findByRef(ref, partner) {
  const url = new URL(
    "https://billapi.oneclickdz.com/v3/bills/transactions/by-ref",
  );
  url.searchParams.set("ref", ref);
  url.searchParams.set("partner", partner);

  const response = await fetch(url, {
    headers: { "X-Access-Token": process.env.ONECLICKDZ_API_KEY },
  });

  const body = await response.json();
  if (!body.success) throw new Error(body.error.code);
  return body.data.transactionId;
}

A good ref is derived from something you already store — your own invoice or order identifier — so you can always reconstruct it. See Discovering bills for a naming recipe.

Status Lifecycle

PENDING

The response you just received. The discovery is queued and running.

READY

Discovery finished. bills[] is present — possibly empty. Choose a billId and call Pay a Bill.

FAILED

The discovery could not complete. error.code explains why: INVALID_ACCOUNT, PARTNER_UNAVAILABLE, BILL_ALREADY_PAID or PAYMENT_DECLINED.

Full status reference →

Best Practices

Check the partner first

A cached partner map lets you hide an unavailable biller before the customer fills in an account number.

Derive the ref, do not invent it

Build ref from your own order identifier so you can always look the transaction up again.

Never assume 200 means empty

The bills arrive in the transaction, not in this response. Poll before you tell a customer anything.

Read fee from the response

Each bill carries its own fee. Do not recompute it in your own code.

List Partners

Check availability first

Get Transaction by ID

Poll for the bills

Pay a Bill

Pay one of them

Get Transaction by Reference

Recover a lost response

Discovering Bills

The full walkthrough

Partners and Accounts

Identifier rules per partner

API Reference

Core

Account

Mobile Top-Ups

Internet Top-Ups

Gift Cards

Navio

Bill Payment

Overview

Request Body

Account identifiers

Response

Examples

Success Response

Error Responses

The 200 DZD discovery floor

Preventing duplicate requests

Status Lifecycle

Best Practices

Check the partner first

Derive the ref, do not invent it

Never assume 200 means empty

Read fee from the response

List Partners

Get Transaction by ID

Pay a Bill

Get Transaction by Reference

Discovering Bills

Partners and Accounts

​Overview

​Request Body

​Account identifiers

​Response

​Examples

​Success Response

​Error Responses

​The 200 DZD discovery floor

​Preventing duplicate requests

​Status Lifecycle

​Best Practices

Check the partner first

Derive the ref, do not invent it

Never assume 200 means empty

Read fee from the response

​Related Endpoints

List Partners

Get Transaction by ID

Pay a Bill

Get Transaction by Reference

Discovering Bills

Partners and Accounts

Overview

Request Body

Account identifiers

Response

Examples

Success Response

Error Responses

The 200 DZD discovery floor

Preventing duplicate requests

Status Lifecycle

Best Practices

Related Endpoints