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

# Obtenir une Transaction par ID

> Lire l'état complet d'une découverte ou d'un paiement de facture

## Vue d'Ensemble

Retourne l'objet transaction complet — la vue canonique d'une découverte ou d'un paiement Bill Payment. Tous les autres endpoints Bill Payment retournent soit ce même objet, soit un identifiant qui pointe vers lui.

Parce que la découverte et le paiement sont asynchrones, c'est sur cet endpoint qu'apparaît le résultat réel. Le `200` que vous avez reçu de `discover` ou de `pay` confirmait seulement que la requête avait été acceptée.

<Note>
  Une transaction qui appartient à un autre partenaire retourne `404`, pas `403`. L'API ne confirme jamais l'existence de la transaction de quelqu'un d'autre. Il en va de même entre environnements : une clé sandbox ne peut pas lire une transaction de production, et inversement.
</Note>

## Paramètres de Chemin

<ParamField path="transactionId" type="string" required>
  L'identifiant de transaction retourné par [Découvrir les Factures](/fr/api-reference/bill-payment/discover-bills) ou [Payer une Facture](/fr/api-reference/bill-payment/pay-bill).

  Une chaîne hexadécimale minuscule de 24 caractères, par exemple `68b2f4c1a7d3e9f204c81a55`.
</ParamField>

## Réponse

<ResponseField name="success" type="boolean" required>
  `true` lorsque la transaction a été trouvée et retournée.
</ResponseField>

