Événements webhook

Catalogue de référence des événements webhook. Pour la mise en place (signature, retry, idempotence), voir le guide Webhooks.

Enveloppe commune

Tout webhook partage la même enveloppe :

{
  "event": "payment_intent.completed",
  "timestamp": 1731843299,
  "data": {
    "intentId": "3f1c…",
    "merchantId": "9a20…",
    "object": {
      "id": "3f1c…",
      "status": "completed",
      "amountRequested": "50000"
    }
  }
}

Champ	Type	Sens
`event`	string	Le type d’événement.
`timestamp`	number	Horodatage Unix de l’émission. Sert à l’anti-replay, jamais à décider d’une action.
`data`	object	Les identifiants de l’événement et `object`.
`data.object`	object	Instantané de la ressource au moment de l’émission.

Lisez vos champs dans data.object, pas dans data. data ne porte que les identifiants (intentId, merchantId, …) ; l’état de la ressource est dans data.object. data.status n’existe pas — c’est data.object.status.

Deux headers accompagnent chaque livraison : X-IziPay-Signature et X-IziPay-Timestamp. Vérifiez toujours la signature avant de traiter.

Trois règles qui évitent des bugs

object est figé. C’est l’état au moment de l’émission, pas l’état courant. Les tentatives de retry rejouent le corps octet pour octet — sans quoi la signature ne serait plus valable — donc un webhook reçu après plusieurs heures porte toujours l’ancien instantané. Pour l’état actuel, faites un GET /v1/<ressource>/{id}. Les champs vides sont omis. Un champ null n’est pas envoyé du tout. Testez la présence de la clé, pas sa valeur. Les montants sont des chaînes. Jamais des nombres JSON : un montant crypto peut porter 18 décimales, qu’un float arrondirait silencieusement. Voir Montants et précision.

Les objets embarqués

data.object prend six formes selon le domaine de l’événement.

PaymentIntent

payment_intent.* · dispute.*

Champ	Sens
`id`, `status`, `createdAt`	Identité et état.
`amountRequested`, `currencyRequested`, `requestedCurrencyType`	Ce qui a été demandé.
`amountCryptoExpected`, `assetCode`	Ce que le client devait envoyer, après choix de la crypto.
`totalAmountReceived`	Total reçu, tous dépôts confondus.
`amountInRange`	Part acceptée (dans la tolérance sous/sur-paiement).
`amountRejected`	Part rejetée, en attente de décision.
`amountNetMerchant`	Net crédité au marchand, frais déduits.
`amountToRefund`	Montant remboursable. Présent uniquement si l’intent est irrégulier.
`amountEncashed`	Présent uniquement après un encaissement.
`feeAmountTotal`, `feeAmountOnRange`, `feeAmountOnRejected`	Frais, avec la ventilation accepté / rejeté.
`snapFeeBearer`	Qui porte les frais d’encaissement : `merchant` ou `customer`.
`paymentResult`	`exact`, `underpaid_accepted`, `underpaid_rejected`, `overpaid_accepted`, `overpaid_rejected`.
`irregularStatus`	Présent si irrégulier : `pending_decision`, `encashed`, `refunded`.
`merchantReference`, `metadata`	Vos propres références.
`customerEmail`, `customerFirstName`, `customerLastName`	Identité du client, si collectée.

customerRefundAddress n’est jamais exposé dans un webhook — donnée sensible, server-only.

Payin

payin.* · merchant_deposit.completed id, paymentIntentId, amountGross, feeAmount, assetCode, senderAddress, txid (hash on-chain, votre référence canonique), status, createdAt.

Payout

payout.*

Champ	Sens
`id`, `status`, `createdAt`	Identité et état.
`payoutType`	`standard`, `refund`, `settlement`, `internal`…
`amount`, `assetCode`	Montant et actif.
`feeAmount`, `feeBearer`	Frais de service et qui les porte.
`destinationAddress`, `destinationType`, `destinationMemo`	Destination on-chain.
`networkFeeAmount`, `networkFeeAssetCode`	Frais réseau. Avant `payout.confirmed` c’est l’estimation figée ; après, le réel — qui peut valoir `0` sur Tron avec de l’énergie déléguée.
`merchantReference`	Votre référence.
`refundPaymentIntentId`	Présent si c’est un remboursement : l’intent d’origine.
`settlementId`	Présent si le payout est la jambe crypto d’un règlement.

BatchPayout

batch_payout.completed id, label, lineCount, status, executionState, createdAt, et payouts[] (chaque ligne : id, status, amount, assetCode, destinationAddress).

Settlement

settlement.*

Champ	Sens
`id`, `status`, `mode`, `createdAt`	Identité et état.
`payoutId`	La jambe crypto associée.
`assetCode`, `amountCrypto`	Ce qui a été converti.
`fiatCurrency`, `rateEffective`, `fiatAmountFinal`	Le résultat fiat et le taux réellement appliqué.
`settlementProviderFee`, `settlementMnoFee`, `feeBearer`	Frais fiat, à rapprocher de votre compte de réception.
`failureReason`	Présent si `status = failed`.
`providerReference`	Référence du prestataire de paiement.
`merchantSettlementAccountId`	Le compte de retrait crédité.

