List Transactions

curl --request GET \
  --url https://billapi.oneclickdz.com/v3/bills/transactions \
  --header 'X-Access-Token: <api-key>'

const options = {method: 'GET', headers: {'X-Access-Token': '<api-key>'}};

fetch('https://billapi.oneclickdz.com/v3/bills/transactions', 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/transactions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "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"
	"net/http"
	"io"
)

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Access-Token", "<api-key>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["X-Access-Token"] = '<api-key>'

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

{
  "success": true,
  "data": [
    {}
  ],
  "meta": {
    "timestamp": "<string>",
    "total": 123,
    "limit": 123,
    "offset": 123
  },
  "requestId": "<string>"
}

GET

bills

transactions

List Transactions

curl --request GET \
  --url https://billapi.oneclickdz.com/v3/bills/transactions \
  --header 'X-Access-Token: <api-key>'

const options = {method: 'GET', headers: {'X-Access-Token': '<api-key>'}};

fetch('https://billapi.oneclickdz.com/v3/bills/transactions', 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/transactions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "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"
	"net/http"
	"io"
)

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Access-Token", "<api-key>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["X-Access-Token"] = '<api-key>'

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

{
  "success": true,
  "data": [
    {}
  ],
  "meta": {
    "timestamp": "<string>",
    "total": 123,
    "limit": 123,
    "offset": 123
  },
  "requestId": "<string>"
}

Overview

Returns your Bill Payment transactions, newest first. Use it for reconciliation, for a history screen, and for finding a transaction when you have lost its identifier and its reference. The list is scoped to your own account and to the environment of the key you send: a sandbox key never sees production transactions, and vice versa.

data is a plain array of transaction objects. The counts live in meta: total, limit and offset.

Query Parameters

string

Filter by status. One of PENDING, READY, PROCESSING, SUCCESS, FAILED, REFUNDED, UNKNOWN.

string

Filter by biller. One of ADE, SONELGAZ, SEAAL, AADL, Algérie Télécom.

string

Only transactions created on or after this instant. An ISO 8601 date or date-time, for example 2026-08-01 or 2026-08-01T00:00:00Z.

string

Only transactions created on or before this instant. Same format as from.

integer

default:"20"

Page size, between 1 and 100.

integer

default:"0"

How many transactions to skip. Zero or more.

There is no ref filter on this endpoint. To find a transaction by your own reference, use Get Transaction by Reference.

Response

boolean

required

true when the page was returned.

array

required

An array of transaction objects, newest first. Each entry has exactly the shape documented on Get Transaction by ID — including the rule that bills, selectedBill, receiptUrl, operationId and error appear only in the statuses where they are meaningful.An empty array means no transaction matched.

object

required

Show properties

string

required

Response time, ISO 8601 UTC.

integer

required

How many transactions match the filters in total, ignoring limit and offset.

integer

required

The page size that was applied.

integer

required

The offset that was applied.

string

required

Correlation identifier, also sent as the X-Request-Id response header.

Examples

curl -G https://billapi.oneclickdz.com/v3/bills/transactions \
  --data-urlencode "status=SUCCESS" \
  --data-urlencode "partner=ADE" \
  --data-urlencode "from=2026-08-01" \
  --data-urlencode "to=2026-08-31" \
  --data-urlencode "limit=50" \
  -H "X-Access-Token: YOUR_API_KEY"

