Get Transaction by ID

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

import requests

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

headers = {"X-Access-Token": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

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

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

	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/{transactionId}")

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": {
    "transactionId": "<string>",
    "ref": "<string>",
    "type": "<string>",
    "status": "<string>",
    "partner": "<string>",
    "account": {},
    "currency": "<string>",
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "completedAt": {},
    "bills": [
      {
        "billId": "<string>",
        "amount": 123,
        "fee": 123,
        "label": "<string>",
        "period": "<string>"
      }
    ],
    "selectedBill": {},
    "total": 123,
    "receiptUrl": "<string>",
    "operationId": "<string>",
    "error": {
      "code": "<string>",
      "message": "<string>"
    }
  },
  "meta": {
    "timestamp": "<string>"
  },
  "requestId": "<string>"
}

GET

bills

transactions

{transactionId}

Get Transaction by ID

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

import requests

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

headers = {"X-Access-Token": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

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

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

	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/{transactionId}")

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": {
    "transactionId": "<string>",
    "ref": "<string>",
    "type": "<string>",
    "status": "<string>",
    "partner": "<string>",
    "account": {},
    "currency": "<string>",
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "completedAt": {},
    "bills": [
      {
        "billId": "<string>",
        "amount": 123,
        "fee": 123,
        "label": "<string>",
        "period": "<string>"
      }
    ],
    "selectedBill": {},
    "total": 123,
    "receiptUrl": "<string>",
    "operationId": "<string>",
    "error": {
      "code": "<string>",
      "message": "<string>"
    }
  },
  "meta": {
    "timestamp": "<string>"
  },
  "requestId": "<string>"
}

Overview

Returns the complete transaction object — the canonical view of a Bill Payment discovery or payment. Every other Bill Payment endpoint either returns this same object or returns an identifier that points at it. Because discovery and payment are asynchronous, this endpoint is where the real outcome appears. The 200 you received from discover or pay only confirmed that the request was accepted.

A transaction that belongs to another partner returns 404, not 403. The API never confirms that someone else’s transaction exists. The same applies across environments: a sandbox key cannot read a production transaction, and vice versa.

Path Parameters

string

required

The transaction identifier returned by Discover Bills or Pay a Bill.A 24-character lowercase hexadecimal string, for example 68b2f4c1a7d3e9f204c81a55.

Response

boolean

required

true when the transaction was found and returned.

object

required

The transaction object.

Show properties

string

required

The transaction identifier. Always present.

string

required

The idempotency reference you supplied when you started the discovery. This is the value Get Transaction by Reference looks up.

string

required

discovery while the transaction has only looked bills up, payment once you have submitted a payment against it.

string

required

One of PENDING, READY, PROCESSING, SUCCESS, FAILED, REFUNDED, UNKNOWN. See Status lifecycle.

string

required

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

object

required

The account the transaction is for, keyed by that partner’s identifier field: reference for ADE and SEAAL, contractNumber for SONELGAZ, aadlNumber for AADL, phoneNumber for Algérie Télécom.

string

required

Always DZD.

string

required

When the transaction was created, ISO 8601 UTC.

string

required

When the transaction last changed, ISO 8601 UTC.

string | null

required

When the transaction stopped working. null while it is still in progress. Branch on status, never on this field.

array

Present only when status is READY. The bills that are due and payable. An empty array means there is nothing to pay.

Show bill properties

string

required

The identifier to send to Pay a Bill.

number

required

What the partner is owed, in DZD, 2 decimals.

number

required

The OneClickDz service fee for paying this bill, in DZD, 2 decimals. Read it from the response — never recompute it.

string

A human-readable description, when the partner supplied one.

string

The billing period, when the partner supplied one.

object

Present once a bill has been selected for payment. Same shape as a bills[] entry, and it is the bill that was actually charged.

number

Present with selectedBill. amount + fee — the figure debited from your balance.

string

Present only when status is SUCCESS. The absolute URL of the receipt download.

string

