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

# Vue d'ensemble de l'intégration Paiement de Factures

> Découvrez et payez les factures algériennes de services publics et de télécommunications

## Introduction

Le Paiement de Factures vous permet de payer les factures algériennes de services publics et de télécommunications pour le compte de vos propres clients. Vous demandez à un facturier ce qu'un compte doit, vous payez l'une des factures renvoyées, vous la suivez jusqu'à un état final, et vous conservez le reçu.

Tout le produit tient en cinq appels. Cette page est la carte ; chaque étape ci-dessous renvoie vers un guide avec du code fonctionnel en cURL, Node.js, Python et PHP.

<Note>
  Le Paiement de Factures est hébergé sur **`https://billapi.oneclickdz.com`** — une URL de base différente de celle du reste de la plateforme. L'en-tête d'authentification est le même que celui que vous utilisez déjà : `X-Access-Token`.
</Note>

## Comment ça fonctionne

```mermaid theme={null}
sequenceDiagram
    participant Customer
    participant YourApp
    participant API as Bill Payment API

    YourApp->>API: 1. GET /v3/partners
    API-->>YourApp: Availability map

    Customer->>YourApp: Enters account number
    YourApp->>API: 2. POST /v3/bills/discover
    API-->>YourApp: transactionId (PENDING)

    loop Until READY
        YourApp->>API: GET /v3/bills/transactions/{id}
        API-->>YourApp: Status
    end

    API-->>YourApp: READY + bills[]
    YourApp->>Customer: Shows amount + fee
    Customer->>YourApp: Confirms

    YourApp->>API: 3. POST /v3/bills/pay
    API-->>YourApp: PROCESSING

    loop 4. Until final
        YourApp->>API: GET /v3/bills/transactions/{id}
        API-->>YourApp: Status
    end

    API-->>YourApp: SUCCESS + operationId
    YourApp->>API: 5. GET .../receipt
    API-->>YourApp: Receipt file
    YourApp->>Customer: Confirmation + receipt
```

## Les cinq étapes

<Steps>
  <Step title="Vérifier que le facturier est disponible">
    Lisez la carte de disponibilité et masquez tout facturier `UNAVAILABLE` avant que votre client ne commence à remplir un formulaire.

    → [Étape 1 : Partenaires et comptes](/fr/bill-payment-guides/1-partners-and-accounts)
  </Step>

  <Step title="Découvrir ce qui est dû">
    Envoyez le partenaire, l'identifiant du compte et votre propre `ref`. Vous recevez un `transactionId` en retour ; les factures arrivent sur cette transaction un instant plus tard.

    → [Étape 2 : Découverte des factures](/fr/bill-payment-guides/2-discovering-bills)
  </Step>

  <Step title="Payer une facture">
    Choisissez un `billId` dans `bills[]`, montrez `amount + fee` à votre client, et soumettez le paiement avec un nouveau `ref`.

    → [Étape 3 : Paiement des factures](/fr/bill-payment-guides/3-paying-bills)
  </Step>

  <Step title="Interroger jusqu'à ce que le statut soit final">
    `SUCCESS`, `FAILED` ou `REFUNDED`. `UNKNOWN` signifie qu'il faut continuer à interroger — ne remboursez jamais votre client et ne réessayez jamais le paiement tant qu'il dure.

    → [Étape 4 : Suivi du statut](/fr/bill-payment-guides/4-status-polling)
  </Step>

  <Step title="Conserver le reçu et rapprocher">
    Téléchargez le reçu, stockez-le avec l'`operationId`, et effectuez un rapprochement quotidien avec votre propre registre.

    → [Étape 5 : Reçus et rapprochement](/fr/bill-payment-guides/5-receipts-and-reconciliation)
  </Step>
</Steps>

## Ce que vous devez savoir

### Tout est asynchrone

`POST /v3/bills/discover` et `POST /v3/bills/pay` répondent tous les deux `200` immédiatement. Ce `200` signifie **accepté**, pas **terminé**.

<Warning>
  Un `200` de `pay` ne signifie pas que la facture a été payée. Le résultat réel n'apparaît jamais ailleurs que dans le `status` de la transaction. Concevez votre intégration autour du polling dès la première ligne de code — l'ajouter après coup, c'est ainsi que des clients se retrouvent débités deux fois.
</Warning>

### Les facturiers et leurs identifiants

Cinq facturiers, chacun avec un seul champ d'identifiant. Envoyez le champ qui correspond au partenaire ; l'API renvoie ce même champ sur chaque transaction.