<ResponseField name="data" type="object" required>
  L'objet transaction.

  <Expandable title="properties">
    <ResponseField name="transactionId" type="string" required>
      L'identifiant de la transaction. Toujours présent.
    </ResponseField>

    <ResponseField name="ref" type="string" required>
      La référence d'idempotence que vous avez fournie au démarrage de la découverte. C'est la valeur que recherche [Obtenir une Transaction par Référence](/fr/api-reference/bill-payment/check-by-ref).
    </ResponseField>

    <ResponseField name="type" type="string" required>
      `discovery` tant que la transaction n'a fait que rechercher des factures, `payment` une fois que vous avez soumis un paiement contre elle.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      L'une des valeurs `PENDING`, `READY`, `PROCESSING`, `SUCCESS`, `FAILED`, `REFUNDED`, `UNKNOWN`. Voir [Cycle de vie du statut](#status-lifecycle).
    </ResponseField>

    <ResponseField name="partner" type="string" required>
      L'une des valeurs `ADE`, `SONELGAZ`, `SEAAL`, `AADL`, `Algérie Télécom`.
    </ResponseField>

    <ResponseField name="account" type="object" required>
      Le compte concerné par la transaction, indexé par le champ identifiant de ce partenaire : `reference` pour ADE et SEAAL, `contractNumber` pour SONELGAZ, `aadlNumber` pour AADL, `phoneNumber` pour Algérie Télécom.
    </ResponseField>

    <ResponseField name="currency" type="string" required>
      Toujours `DZD`.
    </ResponseField>

    <ResponseField name="createdAt" type="string" required>
      Date de création de la transaction, ISO 8601 UTC.
    </ResponseField>

    <ResponseField name="updatedAt" type="string" required>
      Date du dernier changement de la transaction, ISO 8601 UTC.
    </ResponseField>

    <ResponseField name="completedAt" type="string | null" required>
      Date à laquelle la transaction a cessé de travailler. `null` tant qu'elle est encore en cours. Branchez sur `status`, jamais sur ce champ.
    </ResponseField>

    <ResponseField name="bills" type="array">
      Présent **uniquement lorsque `status` vaut `READY`**. Les factures dues et payables. Un tableau vide signifie qu'il n'y a rien à payer.

      <Expandable title="bill properties">
        <ResponseField name="billId" type="string" required>
          L'identifiant à envoyer à [Payer une Facture](/fr/api-reference/bill-payment/pay-bill).
        </ResponseField>

        <ResponseField name="amount" type="number" required>
          Ce qui est dû au partenaire, en DZD, 2 décimales.
        </ResponseField>

        <ResponseField name="fee" type="number" required>
          Les frais de service OneClickDz pour payer cette facture, en DZD, 2 décimales. Lisez-les depuis la réponse — ne les recalculez jamais.
        </ResponseField>

        <ResponseField name="label" type="string">
          Une description lisible par un humain, lorsque le partenaire en a fourni une.
        </ResponseField>

        <ResponseField name="period" type="string">
          La période de facturation, lorsque le partenaire en a fourni une.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="selectedBill" type="object">
      Présent une fois qu'une facture a été sélectionnée pour paiement. Même forme qu'une entrée de `bills[]`, et c'est la facture qui a réellement été débitée.
    </ResponseField>

    <ResponseField name="total" type="number">
      Présent avec `selectedBill`. `amount + fee` — le montant débité de votre solde.
    </ResponseField>

    <ResponseField name="receiptUrl" type="string">
      Présent **uniquement lorsque `status` vaut `SUCCESS`**. L'URL absolue du [téléchargement du reçu](/fr/api-reference/bill-payment/get-receipt).
    </ResponseField>

    <ResponseField name="operationId" type="string">
      Présent **uniquement lorsque `status` vaut `SUCCESS`**. La référence de preuve de paiement du partenaire. Stockez-la — c'est avec elle qu'un litige client se règle.
    </ResponseField>

    <ResponseField name="error" type="object">
      Présent **uniquement lorsque `status` vaut `FAILED` ou `REFUNDED`**.

      <Expandable title="properties">
        <ResponseField name="code" type="string" required>
          L'une des valeurs `PAYMENT_DECLINED`, `PARTNER_UNAVAILABLE`, `INVALID_ACCOUNT`, `BILL_ALREADY_PAID`.
        </ResponseField>

        <ResponseField name="message" type="string" required>
          Une courte explication, sans risque à journaliser. Ne l'analysez pas — branchez sur `code`.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object" required>
  <Expandable title="properties">
    <ResponseField name="timestamp" type="string" required>
      Heure de la réponse, ISO 8601 UTC.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="requestId" type="string" required>
  Identifiant de corrélation, également envoyé dans l'en-tête de réponse `X-Request-Id`. Journalisez-le — c'est la seule chose dont le support a besoin pour tracer une requête.
</ResponseField>

## Exemples

<CodeGroup>
  ```bash cURL theme={null}
  curl https://billapi.oneclickdz.com/v3/bills/transactions/68b2f4c1a7d3e9f204c81a55 \
    -H "X-Access-Token: YOUR_API_KEY"
  ```

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

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

### Réponse de Succès

Un paiement terminé :

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

Une découverte terminée qui a trouvé une facture payable :

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

Un paiement refusé et remboursé intégralement :

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

## Réponses d'Erreur

<AccordionGroup>
  <Accordion title="401 — Jeton d'accès manquant">
    **L'en-tête `X-Access-Token` n'a pas été envoyé.**

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

    **Que faire :** envoyez votre clé API dans l'en-tête `X-Access-Token` à chaque requête.
  </Accordion>

  <Accordion title="401 — Jeton d'accès invalide">
    **La clé a été rejetée.**

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

    **Que faire :** vérifiez la clé. Ne réessayez pas avec la même valeur — cela ne se résoudra pas tout seul.
  </Accordion>

  <Accordion title="404 — Transaction introuvable">
    **Aucune transaction portant cet identifiant n'appartient à votre compte dans cet environnement.**

    ```json theme={null}
    {
      "success": false,
      "error": {
        "code": "NOT_FOUND",
        "message": "Transaction not found."
      },
      "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
    }
    ```

    **Que faire :** confirmez l'identifiant, et confirmez que vous utilisez la clé de l'environnement dans lequel la transaction a été créée. Un identifiant malformé répond également `404`.
  </Accordion>

  <Accordion title="503 — Authentification indisponible">
    **Nous n'avons pas pu vérifier votre clé à temps. Ce n'est pas un verdict sur votre clé.**

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

    **Que faire :** attendez le nombre de secondes indiqué dans l'en-tête de réponse `Retry-After`, puis réessayez la même requête. Ne présentez jamais ceci à votre client comme un problème d'identifiants.
  </Accordion>

  <Accordion title="503 — Service indisponible">
    **L'API Bill Payment est en maintenance planifiée. Chaque route `/v3` répond ceci.**

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

    **Que faire :** respectez `Retry-After` et réessayez. Les lectures peuvent être répétées sans risque.
  </Accordion>

  <Accordion title="500 — Erreur interne">
    **Quelque chose a échoué de notre côté.**

    ```json theme={null}
    {
      "success": false,
      "error": {
        "code": "INTERNAL_ERROR",
        "message": "An unexpected error occurred."
      },
      "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
    }
    ```

    **Que faire :** réessayez la lecture. Si le problème persiste, contactez le support avec le `requestId`.
  </Accordion>
</AccordionGroup>

## Cycle de vie du statut

Une transaction est créée par `discover`, devient payable, puis suit le paiement jusqu'à un état final.

| Statut       | Signification                                                                     | Final      |
| ------------ | --------------------------------------------------------------------------------- | ---------- |
| `PENDING`    | Acceptée ; la découverte n'est pas terminée                                       | Non        |
| `READY`      | Découverte terminée — lisez `bills[]`. Un tableau vide signifie que rien n'est dû | Non        |
| `PROCESSING` | Paiement en vol                                                                   | Non        |
| `SUCCESS`    | Payée. `operationId` et `receiptUrl` sont présents                                | Oui        |
| `FAILED`     | N'a pas abouti. Aucun argent n'a bougé                                            | Oui        |
| `REFUNDED`   | L'argent a bougé et a été restitué intégralement                                  | Oui        |
| `UNKNOWN`    | Résultat pas encore confirmé ; en cours d'examen                                  | Pas encore |

<Warning>
  `UNKNOWN` n'est pas un échec. Ne remboursez jamais votre propre client et ne réessayez jamais le paiement tant qu'une transaction est `UNKNOWN` — continuez à interroger. Elle se résout en `SUCCESS` ou `REFUNDED`.
</Warning>

[Stratégie d'interrogation complète →](/fr/bill-payment-guides/4-status-polling)

## Champs par statut

Seuls les champs marqués ci-dessous sont présents. Ne supposez pas qu'un champ existe parce que vous l'avez vu dans un autre statut.

| Champ                                                                                                | `PENDING` | `READY` | `PROCESSING` | `SUCCESS` | `FAILED` | `REFUNDED` | `UNKNOWN` |
| ---------------------------------------------------------------------------------------------------- | --------- | ------- | ------------ | --------- | -------- | ---------- | --------- |
| `transactionId`, `ref`, `type`, `status`, `partner`, `account`, `currency`, `createdAt`, `updatedAt` | Oui       | Oui     | Oui          | Oui       | Oui      | Oui        | Oui       |
| `completedAt`                                                                                        | `null`    | Défini  | `null`       | Défini    | Défini   | Défini     | Défini    |
| `bills`                                                                                              | —         | Oui     | —            | —         | —        | —          | —         |
| `selectedBill`, `total`                                                                              | —         | —       | Oui          | Oui       | Oui      | Oui        | Oui       |
| `receiptUrl`, `operationId`                                                                          | —         | —       | —            | Oui       | —        | —          | —         |
| `error`                                                                                              | —         | —       | —            | —         | Oui      | Oui        | —         |

`selectedBill` et `total` apparaissent dès le moment où une facture est sélectionnée pour paiement, ils sont donc absents d'une découverte qui n'a jamais été payée.

## Bonnes Pratiques

<CardGroup cols={2}>
  <Card title="Branchez sur status" icon="code-branch">
    Traitez `status` comme la seule source de vérité pour le résultat. Ne le déduisez jamais de `completedAt` ni du statut HTTP de la requête d'origine.
  </Card>

  <Card title="Stockez l'operationId" icon="receipt">
    Sur `SUCCESS`, persistez `operationId` et téléchargez le reçu. Ensemble, ils constituent la preuve dont un litige client a besoin.
  </Card>

  <Card title="Journalisez chaque requestId" icon="fingerprint">
    Conservez `requestId` à côté de votre propre identifiant de commande. C'est la voie la plus rapide vers une réponse du support.
  </Card>

  <Card title="Interrogez, ne réessayez pas" icon="arrows-rotate">
    Une transaction lente n'est pas une transaction perdue. Interrogez cet endpoint au lieu de resoumettre la découverte ou le paiement.
  </Card>
</CardGroup>

## Endpoints Associés

<CardGroup cols={3}>
  <Card title="Découvrir les Factures" icon="magnifying-glass-dollar" href="/fr/api-reference/bill-payment/discover-bills">
    Démarrer une découverte
  </Card>

  <Card title="Payer une Facture" icon="money-bill-transfer" href="/fr/api-reference/bill-payment/pay-bill">
    Payer une facture découverte
  </Card>

  <Card title="Obtenir une Transaction par Référence" icon="tag" href="/fr/api-reference/bill-payment/check-by-ref">
    Rechercher par votre propre `ref`
  </Card>

  <Card title="Lister les Transactions" icon="list" href="/fr/api-reference/bill-payment/list-transactions">
    Filtrer et paginer l'historique
  </Card>

  <Card title="Télécharger le Reçu" icon="file-arrow-down" href="/fr/api-reference/bill-payment/get-receipt">
    Obtenir la preuve de paiement
  </Card>

  <Card title="Guide d'Interrogation du Statut" icon="arrows-rotate" href="/fr/bill-payment-guides/4-status-polling">
    Un interrogateur prêt pour la production
  </Card>
</CardGroup>