Receipts and Reconciliation - OneClickDz Flexy API

Overview

A payment that reached SUCCESS leaves two pieces of evidence: operationId, the biller’s own reference for the transaction, and the receipt file. Together they settle any dispute a customer raises months later. This step covers downloading and storing both, and a daily routine that proves your ledger and ours agree.

What a success gives you

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

Field	Keep it because
`operationId`	It is the biller’s reference for this payment — the one a dispute is settled with
`receiptUrl`	It points at the receipt file. Download it; do not store the link
`total`	The exact figure debited from your balance
`selectedBill`	The bill that was actually paid, with its `amount` and `fee`
`completedAt`	When the payment settled

receiptUrl requires your X-Access-Token header. It is not a link you can email to a customer or embed in a page. Download the bytes and serve them from your own system.

Downloading the receipt

Fetch it in the same step that records the success, and take the file extension from the Content-Type header — a receipt is a PDF or an image depending on the biller.

# -J -O writes the file under the name the server suggests
curl https://billapi.oneclickdz.com/v3/bills/transactions/68b2f4c1a7d3e9f204c81a55/receipt \
  -H "X-Access-Token: YOUR_API_KEY" \
  --fail \
  --remote-header-name --remote-name

import { writeFile } from "node:fs/promises";

const BASE = "https://billapi.oneclickdz.com";
const KEY = process.env.ONECLICKDZ_API_KEY;

function extensionFor(contentType = "") {
  if (contentType.includes("pdf")) return "pdf";
  if (contentType.includes("png")) return "png";
  if (contentType.includes("jpeg")) return "jpg";
  return "bin";
}

async function downloadReceipt(transactionId) {
  const response = await fetch(
    `${BASE}/v3/bills/transactions/${transactionId}/receipt`,
    { headers: { "X-Access-Token": KEY } },
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`${error.error.code}: ${error.error.message}`);
  }

  const extension = extensionFor(response.headers.get("content-type"));
  const bytes = Buffer.from(await response.arrayBuffer());
  const path = `receipts/${transactionId}.${extension}`;

  await writeFile(path, bytes);

  return { path, bytes: bytes.length };
}

import os
import requests

BASE = 'https://billapi.oneclickdz.com'
KEY = os.getenv('ONECLICKDZ_API_KEY')


def extension_for(content_type=''):
    if 'pdf' in content_type:
        return 'pdf'
    if 'png' in content_type:
        return 'png'
    if 'jpeg' in content_type:
        return 'jpg'
    return 'bin'


def download_receipt(transaction_id):
    response = requests.get(
        f'{BASE}/v3/bills/transactions/{transaction_id}/receipt',
        headers={'X-Access-Token': KEY}
    )

    if response.status_code != 200:
        error = response.json()
        raise RuntimeError(f"{error['error']['code']}: {error['error']['message']}")

    extension = extension_for(response.headers.get('Content-Type', ''))
    path = f'receipts/{transaction_id}.{extension}'

    with open(path, 'wb') as handle:
        handle.write(response.content)

    return {'path': path, 'bytes': len(response.content)}

<?php
const BASE = 'https://billapi.oneclickdz.com';

function extensionFor(string $contentType): string
{
    if (str_contains($contentType, 'pdf'))  return 'pdf';
    if (str_contains($contentType, 'png'))  return 'png';
    if (str_contains($contentType, 'jpeg')) return 'jpg';
    return 'bin';
}

function downloadReceipt(string $transactionId): array
{
    $ch = curl_init(BASE . "/v3/bills/transactions/$transactionId/receipt");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'X-Access-Token: ' . getenv('ONECLICKDZ_API_KEY')
    ]);

    $bytes  = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    $type   = curl_getinfo($ch, CURLINFO_CONTENT_TYPE);
    curl_close($ch);

    if ($status !== 200) {
        $error = json_decode($bytes, true);
        throw new Exception($error['error']['code'] . ': ' . $error['error']['message']);
    }

    $path = "receipts/$transactionId." . extensionFor($type);
    file_put_contents($path, $bytes);

    return ['path' => $path, 'bytes' => strlen($bytes)];
}
?>

