Skip to main content
POST
Payer une Facture

Vue d’Ensemble

Paie une seule facture issue d’une découverte READY. Vous choisissez un billId parmi les bills[] de cette transaction ; la même transaction porte ensuite le paiement jusqu’à un état final.
200 est un accusé de réception, pas un résultat. Cela signifie que le paiement a été accepté et qu’il est désormais en cours d’acheminement. Le fait que l’argent ait réellement été déplacé n’est connaissable que par le status de la transaction — interrogez-la jusqu’à ce qu’elle atteigne SUCCESS, FAILED ou REFUNDED.
C’est l’appel qui déplace de l’argent. Tout ce dont vous avez besoin de votre côté — l’enregistrement de la commande, le montant, l’autorisation de votre client — doit déjà être persisté avant de l’envoyer.

Corps de la Requête

string
requis
La découverte sur laquelle payer. Doit être une chaîne hexadécimale minuscule de 24 caractères, et la transaction doit être actuellement READY.
string
requis
Le billId d’une entrée des bills[] de cette transaction. Maximum 100 caractères.Copiez-le depuis la réponse — ne le construisez pas.
string
requis
Une nouvelle référence pour ce paiement. Maximum 100 caractères, et unique parmi vos transactions en cours pour ce partenaire.Elle doit être différente de la ref que vous avez utilisée pour la découverte ; réutiliser cette valeur répond 403 DUPLICATED_REF.
La transaction conserve la ref avec laquelle elle a été créée. C’est cette ref de découverte d’origine que cet endpoint renvoie, que Obtenir une Transaction par Référence recherche, et qui apparaît désormais sur la transaction.

Réponse

boolean
requis
true lorsque le paiement a été accepté.
object
requis
object
requis
string
requis
Identifiant de corrélation, également envoyé dans l’en-tête de réponse X-Request-Id.

Exemples

Réponse de Succès

Une fois que la transaction atteint SUCCESS, Obtenir une Transaction par ID retourne operationId et receiptUrl aux côtés de selectedBill et total.

Réponses d’Erreur

Le corps ne correspondait pas au schéma.
Causes courantes : un transactionId qui ne fait pas 24 caractères hexadécimaux, un billId manquant, une ref manquante, ou une ref de plus de 100 caractères.Que faire : corrigez la requête. Ne la réessayez jamais telle quelle.
La clé était absente ou a été rejetée.
Que faire : vérifiez la clé avec Valider la Clé API. Rien n’a été débité.
La ref est déjà utilisée pour ce partenaire.
La cause la plus fréquente est la réutilisation de la ref de découverte pour le paiement. Envoyez une valeur distincte, par exemple pay- devant votre identifiant de commande.Que faire : avant de réessayer, vérifiez l’état actuel de la transaction avec Obtenir une Transaction par ID. Si elle est déjà PROCESSING, votre paiement est bien passé et il n’y a rien à renvoyer.
La transaction n’existe pas pour votre compte, ou elle n’est pas dans un état payable, ou ce billId ne fait pas partie de ses factures.
Ces trois cas répondent tous 404 — y compris une transaction qui appartient à un autre partenaire, de sorte que l’API ne confirme jamais l’existence de la transaction de quelqu’un d’autre.Que faire : relisez la transaction. Si son status n’est plus READY, le paiement a déjà été démarré ; interrogez-la au lieu d’en envoyer un autre.
Cette facture précise a déjà été payée.
Que faire : traitez-le comme un résultat positif que vous détenez déjà. Retrouvez la transaction payée dans Lister les Transactions et utilisez son reçu. Ne facturez pas deux fois votre client.
Un autre paiement pour la même facture n’est pas terminé.
Que faire : interrogez la transaction déjà en cours. Renvoyer cet appel ne la fera pas se terminer plus tôt.
Le facturier est injoignable, ou est actuellement désactivé.
Que faire : rien n’a été débité. La découverte est toujours READY, vous pouvez donc payer le même billId plus tard — avec la même ref, qui n’a jamais été consommée.
Nous n’avons pas pu vérifier votre clé à temps. Votre clé n’est pas en cause.
Que faire : attendez le Retry-After (5 secondes) et réessayez la même requête. La requête n’a jamais atteint le chemin de paiement, il est donc sans risque de la réessayer.
L’API Bill Payment est en maintenance planifiée.
Que faire : respectez Retry-After et réessayez.
Quelque chose a échoué de notre côté.
Que faire : ne renvoyez pas le paiement. Lisez d’abord la transaction — si elle est PROCESSING, le paiement est en cours. Contactez le support avec le requestId si l’état n’est pas clair.

Ce que vous payez

Chaque facture d’une découverte porte ses propres champs monétaires. Les frais sont un pourcentage du montant, borné entre un minimum et un maximum, défini par facturier : Comme 0,5 % d’une facture courante reste largement sous le minimum, la plupart des paiements sont facturés exactement au minimum. 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 apparaît sur la transaction une fois qu’une facture a été sélectionnée. Pour la facture ADE de 443,39 DZD ci-dessus : 0,5 % vaut 2,22, soit moins que le minimum de 30 DZD, donc fee vaut 30,00 et total vaut 473,39.

Avant d’appeler

1

Persistez d'abord votre propre enregistrement

Écrivez votre commande — client, transactionId, billId, amount, fee, total et la ref que vous êtes sur le point d’utiliser — avant que la requête ne quitte votre processus. Si la réponse est perdue, cet enregistrement est le moyen de retrouver le paiement.
2

Confirmez le montant avec votre client

amount et fee proviennent de la découverte. Affichez le total que vous allez débiter, pas une estimation.
3

Envoyez le paiement

Un seul appel, avec une ref nouvelle pour ce partenaire.
4

Interrogez jusqu'à l'état final

SUCCESS, FAILED ou REFUNDED. Traitez UNKNOWN comme « continuez à interroger », jamais comme un échec.Interrogation du statut

Les protections qui vous protègent

Trois règles empêchent le même argent de bouger deux fois. Toutes les trois répondent avant que quoi que ce soit ne soit débité.
Aucune de ces trois réponses n’est une raison de réessayer avec une ref différente. Chacune signifie que le travail est soit déjà fait, soit déjà en cours — recherchez-le plutôt que de le renvoyer.

Bonnes Pratiques

Écrivez avant d'envoyer

Persistez l’enregistrement de votre commande, y compris la ref, avant la requête. Une réponse perdue est alors récupérable.

Une ref par appel

Utilisez une ref distincte pour la découverte et pour le paiement. disc- et pay- devant votre identifiant de commande suffisent.

Ne renvoyez jamais après un délai d'attente

Lisez d’abord la transaction. Un délai d’attente réseau ne signifie pas que le paiement n’a pas eu lieu.

Facturez à partir de total

Débitez à votre client le total retourné par l’API, jamais un montant que vous avez calculé vous-même.

Endpoints Associés

Découvrir les Factures

Trouver ce qui est payable

Obtenir une Transaction par ID

Interroger le résultat

Télécharger le Reçu

Preuve de paiement

Obtenir une Transaction par Référence

Récupérer une réponse perdue

Payer les Factures

Le guide complet

Interrogation du Statut

Un interrogateur prêt pour la production