Transaction Status - OneClickDz Flexy API

One object for the whole lifecycle

A discovery and the payment made from it are the same transaction, with the same transactionId and the same ref. type is discovery until a payment is accepted, then payment. Read it with GET /v3/bills/transactions/{transactionId} or GET /v3/bills/transactions/by-ref?ref=….

Statuses

Status	Phase	Meaning	Final
`PENDING`	Discovery	Discovery in progress	No
`READY`	Discovery	`bills[]` is available; waiting for `pay`	No
`FAILED`	Discovery	Discovery could not complete; see `error`	Yes
`PROCESSING`	Payment	Payment in progress	No
`UNKNOWN`	Payment	Outcome not yet confirmed	No
`SUCCESS`	Payment	Paid; `receiptUrl` and `operationId` available	Yes
`FAILED`	Payment	Not paid; nothing debited	Yes
`REFUNDED`	Payment	Debited then fully refunded; see `error`	Yes

Fields

Always present:

Field	Type	Description
`transactionId`	string	Transaction identifier
`ref`	string	Your discovery `ref`
`type`	string	`discovery` or `payment`
`status`	string	One of the statuses above
`partner`	string	Biller name
`account`	object	The identifier, echoed under a partner-specific key
`currency`	string	Always `DZD`
`createdAt`	string	ISO 8601
`updatedAt`	string	ISO 8601, last change
`completedAt`	string \| null	`null` while the transaction is in progress. Set when discovery finishes, when a payment becomes `UNKNOWN`, `SUCCESS` or `FAILED`, and when a refund is completed.

Present depending on status:

Field	Present when	Description
`bills[]`	`READY`	Unpaid bills; empty array when nothing is due
`selectedBill`	after `pay`	The bill being paid. For a multi-bill order: `amount` is the combined amount, `billId` is the first id
`selectedBills[]`	after `pay`, multi-bill only	Each bill of the order
`total`	after `pay`	`selectedBill.amount + selectedBill.fee`, the amount debited from your balance
`receiptUrl`	`SUCCESS`	Full URL of the receipt download
`operationId`	`SUCCESS`	The biller’s or payment gateway’s operation reference
`error`	`FAILED`, `REFUNDED`	`{ code, message }`

Branch on status, never on the presence of a field.

`error.code`

Code	Meaning
`PAYMENT_DECLINED`	The bank or the biller’s portal declined the payment
`PARTNER_UNAVAILABLE`	The biller’s portal did not answer
`INVALID_ACCOUNT`	The biller does not recognise the identifier
`BILL_ALREADY_PAID`	The biller reports the bill as already settled

Polling

Phase	Interval	Stop when	Typical duration
Discovery	2–3 s	`status` ≠ `PENDING`	Seconds; a few minutes under load
Payment	5 s	`status` is `SUCCESS`, `FAILED` or `REFUNDED`	Under a few minutes
`UNKNOWN`	60 s	`status` is `SUCCESS` or `REFUNDED`	Usually minutes; longer when manual review is needed

Node.js

const FINAL = new Set(["SUCCESS", "FAILED", "REFUNDED"]);

async function waitForPayment(transactionId) {
  for (;;) {
    const res = await fetch(`https://api.oneclickdz.com/v3/bills/transactions/${transactionId}`, {
      headers: { "X-Access-Token": process.env.ONECLICKDZ_API_KEY },
    });
    const body = await res.json();
    if (!body.success) throw new Error(body.error.code);

    const txn = body.data;
    if (FINAL.has(txn.status)) return txn;

    const delay = txn.status === "UNKNOWN" ? 60_000 : 5_000;
    await new Promise((r) => setTimeout(r, delay));
  }
}

UNKNOWN

UNKNOWN means the payment was submitted to the biller but the result has not been confirmed. Money may or may not have moved. It always resolves to SUCCESS or REFUNDED. While a transaction is UNKNOWN:

Do not start a new payment for the same bill.
Do not refund or credit your customer.
Tell the customer the payment is being confirmed.

Recovering after a timeout

If discover or pay times out on your side, the request may still have been processed.

GET /v3/bills/transactions/by-ref?ref=<your discovery ref>.
404 NOT_FOUND: the discovery was never created. Send it again with the same ref.
Anything else: the transaction exists. Continue from its status.

For a pay timeout, read the transaction by id: PROCESSING or later means the payment was accepted.

Next: Receipts and reconciliation

Download receipts and reconcile your history

​One object for the whole lifecycle

​Statuses

​Fields

​error.code

​Polling

​UNKNOWN

​Recovering after a timeout