> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneclickdz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Transaction by Reference

> Look a transaction up by the ref you supplied

## 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](/en/api-reference/bill-payment/check-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.

<Note>
  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.
</Note>

## Query Parameters

<ParamField query="ref" type="string" required>
  The reference you supplied when you created the discovery. Maximum 100 characters.
</ParamField>

<ParamField query="partner" type="string">
  Optional. One of `ADE`, `SONELGAZ`, `SEAAL`, `AADL`, `Algérie Télécom`. Narrows the lookup to that biller.
</ParamField>

## Response

Identical to [Get Transaction by ID](/en/api-reference/bill-payment/check-by-id#response) — 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.

<ResponseField name="success" type="boolean" required>
  `true` when a transaction was found.
</ResponseField>

<ResponseField name="data" type="object" required>
  The transaction object. [Full field reference →](/en/api-reference/bill-payment/check-by-id#response)
</ResponseField>

<ResponseField name="meta" type="object" required>
  <Expandable title="properties">
    <ResponseField name="timestamp" type="string" required>
      Response time, ISO 8601 UTC.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="requestId" type="string" required>
  Correlation identifier, also sent as the `X-Request-Id` response header.
</ResponseField>

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```javascript Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  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 PHP theme={null}
  <?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'];
  ?>
  ```
</CodeGroup>

### Success Response

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="400 — Validation error">
    **`ref` was missing, too long, or `partner` was not a known value.**

    ```json theme={null}
    {
      "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.
  </Accordion>

  <Accordion title="401 — Missing or invalid access token">
    **The key was absent or rejected.**

    ```json theme={null}
    {
      "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](/en/api-reference/bill-payment/validate-key).
  </Accordion>

  <Accordion title="404 — Transaction not found">
    **No transaction with that `ref` belongs to your account in this environment.**

    ```json theme={null}
    {
      "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.
  </Accordion>

  <Accordion title="503 — Authentication or service unavailable">
    **We could not verify your key in time, or the API is in planned maintenance.**

    ```json theme={null}
    {
      "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.
  </Accordion>
</AccordionGroup>

## 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.

```javascript theme={null}
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}`);
}
```

<Warning>
  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`.
</Warning>

## Best Practices

<CardGroup cols={2}>
  <Card title="Look up, do not resend" icon="magnifying-glass">
    Every timeout and every `DUPLICATED_REF` is answered here, not by a second write.
  </Card>

  <Card title="Pass the partner" icon="building-columns">
    It costs nothing and removes any ambiguity when the same `ref` string exists for two billers.
  </Card>

  <Card title="Store the ref with your order" icon="database">
    A `ref` you cannot reconstruct is a transaction you cannot recover.
  </Card>

  <Card title="Poll by ID once you have it" icon="id-card">
    Use this endpoint to recover, then poll by `transactionId` — one fewer parameter to get wrong.
  </Card>
</CardGroup>

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Get Transaction by ID" icon="id-card" href="/en/api-reference/bill-payment/check-by-id">
    The full transaction object
  </Card>

  <Card title="List Transactions" icon="list" href="/en/api-reference/bill-payment/list-transactions">
    Filter and paginate history
  </Card>

  <Card title="Discover Bills" icon="magnifying-glass-dollar" href="/en/api-reference/bill-payment/discover-bills">
    Where a `ref` is created
  </Card>

  <Card title="Status Polling" icon="arrows-rotate" href="/en/bill-payment-guides/4-status-polling">
    A production-grade poller
  </Card>
</CardGroup>