A receipt exists only for a SUCCESS transaction. Anything else — still in flight, FAILED, REFUNDED, or belonging to another partner — answers 404 NOT_FOUND in the ordinary JSON envelope.

Storing it

Download once, at settlement

Fetch the receipt in the same step that marks your order paid. Retrying later is fine, but do not leave it until a customer asks.

Store the bytes, not the URL

Put the file in your own object storage, keyed by your order identifier. The API URL needs your key and is useless to anyone else.

Store operationId alongside it

The receipt is the document; operationId is the reference. Keep both on the order row.

Serve it behind your own authentication

Your customer downloads it from you, not from us.

async function settle(order, transaction) {
  const receipt = await downloadReceipt(transaction.transactionId);

  await db.orders.update(order.id, {
    state: "PAID",
    operationId: transaction.operationId,
    total: transaction.total,
    amount: transaction.selectedBill.amount,
    fee: transaction.selectedBill.fee,
    completedAt: transaction.completedAt,
    receiptPath: receipt.path,
  });
}

Reconciling a day

GET /v3/bills/transactions with from and to gives you everything that happened in a window. Bound the window — an unbounded list grows with your business, and a bounded one cannot shift underneath you while you page.

curl -G https://billapi.oneclickdz.com/v3/bills/transactions \
  --data-urlencode "from=2026-08-30T00:00:00Z" \
  --data-urlencode "to=2026-08-30T23:59:59Z" \
  --data-urlencode "status=SUCCESS" \
  --data-urlencode "limit=100" \
  -H "X-Access-Token: YOUR_API_KEY"

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

  for (;;) {
    const url = new URL(`${BASE}/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": 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;
  }
}

async function reconcile(day) {
  const filters = {
    from: `${day}T00:00:00Z`,
    to: `${day}T23:59:59Z`,
  };

  let charged = 0;
  let returned = 0;
  const mismatches = [];

  for await (const transaction of eachTransaction(filters)) {
    const order = await db.orders.findByRef(transaction.ref);

    if (!order) {
      mismatches.push({ reason: "unknownToUs", transaction });
      continue;
    }

    if (transaction.status === "SUCCESS") {
      charged += transaction.total;
      if (order.state !== "PAID") {
        mismatches.push({ reason: "missedSuccess", transaction });
      }
    }

    if (transaction.status === "REFUNDED") {
      returned += transaction.total;
      if (order.state === "PAID") {
        mismatches.push({ reason: "refundMarkedPaid", transaction });
      }
    }

    if (["PENDING", "PROCESSING", "UNKNOWN"].includes(transaction.status)) {
      mismatches.push({ reason: "stillOpen", transaction });
    }
  }

  return { day, charged, returned, net: charged - returned, mismatches };
}

def each_transaction(filters):
    offset, limit = 0, 100

    while True:
        response = requests.get(
            f'{BASE}/v3/bills/transactions',
            headers={'X-Access-Token': KEY},
            params={**filters, 'limit': limit, 'offset': offset}
        )

        body = response.json()
        if not body['success']:
            raise RuntimeError(body['error']['code'])

        for transaction in body['data']:
            yield transaction

        offset += len(body['data'])
        if offset >= body['meta']['total'] or not body['data']:
            return


def reconcile(day):
    filters = {'from': f'{day}T00:00:00Z', 'to': f'{day}T23:59:59Z'}

    charged = returned = 0.0
    mismatches = []

    for transaction in each_transaction(filters):
        order = db.orders.find_by_ref(transaction['ref'])

        if not order:
            mismatches.append(('unknownToUs', transaction))
            continue

        if transaction['status'] == 'SUCCESS':
            charged += transaction['total']
            if order['state'] != 'PAID':
                mismatches.append(('missedSuccess', transaction))

        if transaction['status'] == 'REFUNDED':
            returned += transaction['total']
            if order['state'] == 'PAID':
                mismatches.append(('refundMarkedPaid', transaction))

        if transaction['status'] in ('PENDING', 'PROCESSING', 'UNKNOWN'):
            mismatches.append(('stillOpen', transaction))

    return {
        'day': day,
        'charged': charged,
        'returned': returned,
        'net': charged - returned,
        'mismatches': mismatches
    }

<?php
function eachTransaction(array $filters): Generator
{
    $offset = 0;
    $limit  = 100;

    while (true) {
        $query = http_build_query($filters + ['limit' => $limit, 'offset' => $offset]);

        $ch = curl_init(BASE . "/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']);
        }

        foreach ($body['data'] as $transaction) {
            yield $transaction;
        }

        $offset += count($body['data']);
        if ($offset >= $body['meta']['total'] || count($body['data']) === 0) {
            return;
        }
    }
}

function reconcile(string $day): array
{
    $filters = ['from' => "{$day}T00:00:00Z", 'to' => "{$day}T23:59:59Z"];

    $charged = 0.0;
    $returned = 0.0;
    $mismatches = [];

    foreach (eachTransaction($filters) as $transaction) {
        $order = $db->orders->findByRef($transaction['ref']);

        if (!$order) {
            $mismatches[] = ['unknownToUs', $transaction];
            continue;
        }

        if ($transaction['status'] === 'SUCCESS') {
            $charged += $transaction['total'];
            if ($order['state'] !== 'PAID') {
                $mismatches[] = ['missedSuccess', $transaction];
            }
        }

        if ($transaction['status'] === 'REFUNDED') {
            $returned += $transaction['total'];
            if ($order['state'] === 'PAID') {
                $mismatches[] = ['refundMarkedPaid', $transaction];
            }
        }

        if (in_array($transaction['status'], ['PENDING', 'PROCESSING', 'UNKNOWN'], true)) {
            $mismatches[] = ['stillOpen', $transaction];
        }
    }

    return [
        'day'        => $day,
        'charged'    => $charged,
        'returned'   => $returned,
        'net'        => $charged - $returned,
        'mismatches' => $mismatches
    ];
}
?>

What each mismatch means

Finding	Meaning	Action
`missedSuccess`	We charged you; your order is not marked paid	Settle it now, download the receipt, notify the customer
`refundMarkedPaid`	The money came back; your order still says paid	Reverse it on your side and release the customer’s funds
`stillOpen`	A transaction from that day has not reached a final state	Keep it in reconciliation until it does. Never close it as failed
`unknownToUs`	A transaction whose `ref` matches no order of yours	Investigate — usually a discovery that was never paid, or a lost write

Reconcile on SUCCESS and REFUNDED only. A FAILED transaction never moved money, and a PENDING or READY discovery never charged anything.

A daily routine

Run once a day, for yesterday

Bound the window with from and to. Yesterday is complete; today is still moving.

Match on ref

Your ref is the join key between our transactions and your orders. That is what it is for.

Sum SUCCESS and REFUNDED separately

Net movement is SUCCESS totals minus REFUNDED totals. Both belong in your ledger.

Carry open transactions forward

Anything still PENDING, PROCESSING or UNKNOWN stays on the list until it resolves.

Alert on any mismatch

A reconciliation that finds nothing should be silent. One that finds something should page someone.

Best practices

Store both proofs

operationId and the receipt file. One without the other is half an answer to a dispute.

Reconcile daily, not monthly

A one-day window is small enough to investigate by hand. A month is not.

Never close an open transaction

UNKNOWN and PROCESSING resolve on their own. Carry them forward instead of writing them off.

Serve receipts yourself

Behind your own authentication, from your own storage. Never share the API URL.

Next step

Step 6: Sandbox testing

Reproduce every outcome on demand, then switch to production with confidence

Download Receipt

The endpoint reference

List Transactions

Filters, paging and meta.total

Status Polling

Getting to a final state

Get Transaction by ID

Where operationId appears

​Overview

​What a success gives you

​Downloading the receipt

​Storing it

​Reconciling a day

​What each mismatch means

​A daily routine

​Best practices

Store both proofs

Reconcile daily, not monthly

Never close an open transaction

Serve receipts yourself

​Next step

Step 6: Sandbox testing

​Related pages

Download Receipt

List Transactions

Status Polling

Get Transaction by ID

Overview

What a success gives you

Downloading the receipt

Storing it

Reconciling a day

What each mismatch means

A daily routine

Best practices

Next step

Related pages