| Partenaire        | De quoi il s'agit          | Identifiant      |
| ----------------- | -------------------------- | ---------------- |
| `ADE`             | Eau                        | `reference`      |
| `SONELGAZ`        | Électricité et gaz         | `contractNumber` |
| `SEAAL`           | Eau — Alger et Tipaza      | `reference`      |
| `AADL`            | Échéances de logement      | `aadlNumber`     |
| `Algérie Télécom` | Téléphone fixe et internet | `phoneNumber`    |

`SEAAL` et `AADL` sont actuellement `UNAVAILABLE` en sandbox comme en production. Lisez la carte de disponibilité plutôt que de coder cela en dur.

→ [Règles d'identifiant, formats et exemples](/fr/bill-payment-guides/1-partners-and-accounts)

### Les sept statuts

| Statut       | Signification                                    | Final      |
| ------------ | ------------------------------------------------ | ---------- |
| `PENDING`    | Accepté ; la découverte n'est pas terminée       | Non        |
| `READY`      | Découverte terminée — lisez `bills[]`            | Non        |
| `PROCESSING` | Paiement en cours d'exécution                    | Non        |
| `SUCCESS`    | Payée ; `operationId` et `receiptUrl` 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 |

→ [La machine à états complète et un poller de qualité production](/fr/bill-payment-guides/4-status-polling)

### Les frais et le plancher de 200 DZD

Chaque facture porte ses propres champs monétaires :

* `amount` — ce qui est dû au facturier, en DZD.
* `fee` — les frais de service OneClickDz : un pourcentage du montant, borné entre un minimum et un maximum, **défini par facturier** :

  | Facturier         | Pourcentage | Minimum | Maximum |
  | ----------------- | ----------- | ------- | ------- |
  | `ADE`             | 0,5 %       | 30 DZD  | 60 DZD  |
  | `SONELGAZ`        | 0,5 %       | 30 DZD  | 60 DZD  |
  | `Algérie Télécom` | 0,5 %       | 10 DZD  | 50 DZD  |

  En pratique, la plupart des factures paient le minimum : 0,5 % ne dépasse 30 DZD qu'au-delà d'une facture de 6 000 DZD. Ces valeurs relèvent de la configuration et peuvent être ajustées : lisez donc `fee` depuis la réponse plutôt que de le recalculer.
* `total` — `amount + fee`, le montant débité de votre solde.

Les factures inférieures à **200 DZD** sont filtrées pendant la découverte et n'apparaissent jamais dans `bills[]`. Une transaction `READY` avec un `bills[]` vide signifie donc soit « rien n'est dû », soit « tout ce qui est dû est sous le plancher » — l'API ne fait pas la distinction. Dites à votre client « aucune facture n'est payable pour le moment », et non « vous ne devez rien ».

### Votre référence est votre filet de sécurité

`ref` est obligatoire sur `discover` comme sur `pay`, fait au maximum 100 caractères, et doit être unique parmi vos transactions actives pour ce facturier. En réutiliser un renvoie `403 DUPLICATED_REF`.

Dérivez-le de quelque chose que vous stockez déjà, afin qu'après un timeout vous puissiez toujours demander [ce qu'est devenu ce `ref`](/fr/api-reference/bill-payment/check-by-ref) au lieu de renvoyer la requête.

<Note>
  Utilisez un `ref` **différent** pour la découverte et pour le paiement. La transaction conserve son `ref` de découverte d'origine, et c'est celui-là que `by-ref` recherche.
</Note>

### Sandbox

Le sandbox utilise le même hôte, les mêmes routes, la même enveloppe et le même cycle de vie. La seule différence est qu'une clé sandbox n'atteint jamais un facturier et ne déplace jamais d'argent. Le résultat que vous obtenez est déterminé par l'identifiant de compte que vous envoyez, vous pouvez donc reproduire un refus, un remboursement et un paiement non confirmé à la demande.

Chaque clé est liée à un seul environnement. Appelez [Valider la clé API](/fr/api-reference/bill-payment/validate-key) et lisez `key.type` pour savoir laquelle vous détenez.

→ [Tous les scénarios sandbox, et une checklist de mise en production](/fr/bill-payment-guides/6-sandbox-testing)

## Points clés