Invoice

invoice.* id, customerEmail, customerName, amount, currency, description, status, paymentIntentId, merchantReference, meta, expiresAt, createdAt.

Paiements

Événement	Déclenchement	`data`
`payment_intent.created`	Un intent vient d’être créé.	`intentId`, `merchantId`
`payment_intent.confirming`	Un paiement est arrivé on-chain, en attente de confirmations.	`intentId`, `merchantId`
`payment_intent.completed`	Montant attendu atteint, dans la plage acceptée.	`intentId`, `merchantId`
`payment_intent.expired`	Délai écoulé sans montant suffisant — ou sous-paiement hors tolérance.	`intentId`, `merchantId`

payment_intent.expired ne signifie pas toujours « rien reçu ». Un sous-paiement hors tolérance produit lui aussi un intent expired, avec de l’argent réellement reçu et en attente de votre décision. Vérifiez data.object.irregularStatus avant de conclure à un abandon. Voir Traiter un paiement irrégulier.

Dépôts on-chain

Événement	Déclenchement	`data`
`payin.detected`	Transaction vue sur la chaîne, pas encore confirmée.	`payinId`, `intentId`, `merchantId`
`payin.confirmed`	Transaction confirmée.	`payinId`, `intentId`, `merchantId`
`merchant_deposit.completed`	Dépôt direct sur votre compte, hors payment intent.	`payinId`, `merchantId`, `assetCode`, `amountGross`, `amountNet`, `feeAmount`

{
  "event": "payin.confirmed",
  "timestamp": 1731843299,
  "data": {
    "payinId": "7c02…",
    "intentId": "3f1c…",
    "merchantId": "9a20…",
    "object": {
      "id": "7c02…",
      "paymentIntentId": "3f1c…",
      "amountGross": "76.42",
      "feeAmount": "0.76",
      "assetCode": "USDT.TRC20",
      "senderAddress": "TQ5n…",
      "txid": "a3f9…",
      "status": "completed",
      "createdAt": "2026-07-24T09:12:31.000Z"
    }
  }
}

Litiges — paiements irréguliers

Un paiement sous-payé ou sur-payé hors tolérance devient un irrégulier : la part rejetée attend votre décision — encaisser ou rembourser.

Événement	Déclenchement	`data`
`dispute.created`	Un paiement irrégulier attend une décision.	`intentId`, `merchantId`
`dispute.encashed`	La part rejetée a été encaissée : elle rejoint votre solde.	`intentId`, `merchantId`, `decision`
`dispute.refunded`	La part rejetée est remboursée au client.	`intentId`, `merchantId`, `payoutId`

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

Après un encaissement, l’intent reste expired — c’est irregularStatus qui porte la vérité (encashed). Si vous n’écoutez que payment_intent.completed, cet argent n’apparaîtra jamais dans votre système alors qu’il a bien été crédité. Abonnez-vous à dispute.encashed.

Le montant crédité est data.object.amountEncashed, net de frais. Guide complet : Traiter un paiement irrégulier.

Retraits crypto

Événement	Déclenchement	`data`
`payout.created`	Le retrait est enregistré, avant diffusion.	`payoutId`, `merchantId`
`payout.approved`	Retrait débloqué après validation (seuil ou conformité).	`payoutId`, `merchantId`
`payout.confirmed`	Transaction confirmée on-chain.	`payoutId`, `merchantId`
`payout.failed`	Échec définitif — les fonds gelés sont libérés.	`payoutId`, `merchantId`
`batch_payout.completed`	Un lot est terminé.	`batchPayoutId`, `merchantId`, `status`, `confirmed`, `failed`, `total`

{
  "event": "payout.confirmed",
  "timestamp": 1731843299,
  "data": {
    "payoutId": "b81d…",
    "merchantId": "9a20…",
    "object": {
      "id": "b81d…",
      "payoutType": "standard",
      "amount": "120.00",
      "feeAmount": "1.20",
      "feeBearer": "merchant",
      "assetCode": "USDT.TRC20",
      "destinationAddress": "TQ5n…",
      "networkFeeAmount": "0",
      "networkFeeAssetCode": "TRX",
      "status": "confirmed",
      "merchantReference": "wd_2291",
      "createdAt": "2026-07-24T09:00:00.000Z"
    }
  }
}

batch_payout.completed signale la fin du lot, pas son succès. Un lot peut se terminer avec des lignes en échec : lisez data.failed et l’état de chaque ligne dans data.object.payouts[].

Règlements fiat

