Traiter un paiement irrégulier

Quand un client envoie un montant hors tolérance — trop peu ou trop — le paiement devient irrégulier. La part hors plage n’est ni acquise ni rendue : elle attend un arbitrage.

L’arbitrage se fait depuis le tableau de bord, pas par API. Encaisser ou rembourser engage une revue humaine : la décision n’est pas automatisable. Votre intégration détecte le cas et réconcilie le résultat ; la décision, elle, se prend dans Litiges.

Le piège à connaître d’abord

Un sous-paiement hors tolérance produit un intent au statut expired — alors que de l’argent a bien été reçu.Si votre intégration écoute seulement payment_intent.completed et traite expired comme un abandon, vous ignorerez de l’argent réellement encaissable. Le statut ne suffit pas : lisez irregularStatus.

`irregularStatus`	Sens
`none`	Paiement normal, rien à arbitrer.
`pending_decision`	Un arbitrage est attendu dans le tableau de bord.
`encashed`	La part rejetée a été encaissée : elle est sur votre solde.
`refunded`	Elle a été remboursée au client.

paymentResult précise la nature : underpaid_accepted, underpaid_rejected, overpaid_accepted, overpaid_rejected. Les variantes _accepted sont dans la tolérance — elles se règlent seules, sans arbitrage.

1. Détecter — webhook

Abonnez-vous à dispute.created :

{
  "event": "dispute.created",
  "timestamp": 1731843299,
  "data": {
    "intentId": "3f1c…",
    "merchantId": "9a20…",
    "object": {
      "id": "3f1c…",
      "status": "expired",
      "paymentResult": "underpaid_rejected",
      "irregularStatus": "pending_decision",
      "amountRequested": "50000",
      "currencyRequested": "XOF",
      "totalAmountReceived": "70.00",
      "amountInRange": "0",
      "amountRejected": "70.00",
      "amountToRefund": "69.30",
      "assetCode": "USDT.TRC20"
    }
  }
}

amountRejected — la part brute hors tolérance.
amountToRefund — ce qui serait effectivement remboursé, frais déduits.

Ajoutez aussi une garde sur payment_intent.expired : testez irregularStatus avant de conclure à un abandon.

// Un `expired` peut cacher de l'argent en attente d'arbitrage.
if (event.event === 'payment_intent.expired') {
  const st = event.data.object?.irregularStatus;
  if (st === 'pending_decision') {
    await flagForReview(event.data.intentId);   // à arbitrer au dashboard
  } else {
    await markAbandoned(event.data.intentId);
  }
}

2. Consulter — API

Les champs d’irrégularité sont exposés sur le payment intent. Lister ceux en écart :

curl -G https://api.izichangepay.com/v1/payment-intents \
  -H "Authorization: Bearer $IZIPAY_API_KEY" \
  --data-urlencode "status=irregular"

Lire un cas précis :

curl https://api.izichangepay.com/v1/payment-intents/{id} \
  -H "Authorization: Bearer $IZIPAY_API_KEY"

La réponse porte irregularStatus, paymentResult, amountRejected et amountToRefund — de quoi afficher l’état dans votre back-office et suivre ce qui reste à arbitrer. Scope requis : payments:read.

3. Arbitrer — tableau de bord

Encaisser ou rembourser se fait dans Litiges. Pour un remboursement, l’adresse du client est reprise de celle qu’il a laissée sur la page de paiement ; elle peut être corrigée au moment de la décision.

Sous-paiement : laisser le client compléter

Sur un sous-paiement, une troisième issue est proposée : réactiver le paiement. Plutôt que de clore la transaction, elle la remet en cours avec un nouveau délai, sur la même adresse de dépôt — le client n’a qu’à envoyer le complément. Le paiement suit alors son cours normal : payment_intent.completed s’il est soldé, nouveau litige à l’échéance sinon. La réactivation est refusée si cette adresse de dépôt a entre-temps été attribuée à une autre transaction ; il faut alors attendre que celle-ci se termine.

4. Réconcilier — webhook

Événement	Sens	`data`
`dispute.encashed`	La part rejetée a rejoint votre solde.	`intentId`, `merchantId`, `decision`
`dispute.refunded`	Le remboursement est parti.	`intentId`, `merchantId`, `payoutId`
`dispute.reactivated`	Le sous-paiement est rouvert jusqu’à `expiresAt` — ne clôturez pas la commande, le client peut encore payer.	`intentId`, `merchantId`, `expiresAt`

{
  "event": "dispute.encashed",
  "timestamp": 1731843299,
  "data": {
    "intentId": "3f1c…",
    "merchantId": "9a20…",
    "decision": "encash",
    "object": {
      "id": "3f1c…",
      "status": "expired",
      "irregularStatus": "encashed",
      "amountRejected": "70.00",
      "amountEncashed": "69.30",
      "assetCode": "USDT.TRC20"
    }
  }
}

Le montant crédité est data.object.amountEncashed, net de frais — pas amountRejected, qui est le brut.

Après un encaissement, l’intent reste expired et aucun payment_intent.completed n’est émis. C’est volontaire : le paiement n’a jamais atteint le montant demandé. Votre comptabilité doit se fonder sur dispute.encashed, sinon cet argent restera invisible dans votre système alors qu’il est bien sur votre solde.

Pour un remboursement, payoutId permet de suivre le transfert on-chain via payout.confirmed ou GET /v1/payouts/{id}.

Récapitulatif

Détecter — dispute.created, et garde sur irregularStatus pour tout payment_intent.expired.
Consulter — GET /v1/payment-intents?status=irregular.
Arbitrer — dans le tableau de bord : encaisser, rembourser, ou (sous-paiement) réactiver pour laisser le client compléter.
Réconcilier — sur dispute.encashed / dispute.refunded, jamais sur le statut de l’intent. Sur dispute.reactivated, rien à réconcilier : gardez la commande ouverte et attendez l’issue normale du paiement.

Voir aussi

Litiges au tableau de bord

Où se prend la décision.

Événements webhook

Le format exact de dispute.*.

Démarrage

Guides d'intégration

Intégration API

Webhooks

Wallet-as-a-Service

SDKs

Cas d'usage

Traiter un paiement irrégulier

Le piège à connaître d’abord

1. Détecter — webhook

2. Consulter — API

3. Arbitrer — tableau de bord

Sous-paiement : laisser le client compléter

4. Réconcilier — webhook

Récapitulatif

Voir aussi

Litiges au tableau de bord

Événements webhook

​Le piège à connaître d’abord

​1. Détecter — webhook

​2. Consulter — API

​3. Arbitrer — tableau de bord

​Sous-paiement : laisser le client compléter

​4. Réconcilier — webhook

​Récapitulatif

​Voir aussi

Litiges au tableau de bord

Événements webhook

Le piège à connaître d’abord

1. Détecter — webhook

2. Consulter — API

3. Arbitrer — tableau de bord

Sous-paiement : laisser le client compléter

4. Réconcilier — webhook

Récapitulatif

Voir aussi