Present only when status is SUCCESS. The partner’s proof-of-payment reference. Store it — it is what a customer dispute is settled with.

object

Present only when status is FAILED or REFUNDED.

Show properties

string

required

One of PAYMENT_DECLINED, PARTNER_UNAVAILABLE, INVALID_ACCOUNT, BILL_ALREADY_PAID.

string

required

A short explanation, safe to log. Do not parse it — branch on code.

object

required

Show properties

string

required

Response time, ISO 8601 UTC.

string

required

Correlation identifier, also sent as the X-Request-Id response header. Log it — it is the only thing support needs to trace a request.

Examples

curl https://billapi.oneclickdz.com/v3/bills/transactions/68b2f4c1a7d3e9f204c81a55 \
  -H "X-Access-Token: YOUR_API_KEY"

const transactionId = "68b2f4c1a7d3e9f204c81a55";

const response = await fetch(
  `https://billapi.oneclickdz.com/v3/bills/transactions/${transactionId}`,
  { 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.status);

import os
import requests

transaction_id = '68b2f4c1a7d3e9f204c81a55'

response = requests.get(
    f'https://billapi.oneclickdz.com/v3/bills/transactions/{transaction_id}',
    headers={'X-Access-Token': os.getenv('ONECLICKDZ_API_KEY')}
)

body = response.json()

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

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

<?php
$transactionId = '68b2f4c1a7d3e9f204c81a55';

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

Success Response

A completed payment:

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

A discovery that finished and found one payable bill:

{
  "success": true,
  "data": {
    "transactionId": "68b2f4c1a7d3e9f204c81a55",
    "ref": "disc-inv-2026-0042",
    "type": "discovery",
    "status": "READY",
    "partner": "ADE",
    "account": {
      "reference": "0123456789012345678901234"
    },
    "bills": [
      {
        "billId": "sbx_bill_68b2f4c1a7d3e9f204c81a55_0",
        "amount": 443.39,
        "fee": 30.00,
        "label": "Facture ADE"
      }
    ],
    "currency": "DZD",
    "createdAt": "2026-08-31T10:15:32.194Z",
    "updatedAt": "2026-08-31T10:15:33.008Z",
    "completedAt": "2026-08-31T10:15:33.008Z"
  },
  "meta": {
    "timestamp": "2026-08-31T10:15:34.120Z"
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

A payment that was declined and refunded in full:

{
  "success": true,
  "data": {
    "transactionId": "68b2f4c1a7d3e9f204c81a55",
    "ref": "disc-inv-2026-0042",
    "type": "payment",
    "status": "REFUNDED",
    "partner": "ADE",
    "account": {
      "reference": "0123456789012340000000005"
    },
    "selectedBill": {
      "billId": "sbx_bill_68b2f4c1a7d3e9f204c81a55_0",
      "amount": 550.00,
      "fee": 30.00,
      "label": "Facture ADE"
    },
    "total": 580.00,
    "currency": "DZD",
    "error": {
      "code": "PAYMENT_DECLINED",
      "message": "The payment was declined by the bank or partner portal."
    },
    "createdAt": "2026-08-31T10:15:32.194Z",
    "updatedAt": "2026-08-31T10:15:44.310Z",
    "completedAt": "2026-08-31T10:15:44.310Z"
  },
  "meta": {
    "timestamp": "2026-08-31T10:15:46.002Z"
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

Error Responses

401 — Missing access token

The X-Access-Token header was not sent.

{
  "success": false,
  "error": {
    "code": "MISSING_ACCESS_TOKEN",
    "message": "X-Access-Token header is required."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

What to do: send your API key in the X-Access-Token header on every request.

401 — Invalid access token

The key was rejected.

{
  "success": false,
  "error": {
    "code": "INVALID_ACCESS_TOKEN",
    "message": "The provided access token is invalid."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

What to do: check the key. Do not retry with the same value — this will not resolve on its own.

404 — Transaction not found

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

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

What to do: confirm the identifier, and confirm you are using the key for the environment the transaction was created in. A malformed identifier also answers 404.

503 — Authentication unavailable

We could not verify your key in time. This is not a verdict on your key.

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

What to do: wait for the number of seconds in the Retry-After response header, then retry the same request. Never present this to your customer as a credential problem.

503 — Service unavailable

The Bill Payment API is in planned maintenance. Every /v3 route answers this.

{
  "success": false,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "The service is temporarily unavailable. Please retry shortly."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

What to do: honour Retry-After and retry. Reads are safe to repeat.

500 — Internal error

Something failed on our side.

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred."
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

What to do: retry the read. If it persists, contact support with the requestId.

Status lifecycle

A transaction is created by discover, becomes payable, and then follows the payment through to a final state.

Status	Meaning	Final
`PENDING`	Accepted; discovery has not finished	No
`READY`	Discovery finished — read `bills[]`. An empty array means nothing is due	No
`PROCESSING`	Payment in flight	No
`SUCCESS`	Paid. `operationId` and `receiptUrl` are present	Yes
`FAILED`	Did not go through. No money moved	Yes
`REFUNDED`	Money moved and was returned in full	Yes
`UNKNOWN`	Outcome not yet confirmed; under review	Not yet

UNKNOWN is not a failure. Never refund your own customer and never retry the payment while a transaction is UNKNOWN — keep polling. It resolves to SUCCESS or REFUNDED.

Full polling strategy →

Fields by status

Only the fields marked below are present. Do not assume a field exists because you saw it in another status.

Field	`PENDING`	`READY`	`PROCESSING`	`SUCCESS`	`FAILED`	`REFUNDED`	`UNKNOWN`
`transactionId`, `ref`, `type`, `status`, `partner`, `account`, `currency`, `createdAt`, `updatedAt`	Yes	Yes	Yes	Yes	Yes	Yes	Yes
`completedAt`	`null`	Set	`null`	Set	Set	Set	Set
`bills`	—	Yes	—	—	—	—	—
`selectedBill`, `total`	—	—	Yes	Yes	Yes	Yes	Yes
`receiptUrl`, `operationId`	—	—	—	Yes	—	—	—
`error`	—	—	—	—	Yes	Yes	—

selectedBill and total appear from the moment a bill is selected for payment, so they are absent on a discovery that was never paid.

Best Practices

Branch on status

Treat status as the only source of truth for the outcome. Never infer it from completedAt or from the HTTP status of the original request.

Store the operationId

On SUCCESS, persist operationId and download the receipt. Together they are the proof a customer dispute needs.

Log every requestId

Keep requestId next to your own order identifier. It is the fastest route to an answer from support.

Poll, do not retry

A slow transaction is not a lost one. Poll this endpoint instead of resubmitting the discovery or the payment.

Discover Bills

Start a discovery

Pay a Bill

Pay a discovered bill

Get Transaction by Reference

Look up by your own ref

List Transactions

Filter and paginate history

Download Receipt

Get the proof of payment

Status Polling Guide

A production-grade poller

API Reference

Core

Account

Mobile Top-Ups

Internet Top-Ups

Gift Cards

Navio

Bill Payment

Get Transaction by ID

Overview

Path Parameters

Response

Examples

Success Response

Error Responses

Status lifecycle

Fields by status

Best Practices

Branch on status

Store the operationId

Log every requestId

Poll, do not retry

Discover Bills

Pay a Bill

Get Transaction by Reference

List Transactions

Download Receipt

Status Polling Guide

​Overview

​Path Parameters

​Response

​Examples

​Success Response

​Error Responses

​Status lifecycle

​Fields by status

​Best Practices

Branch on status

Store the operationId

Log every requestId

Poll, do not retry

​Related Endpoints

Discover Bills

Pay a Bill

Get Transaction by Reference

List Transactions

Download Receipt

Status Polling Guide

Overview

Path Parameters

Response

Examples

Success Response

Error Responses

Status lifecycle

Fields by status

Best Practices

Related Endpoints