Paying Bills - OneClickDz Flexy API

Overview

Payment is the write half of Bill Payment. You take one billId from a READY discovery, submit it, and the same transaction carries the payment through to a final state. This is the call that moves money, so the order of operations matters more here than anywhere else in the integration: write your own record first, send once, then poll.

The 200 from pay means the payment was accepted and is in flight. It does not mean the bill was paid. The outcome only ever appears in the transaction’s status.

Choosing a bill

bills[] on a READY transaction may hold several entries. Pick one — a payment pays exactly one bill.

{
  "status": "READY",
  "bills": [
    {
      "billId": "sbx_bill_68b2f4c1a7d3e9f204c81a55_0",
      "amount": 1200.0,
      "fee": 30.0,
      "label": "Facture SONELGAZ"
    },
    {
      "billId": "sbx_bill_68b2f4c1a7d3e9f204c81a55_1",
      "amount": 850.0,
      "fee": 30.00,
      "label": "Facture SONELGAZ"
    }
  ]
}

To pay several bills for one account, pay the first, wait for it to reach a final state, then run a fresh discovery. Two payments in flight for the same account are refused with 409 PAYMENT_IN_PROGRESS.

What your customer pays

Field	Meaning
`amount`	What the biller is owed
`fee`	The OneClickDz service fee for paying it
`total`	`amount + fee` — the figure debited from your balance

The fee is a percentage of the amount, clamped between a minimum and a maximum, and it is set per biller:

Biller	Percentage	Minimum	Maximum
`ADE`	0.5%	30 DZD	60 DZD
`SONELGAZ`	0.5%	30 DZD	60 DZD
`Algérie Télécom`	0.5%	10 DZD	50 DZD

SEAAL and AADL are currently unavailable, so no fee is published for them. Worked through, for ADE and SONELGAZ:

Bill amount	0.5% of it	Applied fee	Total
150.00	0.75	—	Below the 200 DZD floor; never appears in `bills[]`
320.00	1.60	30.00 (minimum)	350.00
443.39	2.22	30.00 (minimum)	473.39
1200.00	6.00	30.00 (minimum)	1230.00
6000.00	30.00	30.00 (the percentage, at last)	6030.00
15000.00	75.00	60.00 (maximum)	15060.00

The percentage only starts to matter on large bills. For ADE and SONELGAZ every bill up to 6,000 DZD is charged the 30 DZD minimum, and nothing is ever charged more than 60 DZD. For Algérie Télécom the equivalent thresholds are 2,000 DZD and 10,000 DZD.

Read fee from the response. The percentage and the clamps are configuration, not constants — a fee you calculate yourself will eventually disagree with the one you are charged.

Before you send

Persist your own record

Write the order — customer, transactionId, billId, amount, fee, total, and the ref you are about to use — before the request leaves your process. If the response is lost, that row is how you find the payment again.

Confirm the total with your customer

Show amount and fee separately, and the total you will charge. Never show an estimate.

Send once

One call, with a ref that is new for this biller.

Poll to a final state

SUCCESS, FAILED or REFUNDED.→ Step 4: Status polling

Submitting the payment

Three fields, all required.

{
  "transactionId": "68b2f4c1a7d3e9f204c81a55",
  "billId": "sbx_bill_68b2f4c1a7d3e9f204c81a55_0",
  "ref": "pay-inv-2026-0042"
}

Use a new ref, different from the discovery’s. Reusing the discovery ref here answers 403 DUPLICATED_REF. The transaction keeps its original discovery ref — that is what the response echoes back and what by-ref looks up.

curl https://billapi.oneclickdz.com/v3/bills/pay \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Access-Token: YOUR_API_KEY" \
  -d '{
    "transactionId": "68b2f4c1a7d3e9f204c81a55",
    "billId": "sbx_bill_68b2f4c1a7d3e9f204c81a55_0",
    "ref": "pay-inv-2026-0042"
  }'

const BASE = "https://billapi.oneclickdz.com";
const KEY = process.env.ONECLICKDZ_API_KEY;

async function payBill(order, bill) {
  // 1. Persist before sending — this row is your recovery path.
  await db.payments.insert({
    orderId: order.id,
    transactionId: order.transactionId,
    billId: bill.billId,
    amount: bill.amount,
    fee: bill.fee,
    total: bill.amount + bill.fee,
    discoveryRef: order.discoveryRef,
    paymentRef: `pay-${order.id}`,
    state: "SUBMITTING",
  });

  const response = await fetch(`${BASE}/v3/bills/pay`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Access-Token": KEY,
    },
    body: JSON.stringify({
      transactionId: order.transactionId,
      billId: bill.billId,
      ref: `pay-${order.id}`,
    }),
  });

  const body = await response.json();

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

  // PROCESSING — in flight, not paid.
  await db.payments.update(order.id, { state: "PROCESSING" });
  return body.data.transactionId;
}

import os
import requests

BASE = 'https://billapi.oneclickdz.com'
KEY = os.getenv('ONECLICKDZ_API_KEY')


def pay_bill(order, bill):
    # 1. Persist before sending — this row is your recovery path.
    db.payments.insert({
        'order_id': order['id'],
        'transaction_id': order['transaction_id'],
        'bill_id': bill['billId'],
        'amount': bill['amount'],
        'fee': bill['fee'],
        'total': bill['amount'] + bill['fee'],
        'discovery_ref': order['discovery_ref'],
        'payment_ref': f"pay-{order['id']}",
        'state': 'SUBMITTING'
    })

    response = requests.post(
        f'{BASE}/v3/bills/pay',
        headers={
            'Content-Type': 'application/json',
            'X-Access-Token': KEY
        },
        json={
            'transactionId': order['transaction_id'],
            'billId': bill['billId'],
            'ref': f"pay-{order['id']}"
        }
    )

    body = response.json()

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

    # PROCESSING — in flight, not paid.
    db.payments.update(order['id'], {'state': 'PROCESSING'})
    return body['data']['transactionId']

