Paying Bills - OneClickDz Flexy API

Before you call

The transaction must be READY.
Show the customer amount, fee and their sum for every bill they selected, and get their confirmation.
Persist your own order record first. pay moves money.

Request

POST /v3/bills/pay takes the discovery transactionId, the bill(s) to pay and a new ref.

Field	Type	Rules
`transactionId`	string	The `READY` discovery, 24 hexadecimal characters
`billId`	string	One `billId` from that transaction’s `bills[]`
`billIds`	string[]	1 to 50 distinct `billId`s from `bills[]`, paid as one order
`ref`	string	A new unique reference for this payment, up to 100 characters

Send billId or billIds, never both.

ref must not be the discovery ref. The API keeps the discovery ref on the transaction and refuses any ref that is still in use for that partner with 403 DUPLICATED_REF. A simple convention: <discoveryRef>-pay.

curl -X POST https://api.oneclickdz.com/v3/bills/pay \
  -H "X-Access-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "68cdf0a2b7c1e4d5f6a7b8c9",
    "billId": "0123456789012345678901234",
    "ref": "disc-20260920-0001-pay"
  }'

const response = await fetch("https://api.oneclickdz.com/v3/bills/pay", {
  method: "POST",
  headers: {
    "X-Access-Token": process.env.ONECLICKDZ_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    transactionId: "68cdf0a2b7c1e4d5f6a7b8c9",
    billId: "0123456789012345678901234",
    ref: "disc-20260920-0001-pay",
  }),
});

const body = await response.json();
if (!body.success) throw new Error(`${body.error.code}: ${body.error.message}`);
// body.data.status is PROCESSING — poll the transaction for the outcome

import os, requests

response = requests.post(
    "https://api.oneclickdz.com/v3/bills/pay",
    headers={"X-Access-Token": os.environ["ONECLICKDZ_API_KEY"]},
    json={
        "transactionId": "68cdf0a2b7c1e4d5f6a7b8c9",
        "billId": "0123456789012345678901234",
        "ref": "disc-20260920-0001-pay",
    },
)

body = response.json()
if not body["success"]:
    raise RuntimeError(f'{body["error"]["code"]}: {body["error"]["message"]}')
# body["data"]["status"] is PROCESSING — poll the transaction for the outcome

<?php
$ch = curl_init("https://api.oneclickdz.com/v3/bills/pay");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "X-Access-Token: " . getenv("ONECLICKDZ_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "transactionId" => "68cdf0a2b7c1e4d5f6a7b8c9",
        "billId" => "0123456789012345678901234",
        "ref" => "disc-20260920-0001-pay",
    ]),
]);

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

if (!$body["success"]) {
    throw new Exception($body["error"]["code"] . ": " . $body["error"]["message"]);
}
// $body["data"]["status"] is PROCESSING — poll the transaction for the outcome
?>

Response

{
  "success": true,
  "data": {
    "transactionId": "68cdf0a2b7c1e4d5f6a7b8c9",
    "ref": "disc-20260920-0001",
    "status": "PROCESSING"
  },
  "meta": { "timestamp": "2026-09-20T10:16:04.512Z" },
  "requestId": "req_5f6g7h8i9j0k1l2m3n4o5p6q"
}

ref in the response is the discovery ref: the transaction keeps one reference for its whole life. 200 means the payment was accepted, not that it succeeded.

Paying several bills at once

Send billIds instead of billId. The bills are settled as one order and their fee is the sum of the selected bills’ fee. Only SEAAL settles several bills as one order: for any other partner, billIds with more than one id answers 400 ERR_VALIDATION.

{
  "transactionId": "68cdf0a2b7c1e4d5f6a7b8c9",
  "billIds": ["F061612640", "F060286499", "F059107062"],
  "ref": "disc-20260920-0003-pay"
}

On the transaction, selectedBill then holds the aggregate (amount = sum of the bills, billId = the first id) and selectedBills[] lists each bill individually. Use selectedBills for reconciliation. This applies to any biller whose discovery returned several bills. SEAAL accounts commonly do.

Follow the payment

Poll GET /v3/bills/transactions/{transactionId} every 5 seconds until status is SUCCESS, FAILED or REFUNDED.

`status`	Meaning	What to do
`PROCESSING`	Payment in progress	Keep polling
`UNKNOWN`	Outcome not yet confirmed	Keep polling; never retry, never refund your customer
`SUCCESS`	Paid	Download the receipt
`FAILED`	Not paid, nothing debited	Read `error.code`; the customer may retry with a new discovery
`REFUNDED`	Debited then fully refunded	Read `error.code`; the customer may retry with a new discovery

Details of every status and field: Transaction status.

Synchronous errors

Error	HTTP	Meaning
`ERR_VALIDATION`	400	Bad `transactionId`, both or neither of `billId`/`billIds`, missing `ref`
`DUPLICATED_REF`	403	`ref` already in use for this partner (including the discovery `ref`)
`NOT_FOUND`	404	Transaction unknown, not yours, not `READY`, or a `billId` is not in its `bills[]`
`BILL_ALREADY_PAID`	409	One of the selected bills was already paid through this API
`PAYMENT_IN_PROGRESS`	409	A payment for one of the selected bills is already running
`PARTNER_UNAVAILABLE`	503	The biller is unavailable; nothing was charged

A 4xx/5xx here means nothing moved. A network timeout means you do not know: look the transaction up before doing anything else.

Next: Transaction status

Every status, every field, how to poll

​Before you call

​Request

​Response

​Paying several bills at once

​Follow the payment

​Synchronous errors

Next: Transaction status

Before you call

Request

Response

Paying several bills at once

Follow the payment

Synchronous errors