Get Transaction by Reference

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

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

fetch('https://billapi.oneclickdz.com/v3/bills/transactions/by-ref', 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/by-ref",
  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/by-ref"

	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/by-ref")

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>"
  },
  "requestId": "<string>"
}

GET

bills

transactions

by-ref

Get Transaction by Reference

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

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

fetch('https://billapi.oneclickdz.com/v3/bills/transactions/by-ref', 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/by-ref",
  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/by-ref"

	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/by-ref")

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>"
  },
  "requestId": "<string>"
}

Overview

Finds a transaction by the ref you sent when you started the discovery. It returns exactly the same object as Get Transaction by ID. This is the recovery path. When a response is lost to a timeout, a crash or a redeploy, look the ref up — never resend the write.

A ref is unique per partner, not globally. If you reuse the same ref string for two different partners, pass partner as well so the lookup is unambiguous.

Query Parameters

string

required

The reference you supplied when you created the discovery. Maximum 100 characters.

string

Optional. One of ADE, SONELGAZ, SEAAL, AADL, Algérie Télécom. Narrows the lookup to that biller.

Response

Identical to Get Transaction by ID — the full transaction object, wrapped in the standard envelope. See that page for the field-by-field reference and for which fields appear in which status.

boolean

required

true when a transaction was found.

object

required

The transaction object. Full field reference →

object

required

Show properties

string

required

Response time, ISO 8601 UTC.

string

required

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

Examples

curl -G https://billapi.oneclickdz.com/v3/bills/transactions/by-ref \
  --data-urlencode "ref=disc-inv-2026-0042" \
  --data-urlencode "partner=ADE" \
  -H "X-Access-Token: YOUR_API_KEY"

const url = new URL(
  "https://billapi.oneclickdz.com/v3/bills/transactions/by-ref",
);
url.searchParams.set("ref", "disc-inv-2026-0042");
url.searchParams.set("partner", "ADE");

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.transactionId, body.data.status);

import os
import requests

response = requests.get(
    'https://billapi.oneclickdz.com/v3/bills/transactions/by-ref',
    headers={'X-Access-Token': os.getenv('ONECLICKDZ_API_KEY')},
    params={'ref': 'disc-inv-2026-0042', 'partner': 'ADE'}
)

body = response.json()

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

print(body['data']['transactionId'], body['data']['status'])

<?php
$query = http_build_query([
    'ref'     => 'disc-inv-2026-0042',
    'partner' => 'ADE'
]);

$ch = curl_init("https://billapi.oneclickdz.com/v3/bills/transactions/by-ref?$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 $body['data']['transactionId'] . ' ' . $body['data']['status'];
?>

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-31T10:16:03.771Z"
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

Error Responses

400 — Validation error

ref was missing, too long, or partner was not a known value.

{
  "success": false,
  "error": {
    "code": "ERR_VALIDATION",
    "message": "ref is required."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

What to do: send ref as a query parameter, URL-encoded, at most 100 characters.

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.

404 — Transaction not found

No transaction with that ref belongs to your account in this environment.

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Transaction not found."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

What to do: after a failed write, a 404 here is the proof that the request never landed — it is safe to send it again with the same ref. Check too that you are using the key for the environment the transaction was created in.

503 — Authentication or service unavailable

We could not verify your key in time, or the API is in planned maintenance.

{
  "success": false,
  "error": {
    "code": "AUTH_UNAVAILABLE",
    "message": "Authentication is temporarily unavailable. Please retry shortly."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

What to do: honour the Retry-After header (5 seconds) and retry. A lookup is always safe to repeat.

Recovering from a lost response

The pattern is the same for a discovery and for a payment: if the write failed in a way you cannot explain, ask what the ref resolved to before you send anything again.

async function resolveRef(ref, partner) {
  const url = new URL(
    "https://billapi.oneclickdz.com/v3/bills/transactions/by-ref",
  );
  url.searchParams.set("ref", ref);
  if (partner) url.searchParams.set("partner", partner);

  const response = await fetch(url, {
    headers: { "X-Access-Token": process.env.ONECLICKDZ_API_KEY },
  });

  const body = await response.json();

  if (body.success) {
    return body.data; // The write landed. Continue from data.status.
  }

  if (body.error.code === "NOT_FOUND") {
    return null; // The write never landed. Safe to send it again.
  }

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

A 404 from this endpoint is only meaningful when you are asking about a ref you definitely sent. Never use it to decide that a payment did not happen when the discovery ref is what you looked up — a payment lives on the same transaction as its discovery, under the discovery’s ref.

Best Practices

Look up, do not resend

Every timeout and every DUPLICATED_REF is answered here, not by a second write.

Pass the partner

It costs nothing and removes any ambiguity when the same ref string exists for two billers.

Store the ref with your order

A ref you cannot reconstruct is a transaction you cannot recover.

Poll by ID once you have it

Use this endpoint to recover, then poll by transactionId — one fewer parameter to get wrong.

Get Transaction by ID

The full transaction object

List Transactions

Filter and paginate history

Discover Bills

Where a ref is created

Status Polling

A production-grade poller

API Reference

Core

Account

Mobile Top-Ups

Internet Top-Ups

Gift Cards

Navio

Bill Payment

Get Transaction by Reference

Overview

Query Parameters

Response

Examples

Success Response

Error Responses

Recovering from a lost response

Best Practices

Look up, do not resend

Pass the partner

Store the ref with your order

Poll by ID once you have it

Get Transaction by ID

List Transactions

Discover Bills

Status Polling

​Overview

​Query Parameters

​Response

​Examples

​Success Response

​Error Responses

​Recovering from a lost response

​Best Practices

Look up, do not resend

Pass the partner

Store the ref with your order

Poll by ID once you have it

​Related Endpoints

Get Transaction by ID

List Transactions

Discover Bills

Status Polling

Overview

Query Parameters

Response

Examples

Success Response

Error Responses

Recovering from a lost response

Best Practices

Related Endpoints