Événement	Déclenchement	`data`
`settlement.created`	Le règlement est créé, conversion à venir.	`settlementId`, `merchantId`, `payoutId`
`settlement.completed`	Fonds envoyés sur votre compte de retrait.	`settlementId`, `merchantId`
`settlement.failed`	Échec — voir `data.object.failureReason`.	`settlementId`, `merchantId`
`settlement.relaunched`	Un règlement bloqué a été relancé.	`settlementId`, `merchantId`

{
  "event": "settlement.completed",
  "timestamp": 1731843299,
  "data": {
    "settlementId": "5e44…",
    "merchantId": "9a20…",
    "object": {
      "id": "5e44…",
      "payoutId": "b81d…",
      "assetCode": "USDT.TRC20",
      "amountCrypto": "500.00",
      "fiatCurrency": "XOF",
      "rateEffective": "655.2",
      "fiatAmountFinal": "327600",
      "settlementProviderFee": "1500",
      "settlementMnoFee": "500",
      "feeBearer": "merchant",
      "mode": "on_chain",
      "status": "completed",
      "providerReference": "izipay-5e44…",
      "merchantSettlementAccountId": "c7a1…",
      "createdAt": "2026-07-24T09:30:00.000Z"
    }
  }
}

Factures

Événement	Déclenchement	`data`
`invoice.paid`	La facture est réglée.	`invoiceId`, `merchantId`, `intentId`
`invoice.expired`	L’échéance est passée sans règlement.	`invoiceId`, `merchantId`

Sous-portefeuilles (WaaS)

Ces événements n’ont pas de data.object : tous leurs champs sont directement dans data.

Événement	`data`
`wallet_account.deposit.completed`	`payinId`, `merchantId`, `walletAccountId`, `assetCode`, `amountGross`, `amountNet`, `feeAmount`, `txid`
`wallet_account.payout.confirmed`	`payoutId`, `merchantId`, `walletAccountId`, `assetCode`, `amountGross`, `amountSent`, `feeAmount`, `txid`
`wallet_account.transfer.completed`	`transferId`, `merchantId`, `assetCode`, `amount`, `feeAmount`, `fromWalletAccountId`, `toWalletAccountId`, `fromScope`, `toScope`
`wallet_account.closed`	`walletAccountId`, `merchantId`, `swept[]`, `releasedAddresses`

Voir Wallet-as-a-Service.

Récapitulatif

Les 25 types souscriptibles. S’abonner à un type absent de cette liste renvoie une erreur 400.

Domaine	Événements
Paiements	`payment_intent.created` · `payment_intent.confirming` · `payment_intent.completed` · `payment_intent.expired`
Dépôts	`payin.detected` · `payin.confirmed` · `merchant_deposit.completed`
Litiges	`dispute.created` · `dispute.encashed` · `dispute.refunded`
Retraits	`payout.created` · `payout.approved` · `payout.confirmed` · `payout.failed` · `batch_payout.completed`
Règlements	`settlement.created` · `settlement.completed` · `settlement.failed` · `settlement.relaunched`
Factures	`invoice.paid` · `invoice.expired`
Sous-portefeuilles	`wallet_account.deposit.completed` · `wallet_account.payout.confirmed` · `wallet_account.transfer.completed` · `wallet_account.closed`

Voir aussi

Guide Webhooks

Signature, retry, idempotence côté receveur, debugging.

Paiement irrégulier

Encaisser ou rembourser un sous/sur-paiement.

Vérifier la signature

HMAC-SHA256, anti-replay, rejeu octet pour octet.

Montants et précision

Pourquoi les montants sont des chaînes.

Démarrage

Guides d'intégration

Intégration API

Webhooks

Wallet-as-a-Service

SDKs

Cas d'usage

Enveloppe commune

Trois règles qui évitent des bugs

Les objets embarqués

PaymentIntent

Payin

Payout

BatchPayout

Settlement

Invoice

Paiements

Dépôts on-chain

Litiges — paiements irréguliers

Retraits crypto

Règlements fiat

Factures

Sous-portefeuilles (WaaS)

Récapitulatif

Voir aussi

Guide Webhooks

Paiement irrégulier

Vérifier la signature

Montants et précision

​Enveloppe commune

​Trois règles qui évitent des bugs

​Les objets embarqués

​PaymentIntent

​Payin

​Payout

​BatchPayout

​Settlement

​Invoice

​Paiements

​Dépôts on-chain

​Litiges — paiements irréguliers

​Retraits crypto

​Règlements fiat

​Factures

​Sous-portefeuilles (WaaS)

​Récapitulatif

​Voir aussi

Guide Webhooks

Paiement irrégulier

Vérifier la signature

Montants et précision

Enveloppe commune

Trois règles qui évitent des bugs

Les objets embarqués

PaymentIntent

Payin

Payout

BatchPayout

Settlement

Invoice

Paiements

Dépôts on-chain

Litiges — paiements irréguliers

Retraits crypto

Règlements fiat

Factures

Sous-portefeuilles (WaaS)

Récapitulatif

Voir aussi