const url = new URL("https://billapi.oneclickdz.com/v3/bills/transactions");
url.searchParams.set("status", "SUCCESS");
url.searchParams.set("partner", "ADE");
url.searchParams.set("from", "2026-08-01");
url.searchParams.set("to", "2026-08-31");
url.searchParams.set("limit", "50");

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}: ${body.error.message}`);
}

console.log(`${body.data.length} of ${body.meta.total}`);

import os
import requests

response = requests.get(
    'https://billapi.oneclickdz.com/v3/bills/transactions',
    headers={'X-Access-Token': os.getenv('ONECLICKDZ_API_KEY')},
    params={
        'status': 'SUCCESS',
        'partner': 'ADE',
        'from': '2026-08-01',
        'to': '2026-08-31',
        'limit': 50
    }
)

body = response.json()

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

print(f"{len(body['data'])} of {body['meta']['total']}")

<?php
$query = http_build_query([
    'status'  => 'SUCCESS',
    'partner' => 'ADE',
    'from'    => '2026-08-01',
    'to'      => '2026-08-31',
    'limit'   => 50
]);

$ch = curl_init("https://billapi.oneclickdz.com/v3/bills/transactions?$query");
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'] . ': ' . $body['error']['message']);
}

echo count($body['data']) . ' of ' . $body['meta']['total'];
?>

Success Response

{
  "success": true,
  "data": [
    {
      "transactionId": "68b2f4c1a7d3e9f204c81a55",
      "ref": "disc-inv-2026-0042",
      "type": "payment",
      "status": "SUCCESS",
      "partner": "ADE",
      "account": { "reference": "0123456789012345678901234" },
      "selectedBill": {
        "billId": "sbx_bill_68b2f4c1a7d3e9f204c81a55_0",
        "amount": 443.39,
        "fee": 30.00,
        "label": "Facture ADE"
      },
      "total": 473.39,
      "currency": "DZD",
      "receiptUrl": "https://billapi.oneclickdz.com/v3/bills/transactions/68b2f4c1a7d3e9f204c81a55/receipt",
      "operationId": "op_7726351904",
      "createdAt": "2026-08-31T10:15:32.194Z",
      "updatedAt": "2026-08-31T10:15:41.902Z",
      "completedAt": "2026-08-31T10:15:41.902Z"
    }
  ],
  "meta": {
    "timestamp": "2026-08-31T11:02:14.508Z",
    "total": 137,
    "limit": 50,
    "offset": 0
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

Error Responses

400 — Validation error

A filter value was not accepted.

{
  "success": false,
  "error": {
    "code": "ERR_VALIDATION",
    "message": "status must be one of: PENDING, READY, PROCESSING, UNKNOWN, SUCCESS, FAILED, REFUNDED",
    "details": [
      "status must be one of: PENDING, READY, PROCESSING, UNKNOWN, SUCCESS, FAILED, REFUNDED"
    ]
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

Common causes: a status or partner outside the allowed set, a from or to that is not an ISO 8601 date, a limit above 100 or below 1, a negative offset.What to do: fix the query string. Values are case-sensitive.

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

What to do: verify the key with Validate API Key.

503 — Authentication or service unavailable

We could not verify your key in time, or the 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 the Retry-After header (5 seconds) and retry. Listing is always safe to repeat.

Paging through a period

meta.total is the count for the filters you sent, so you can page until you have seen all of it. Keep the page size modest and the window bounded.

async function* eachTransaction(filters) {
  let offset = 0;
  const limit = 100;

  for (;;) {
    const url = new URL("https://billapi.oneclickdz.com/v3/bills/transactions");
    for (const [key, value] of Object.entries(filters)) {
      url.searchParams.set(key, value);
    }
    url.searchParams.set("limit", String(limit));
    url.searchParams.set("offset", String(offset));

    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);

    for (const transaction of body.data) yield transaction;

    offset += body.data.length;
    if (offset >= body.meta.total || body.data.length === 0) return;
  }
}

// Every successful ADE payment in August
for await (const transaction of eachTransaction({
  status: "SUCCESS",
  partner: "ADE",
  from: "2026-08-01",
  to: "2026-08-31",
})) {
  console.log(transaction.transactionId, transaction.total);
}

New transactions are created while you page. For reconciliation, always bound the window with from and to so the result set cannot grow underneath you.

What the list contains

Both discoveries and payments appear here. type tells them apart:

type: "discovery" — a lookup that has not been paid. Its status is PENDING, READY or FAILED.
type: "payment" — a discovery that a payment was submitted against. Its status is PROCESSING, SUCCESS, FAILED, REFUNDED or UNKNOWN.

A transaction becomes a payment in place, keeping its transactionId and its original ref.

Best Practices

Bound every query

Always send from and to for reconciliation. An unbounded list grows with your business.

Reconcile on SUCCESS and REFUNDED

Those two statuses are where money moved. FAILED never moved any.

Do not poll this endpoint

To follow one transaction, poll it by identifier. Listing repeatedly is slower and heavier for both sides.

Read meta.total

It is the count for your filters, and the only way to know whether another page exists.

Get Transaction by ID

The full transaction object

Get Transaction by Reference

Look up by your own ref

Download Receipt

Proof for a paid transaction

Receipts and Reconciliation

A daily reconciliation routine

API Reference

Core

Account

Mobile Top-Ups

Internet Top-Ups

Gift Cards

Navio

Bill Payment

List Transactions

Overview

Query Parameters

Response

Examples

Success Response

Error Responses

Paging through a period

What the list contains

Best Practices

Bound every query

Reconcile on SUCCESS and REFUNDED

Do not poll this endpoint

Read meta.total

Get Transaction by ID

Get Transaction by Reference

Download Receipt

Receipts and Reconciliation

​Overview

​Query Parameters

​Response

​Examples

​Success Response

​Error Responses

​Paging through a period

​What the list contains

​Best Practices

Bound every query

Reconcile on SUCCESS and REFUNDED

Do not poll this endpoint

Read meta.total

​Related Endpoints

Get Transaction by ID

Get Transaction by Reference

Download Receipt

Receipts and Reconciliation

Overview

Query Parameters

Response

Examples

Success Response

Error Responses

Paging through a period

What the list contains

Best Practices

Related Endpoints