Cycle de vie du paiement

Deux questions comptent, et elles ont des réponses différentes.

Le client a-t-il payé ? C’est ce qui décide si vous honorez la commande. Lisez outcome.

Les fonds sont-ils arrivés sur mon wallet ? C’est votre versement, et il a lieu après que la commande a été honorée. Lisez settlement.

Honorer la commande selon `outcome`

curl https://hub.stablezact.com/api/v1/payments/PAYMENT_UUID/status \
  -H "X-Public-Key: pk_your_public_key"

{
  "success": true,
  "payment": {
    "paymentId": "e6c1…",
    "outcome": "paid",
    "isFinal": true,
    "amount": "50.00",
    "amountReceived": "50.00",
    "currency": "USDC",
    "network": "Base",
    "transactionHash": "0x…"
  }
}

outcome a trois valeurs.

`outcome`	Signification	Honorer
`pending`	pas encore payé, et pas terminé	non
`paid`	les fonds du client sont arrivés	oui
`failed`	expiré, annulé ou échoué	non

C’est toute la règle. Honorez la commande sur paid, et rien avant.

outcome est le même quelle que soit la façon dont le client a payé. Un paiement effectué directement depuis un wallet et un paiement envoyé à une adresse de dépôt générée atteignent tous deux paid : votre code n’a besoin que d’une branche, pas de deux.

isFinal vous indique si la réponse peut encore changer. outcome: pending avec isFinal: false signifie qu’il faut continuer d’attendre.

Puis surveillez `settlement` pour votre versement

Un paiement passe à paid dès que les fonds du client sont arrivés. Les faire parvenir jusqu’à votre wallet est une étape distincte, et dans de rares cas elle est plus lente que le paiement lui-même. C’est dans settlement que cela apparaît :

curl https://hub.stablezact.com/api/v1/payments/PAYMENT_UUID \
  -H "X-Public-Key: pk_your_public_key"

{
  "success": true,
  "payment": {
    "settlement": {
      "state": "settled",
      "message": "Paid out to your wallet."
    }
  }
}

`state`	Signification
`pending`	en attente du client
`settling`	paiement reçu, versement en cours
`delayed`	versement toujours en cours, nouvelles tentatives automatiques
`settled`	sur votre wallet
`failed`	le versement n’a pas pu être effectué, nous vous contactons

delayed n’est pas un problème sur lequel vous devez agir. Les nouvelles tentatives sont automatiques et les fonds sont comptabilisés. failed est le seul état qui demande une intervention, et c’est nous qui venons vers vous, plutôt que d’attendre que vous le remarquiez.

Chaque état comporte un message rédigé pour une personne : vous pouvez donc l’afficher dans votre propre tableau de bord sans écrire le texte vous-même.

Combien est arrivé : `paymentState`

paymentState répond à une troisième question : ce qu’ont fait les fonds, par opposition au fait que le paiement ait réussi ou non.

`paymentState`	Signification
`awaiting`	rien n’est encore arrivé
`underpaid`	une partie est arrivée, moins que le montant facturé
`completed`	le montant total est arrivé
`overpaid_refunding`	plus que le montant facturé est arrivé, l’excédent est en cours de traitement
`expired_refunding`	expiré avec un paiement insuffisant, ce qui est arrivé est en cours de restitution

underpaid n’est pas un échec. Le paiement reste ouvert et se termine si le client envoie la différence. Lorsque le paiement est insuffisant, vous recevez un webhook payment.underpaid : c’est le moment de relancer le client.

Confirmer

Les webhooks, si vous pouvez les recevoir. Vous êtes prévenu, au lieu de devoir demander. Consultez Webhooks.

Le polling, sinon, sur l’endpoint de statut ci-dessus.

Interrogez depuis votre serveur, pas depuis le navigateur. Une lecture du statut dans le navigateur du client peut être falsifiée par le client.

Le callback onSuccess du SDK se déclenche lorsque le wallet du client accepte la transaction. À ce moment, la transaction a été diffusée, pas confirmée. Elle peut encore échouer, être remplacée par une transaction avec des frais plus élevés, ou être abandonnée. Considérez onSuccess comme « le client a soumis le paiement » et confirmez séparément.

Paiements par adresse de dépôt

Certains paiements sont envoyés à une adresse générée pour ce seul paiement, plutôt que directement sur votre wallet. Les fonds vous sont ensuite transférés.

Cela ne change rien à votre intégration. outcome passe toujours à paid, et settlement vous indique toujours quand le versement arrive. L’étape supplémentaire n’est visible que dans les événements webhook de dépôt, listés dans Webhooks.

Le montant qui arrive n’est pas toujours le montant demandé. Consultez Paiements excédentaires et remboursements.

Valeurs brutes de statut

status est un champ de diagnostic qui décrit notre progression interne dans le traitement d’un paiement. Vous n’en avez pas besoin pour votre intégration : outcome et settlement contiennent tout ce qui précède. Il est listé ici pour qu’une valeur aperçue dans une réponse brute de l’API, un export du tableau de bord ou un échange avec le support puisse être retrouvée.

`status`	Rapporté comme
`pending`	`outcome: pending`
`completed`	`outcome: paid`
`sweeping`	`outcome: paid`, `settlement: settling`
`swept`	`outcome: paid`, `settlement: settled`
`sweep_failed`	`outcome: paid`, `settlement: failed`
`expired`	`outcome: failed`
`cancelled`	`outcome: failed`
`failed`	`outcome: failed`

Ne faites pas dépendre votre logique de ces valeurs. Elles décrivent nos mécanismes de règlement, elles sont susceptibles de changer, et tout ce dont vous avez besoin est déjà dans outcome et settlement.