Skip to main content

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

​
Comment ça fonctionne

​
Les cinq étapes

1

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
2

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
3

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
4

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
5

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

​
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é.
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.

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

​
Les sept statuts

→ La machine à états complète et un poller de qualité production

​
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 : 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 au lieu de renvoyer la requête.
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.

​
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 et lisez key.type pour savoir laquelle vous détenez. → Tous les scénarios sandbox, et une checklist de mise en production

​
Points clés

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

​
Référence API

Valider la clé API

GET /v3/validate

Lister les partenaires

GET /v3/partners

Découvrir les factures

POST /v3/bills/discover

Payer une facture

POST /v3/bills/pay

Obtenir une transaction par ID

GET /v3/bills/transactions/id

Obtenir une transaction par référence

GET /v3/bills/transactions/by-ref

Lister les transactions

GET /v3/bills/transactions

Télécharger le reçu

GET /v3/bills/transactions/id/receipt

​
Démarrer l’intégration

Commencer par l'Étape 1 : Partenaires et comptes

Vérifiez la disponibilité et apprenez les règles d’identifiant de chaque facturier

​
Ressources supplémentaires

Authentification

Clés, en-têtes et environnements

Format de réponse

L’enveloppe renvoyée par chaque endpoint

Gestion des erreurs

Chaque code d’erreur et ce qu’il faut faire

Stratégies de polling

Intervalles, backoff et plafonds

Bonnes pratiques de sécurité

Protégez vos clés et vos clients

Contacter le support

Obtenez l’aide de notre équipe