<AccordionGroup>
  <Accordion title="200 est un accusé de réception, pas un résultat" icon="triangle-exclamation">
    Les deux endpoints d'écriture acceptent le travail et répondent immédiatement. Le résultat se trouve dans le `status` de la transaction.

    → [Étape 4 : Suivi du statut](/fr/bill-payment-guides/4-status-polling)
  </Accordion>

  <Accordion title="Ne réessayez jamais un paiement sur UNKNOWN" icon="ban">
    `UNKNOWN` signifie que le résultat n'est pas encore confirmé. Continuez à interroger — il se résout en `SUCCESS` ou `REFUNDED`. Rembourser votre propre client ou renvoyer le paiement tant qu'il dure, c'est ainsi que l'argent est perdu deux fois.

    → [Gérer UNKNOWN](/fr/bill-payment-guides/4-status-polling)
  </Accordion>

  <Accordion title="Consultez, ne renvoyez pas" icon="magnifying-glass">
    Chaque timeout, chaque `DUPLICATED_REF`, chaque échec inexpliqué se règle en consultant le `ref`. Une seconde écriture n'est jamais la bonne façon de récupérer.

    → [Étape 2 : Découverte des factures](/fr/bill-payment-guides/2-discovering-bills)
  </Accordion>

  <Accordion title="Lisez fee et total depuis la réponse" icon="calculator">
    Les frais sont configurés par partenaire et peuvent changer. Facturez à votre client le `total` renvoyé par l'API, jamais un montant que vous avez calculé.

    → [Étape 3 : Paiement des factures](/fr/bill-payment-guides/3-paying-bills)
  </Accordion>

  <Accordion title="Une transaction qui n'est pas la vôtre est un 404" icon="shield-halved">
    Une transaction qui ne vous appartient pas — ou qui appartient à l'autre environnement — renvoie `404`, jamais `403`. L'API ne confirme jamais l'existence de la transaction de quelqu'un d'autre.

    → [Obtenir une transaction par ID](/fr/api-reference/bill-payment/check-by-id)
  </Accordion>
</AccordionGroup>

## Référence API

<CardGroup cols={2}>
  <Card title="Valider la clé API" icon="key" href="/fr/api-reference/bill-payment/validate-key">
    GET /v3/validate
  </Card>

  <Card title="Lister les partenaires" icon="building-columns" href="/fr/api-reference/bill-payment/list-partners">
    GET /v3/partners
  </Card>

  <Card title="Découvrir les factures" icon="magnifying-glass-dollar" href="/fr/api-reference/bill-payment/discover-bills">
    POST /v3/bills/discover
  </Card>

  <Card title="Payer une facture" icon="money-bill-transfer" href="/fr/api-reference/bill-payment/pay-bill">
    POST /v3/bills/pay
  </Card>

  <Card title="Obtenir une transaction par ID" icon="id-card" href="/fr/api-reference/bill-payment/check-by-id">
    GET /v3/bills/transactions/id
  </Card>

  <Card title="Obtenir une transaction par référence" icon="tag" href="/fr/api-reference/bill-payment/check-by-ref">
    GET /v3/bills/transactions/by-ref
  </Card>

  <Card title="Lister les transactions" icon="list" href="/fr/api-reference/bill-payment/list-transactions">
    GET /v3/bills/transactions
  </Card>

  <Card title="Télécharger le reçu" icon="file-arrow-down" href="/fr/api-reference/bill-payment/get-receipt">
    GET /v3/bills/transactions/id/receipt
  </Card>
</CardGroup>

## Démarrer l'intégration

<Card title="Commencer par l'Étape 1 : Partenaires et comptes" icon="play" href="/fr/bill-payment-guides/1-partners-and-accounts" color="#0D9373">
  Vérifiez la disponibilité et apprenez les règles d'identifiant de chaque facturier
</Card>

## Ressources supplémentaires

<CardGroup cols={2}>
  <Card title="Authentification" icon="key" href="/fr/authentication">
    Clés, en-têtes et environnements
  </Card>

  <Card title="Format de réponse" icon="code" href="/fr/api-reference/response-format">
    L'enveloppe renvoyée par chaque endpoint
  </Card>

  <Card title="Gestion des erreurs" icon="triangle-exclamation" href="/fr/api-reference/error-handling">
    Chaque code d'erreur et ce qu'il faut faire
  </Card>

  <Card title="Stratégies de polling" icon="chart-line" href="/fr/polling-strategies">
    Intervalles, backoff et plafonds
  </Card>

  <Card title="Bonnes pratiques de sécurité" icon="shield-check" href="/fr/security-best-practices">
    Protégez vos clés et vos clients
  </Card>

  <Card title="Contacter le support" icon="headset" href="/fr/contact">
    Obtenez l'aide de notre équipe
  </Card>
</CardGroup>