<?php
const BASE = 'https://billapi.oneclickdz.com';

function payBill(array $order, array $bill): string
{
    // 1. Persist before sending — this row is your recovery path.
    $db->payments->insert([
        'order_id'       => $order['id'],
        'transaction_id' => $order['transaction_id'],
        'bill_id'        => $bill['billId'],
        'amount'         => $bill['amount'],
        'fee'            => $bill['fee'],
        'total'          => $bill['amount'] + $bill['fee'],
        'discovery_ref'  => $order['discovery_ref'],
        'payment_ref'    => 'pay-' . $order['id'],
        'state'          => 'SUBMITTING'
    ]);

    $ch = curl_init(BASE . '/v3/bills/pay');
    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([
        'transactionId' => $order['transaction_id'],
        'billId'        => $bill['billId'],
        'ref'           => 'pay-' . $order['id']
    ]));

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

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

    // PROCESSING — in flight, not paid.
    $db->payments->update($order['id'], ['state' => 'PROCESSING']);
    return $body['data']['transactionId'];
}
?>

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

The three guards

Three rules stop the same money moving twice. All three answer before anything is charged.

Guard	Response	Meaning
Duplicate reference	`403 DUPLICATED_REF`	This `ref` already belongs to a live transaction for this biller
Already paid	`409 BILL_ALREADY_PAID`	This bill has already been paid successfully
Payment in flight	`409 PAYMENT_IN_PROGRESS`	Another payment for this bill has not finished

None of these is a reason to retry with a different ref. Each one means the work is either already done or already running. Retrying around a guard is how a customer gets charged twice.

The right response to all three is the same: read the transaction and continue from its state.

async function payOnce(order, bill) {
  try {
    return await payBill(order, bill);
  } catch (error) {
    const [code] = String(error.message).split(":");

    if (["DUPLICATED_REF", "BILL_ALREADY_PAID", "PAYMENT_IN_PROGRESS"].includes(code)) {
      // Already handled by us or by an earlier attempt — do not send again.
      const transaction = await getTransaction(order.transactionId);
      return transaction.transactionId;
    }

    throw error;
  }
}

When the response never arrives

A timeout tells you nothing about whether the payment happened. Read the transaction before you do anything else.

async function settleUnknownOutcome(order) {
  const response = await fetch(
    `${BASE}/v3/bills/transactions/${order.transactionId}`,
    { headers: { "X-Access-Token": KEY } },
  );

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

  switch (body.data.status) {
    case "READY":
      return "NOT_SENT"; // The payment never started — safe to send it.
    case "PROCESSING":
    case "UNKNOWN":
      return "IN_FLIGHT"; // Keep polling. Do not resend.
    case "SUCCESS":
    case "FAILED":
    case "REFUNDED":
      return body.data.status; // Already settled.
    default:
      return "IN_FLIGHT";
  }
}

Never resend a payment because a request timed out. A transaction still on READY is the only state that proves the payment did not start.

Errors you will meet

Error	HTTP	What it means	What to do
`ERR_VALIDATION`	400	The body does not match the schema	Fix the request; never retry unchanged
`DUPLICATED_REF`	403	The `ref` is already in use for this biller	Read the transaction; do not resend
`NOT_FOUND`	404	Not yours, not `READY`, or that `billId` is not on it	Re-read the transaction before doing anything
`BILL_ALREADY_PAID`	409	This bill was already paid	Use the existing receipt; do not charge twice
`PAYMENT_IN_PROGRESS`	409	Another payment for this bill is running	Poll the running one
`PARTNER_UNAVAILABLE`	503	The biller is unreachable or switched off	Nothing was charged; the discovery is still `READY`
`AUTH_UNAVAILABLE`	503	We could not verify your key in time	Honour `Retry-After`; the request never reached the payment path
`SERVICE_UNAVAILABLE`	503	Planned maintenance	Honour `Retry-After` and retry
`INTERNAL_ERROR`	500	Something failed on our side	Read the transaction first; never resend blindly

Best practices

Write before you send

Persist the order and its ref first. A lost response is then always recoverable.

One ref per call

disc- for the discovery, pay- for the payment, both derived from your order id.

Charge the returned total

Debit your customer the total the API produced, never a figure you computed.

Treat a guard as an answer

403 and 409 mean the work is done or running. Look it up rather than working around it.

Next step

Step 4: Status polling

Follow the payment to a final state, and handle UNKNOWN correctly

Pay a Bill

The endpoint reference

Get Transaction by ID

The transaction object in full

Discovering Bills

Where billId comes from

Receipts and Reconciliation

What to keep after a success

​Overview

​Choosing a bill

​What your customer pays

​Before you send

​Submitting the payment

​The three guards

​When the response never arrives

​Errors you will meet

​Best practices

Write before you send

One ref per call

Charge the returned total

Treat a guard as an answer

​Next step

Step 4: Status polling

​Related pages

Pay a Bill

Get Transaction by ID

Discovering Bills

Receipts and Reconciliation

Overview

Choosing a bill

What your customer pays

Before you send

Submitting the payment

The three guards

When the response never arrives

Errors you will meet

Best practices

Next step

Related pages