Partners and Accounts - OneClickDz Flexy API

Overview

Before you can discover anything, two things have to be right: the biller has to be available, and the account identifier has to be the one that biller understands. This step covers both, and the difference between the two errors you will see when the second one is wrong.

Everything on this page uses https://billapi.oneclickdz.com and the X-Access-Token header. If you have not confirmed which environment your key belongs to, start with Validate API Key.

Checking availability

GET /v3/partners returns one entry per biller, each with a single status field.

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

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

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

const available = Object.entries(body.data)
  .filter(([, partner]) => partner.status === "ACTIVE")
  .map(([name]) => name);

console.log(available);

import os
import requests

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

body = response.json()
if not body['success']:
    raise RuntimeError(body['error']['code'])

available = [
    name for name, partner in body['data'].items()
    if partner['status'] == 'ACTIVE'
]

print(available)

<?php
$ch = curl_init('https://billapi.oneclickdz.com/v3/partners');
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']);
}

$available = array_keys(array_filter(
    $body['data'],
    fn($partner) => $partner['status'] === 'ACTIVE'
));

print_r($available);
?>

{
  "success": true,
  "data": {
    "ADE": { "status": "ACTIVE" },
    "SONELGAZ": { "status": "ACTIVE" },
    "SEAAL": { "status": "UNAVAILABLE" },
    "AADL": { "status": "UNAVAILABLE" },
    "Algérie Télécom": { "status": "ACTIVE" }
  },
  "meta": { "timestamp": "2026-08-31T10:15:32.194Z" },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

A biller marked UNAVAILABLE answers 503 PARTNER_UNAVAILABLE on discovery and on payment. SEAAL and AADL are currently UNAVAILABLE in both sandbox and production — this is the operator’s current setting, not a permanent limitation, so keep them in your code and let the map decide what to show.

A PRODUCTION key sees live availability; a SANDBOX key sees a fixed map, because a sandbox request never reaches a biller. Do not use sandbox to test how your application reacts to a biller going down — use the dedicated sandbox scenarios for that.

The identifier for each biller

Send exactly one identifier, and send the field that belongs to the biller you are querying. The API returns the same field back in account on every transaction for that biller.

Partner	Field	Format	Valid example
`ADE`	`reference`	Up to 50 characters	`"0123456789012345678901234"`
`SEAAL`	`reference`	Up to 50 characters	`"0123456789012340000000000"`
`SONELGAZ`	`contractNumber`	Up to 50 characters	`"9876543210"`
`AADL`	`aadlNumber`	Up to 50 characters	`"1112223334"`
`Algérie Télécom`	`phoneNumber`	`0` or `+213`, then a digit 2–4, then 7 digits	`"023456789"`

{
  "partner": "ADE",
  "account": { "reference": "0123456789012345678901234" },
  "ref": "disc-inv-2026-0042"
}

Send Algérie Télécom with its accents. The value is compared character for character, and it is also the key you read back from the partner map.

Landline numbers

phoneNumber is an Algerian landline, not a mobile number. Valid:

"023456789" — leading zero, then a digit in the range 2–4
"+213023456789" is not valid; use "+21323456789" or the local "023456789" form

Invalid:

"0778037340" — a mobile number, not a landline
"23456789" — missing the leading zero
"023 45 67 89" — contains spaces
23456789 — a number instead of a string

The richer identifier forms

Two billers accept a fuller object when a single number is not enough to identify a specific bill. Every field inside these objects is required.

SONELGAZ — invoice form

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

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

ADE and SEAAL — 25-character key

electronic_payment_key is accepted as an alternative to reference, and must be exactly 25 characters.

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

Exactly one identifier

The account object must carry one identifier and no more. The fields group into four slots:

Slot	Fields
Reference-style key	`reference`, `contractNumber`, `aadlNumber`, `electronic_payment_key`
Landline	`phoneNumber`, `phone_number`
SONELGAZ invoice	`sonelgaz`
ADE invoice	`ade`

Exactly one slot must be filled. Zero or two is rejected before anything else happens.

{
  "partner": "ADE",
  "account": {
    "reference": "0123456789012345678901234",
    "phoneNumber": "023456789"
  },
  "ref": "disc-inv-2026-0045"
}

{
  "success": false,
  "error": {
    "code": "ERR_VALIDATION",
    "message": "account must contain exactly one identifier (electronic_payment_key, phone_number, sonelgaz, or ade)",
    "details": [
      "account must contain exactly one identifier (electronic_payment_key, phone_number, sonelgaz, or ade)"
    ]
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

Validating this on your own side is one line, and it turns a round trip into an instant form error:

const SLOTS = [
  ["reference", "contractNumber", "aadlNumber", "electronic_payment_key"],
  ["phoneNumber", "phone_number"],
  ["sonelgaz"],
  ["ade"],
];

function hasExactlyOneIdentifier(account) {
  const filled = SLOTS.filter((slot) =>
    slot.some((field) => {
      const value = account[field];
      return value !== undefined && value !== null && value !== "";
    }),
  );

  return filled.length === 1;
}

`ERR_VALIDATION` or `INVALID_ACCOUNT`?

Both are 400, and they mean very different things.

	`ERR_VALIDATION`	`INVALID_ACCOUNT`
Cause	The request does not match the schema	The identifier is well-formed but not usable
Examples	No `ref`; two identifiers; a 24-character `electronic_payment_key`; a mobile number in `phoneNumber`	An account number the biller does not recognise
Whose mistake	Your integration’s	Your customer’s typing
Show to the customer	No — log it	Yes — “check the number on your bill”
Retry unchanged	Never	Only after the customer corrects the number

Do not show ERR_VALIDATION messages to end customers. They name internal field names such as electronic_payment_key, which means nothing to someone holding a paper bill.

Caching the partner map

Availability changes rarely, so refresh it on a timer instead of before every discovery — and keep serving the last good copy if a refresh fails. An empty biller list is worse for your customers than a slightly stale one.

let cache = { map: null, fetchedAt: 0 };
const TTL_MS = 5 * 60 * 1000;

async function getPartners() {
  if (cache.map && Date.now() - cache.fetchedAt < TTL_MS) return cache.map;

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

    const body = await response.json();
    if (body.success) cache = { map: body.data, fetchedAt: Date.now() };
  } catch {
    // Serve the previous map rather than blocking the customer.
  }

  return cache.map ?? {};
}

Caching does not remove the need to handle 503 PARTNER_UNAVAILABLE on discovery. A biller can go down between your last refresh and the customer pressing the button.

Best practices

Validate before you send

Check the slot rule and the landline format client-side. It saves a round trip and gives a better error message.

Cache the map for minutes, not hours

Five minutes is plenty. Refresh in the background, never on the customer’s critical path.

Keep unavailable billers in your code

SEAAL and AADL will come back. Drive the UI from the map, not from a hard-coded list.

Separate the two 400s

INVALID_ACCOUNT is a message for your customer. ERR_VALIDATION is a message for your logs.

Next step

Step 2: Discovering bills

Send a discovery, poll it to READY, and read what is payable

List Partners

The endpoint reference

Discover Bills

Where the account object is sent

Bill Payment Overview

The five-step map

Sandbox Testing

Identifiers that produce a chosen outcome

​Overview

​Checking availability

​The identifier for each biller

​Landline numbers

​The richer identifier forms

​Exactly one identifier

​ERR_VALIDATION or INVALID_ACCOUNT?

​Caching the partner map

​Best practices

Validate before you send

Cache the map for minutes, not hours

Keep unavailable billers in your code

Separate the two 400s

​Next step

Step 2: Discovering bills

​Related pages

List Partners

Discover Bills

Bill Payment Overview

Sandbox Testing

Overview

Checking availability

The identifier for each biller

Landline numbers

The richer identifier forms

Exactly one identifier

`ERR_VALIDATION` or `INVALID_ACCOUNT`?

Caching the partner map

Best practices

Next step

Related pages