Statut de la transaction - OneClickDz Flexy API

Un seul objet pour tout le cycle de vie

Une découverte et le paiement effectué à partir de celle-ci sont la même transaction, avec le même transactionId et la même ref. type vaut discovery jusqu’à ce qu’un paiement soit accepté, puis payment. Lisez-la avec GET /v3/bills/transactions/{transactionId} ou GET /v3/bills/transactions/by-ref?ref=….

Statuts

Statut	Phase	Signification	Final
`PENDING`	Découverte	Découverte en cours	Non
`READY`	Découverte	`bills[]` est disponible ; en attente de `pay`	Non
`FAILED`	Découverte	La découverte n’a pas pu aboutir ; voir `error`	Oui
`PROCESSING`	Paiement	Paiement en cours	Non
`UNKNOWN`	Paiement	Résultat pas encore confirmé	Non
`SUCCESS`	Paiement	Payé ; `receiptUrl` et `operationId` disponibles	Oui
`FAILED`	Paiement	Non payé ; rien n’a été débité	Oui
`REFUNDED`	Paiement	Débité puis intégralement remboursé ; voir `error`	Oui

Champs

Toujours présents :

Champ	Type	Description
`transactionId`	string	Identifiant de la transaction
`ref`	string	Votre `ref` de découverte
`type`	string	`discovery` ou `payment`
`status`	string	L’un des statuts ci-dessus
`partner`	string	Nom du facturier
`account`	object	L’identifiant, renvoyé sous une clé propre au partenaire
`currency`	string	Toujours `DZD`
`createdAt`	string	ISO 8601
`updatedAt`	string	ISO 8601, dernière modification
`completedAt`	string \| null	`null` tant que la transaction est en cours. Renseigné lorsque la découverte se termine, lorsqu’un paiement passe à `UNKNOWN`, `SUCCESS` ou `FAILED`, et lorsqu’un remboursement est terminé.

Présents selon le statut :

Champ	Présent quand	Description
`bills[]`	`READY`	Factures impayées ; tableau vide lorsque rien n’est dû
`selectedBill`	après `pay`	La facture en cours de paiement. Pour une commande multi-factures : `amount` est le montant cumulé, `billId` est le premier id
`selectedBills[]`	après `pay`, commande multi-factures uniquement	Chaque facture de la commande
`total`	après `pay`	`selectedBill.amount + selectedBill.fee`, le montant débité de votre solde
`receiptUrl`	`SUCCESS`	URL complète de téléchargement du reçu
`operationId`	`SUCCESS`	La référence d’opération du facturier ou de la passerelle de paiement
`error`	`FAILED`, `REFUNDED`	`{ code, message }`

Basez votre logique sur status, jamais sur la présence d’un champ.

`error.code`

Code	Signification
`PAYMENT_DECLINED`	La banque ou le portail du facturier a refusé le paiement
`PARTNER_UNAVAILABLE`	Le portail du facturier n’a pas répondu
`INVALID_ACCOUNT`	Le facturier ne reconnaît pas l’identifiant
`BILL_ALREADY_PAID`	Le facturier indique que la facture est déjà réglée

Interrogation

Phase	Intervalle	Arrêter quand	Durée typique
Découverte	2–3 s	`status` ≠ `PENDING`	Quelques secondes ; quelques minutes en période de charge
Paiement	5 s	`status` vaut `SUCCESS`, `FAILED` ou `REFUNDED`	Moins de quelques minutes
`UNKNOWN`	60 s	`status` vaut `SUCCESS` ou `REFUNDED`	Généralement quelques minutes ; plus long si une vérification manuelle est nécessaire

Node.js

const FINAL = new Set(["SUCCESS", "FAILED", "REFUNDED"]);

async function waitForPayment(transactionId) {
  for (;;) {
    const res = await fetch(`https://api.oneclickdz.com/v3/bills/transactions/${transactionId}`, {
      headers: { "X-Access-Token": process.env.ONECLICKDZ_API_KEY },
    });
    const body = await res.json();
    if (!body.success) throw new Error(body.error.code);

    const txn = body.data;
    if (FINAL.has(txn.status)) return txn;

    const delay = txn.status === "UNKNOWN" ? 60_000 : 5_000;
    await new Promise((r) => setTimeout(r, delay));
  }
}

UNKNOWN

UNKNOWN signifie que le paiement a été soumis au facturier mais que le résultat n’a pas été confirmé. L’argent a pu être débité ou non. Ce statut se résout toujours en SUCCESS ou REFUNDED. Tant qu’une transaction est UNKNOWN :

Ne lancez pas de nouveau paiement pour la même facture.
Ne remboursez pas et ne créditez pas votre client.
Indiquez au client que le paiement est en cours de confirmation.

Reprise après une expiration

Si discover ou pay expire de votre côté, la requête a pu être traitée malgré tout.

GET /v3/bills/transactions/by-ref?ref=<your discovery ref>.
404 NOT_FOUND : la découverte n’a jamais été créée. Renvoyez-la avec la même ref.
Tout autre résultat : la transaction existe. Reprenez à partir de son status.

Pour une expiration de pay, lisez la transaction par id : PROCESSING ou un statut ultérieur signifie que le paiement a été accepté.

Suivant : Reçus et rapprochement

Télécharger les reçus et rapprocher votre historique

​Un seul objet pour tout le cycle de vie

​Statuts

​Champs

​error.code

​Interrogation

​UNKNOWN

​Reprise après une expiration