Webhooks

Configuration et livraisons webhook.

POST/api/v1/merchant/merchants/:merchantId/webhook-endpointsPermission · merchant.webhooks.manage

Créer un endpoint webhook

Enregistre une URL HTTPS (HTTP localhost autorisé en dev) et les événements souscrits.

Paramètres de chemin

NomTypeRequisDescription
merchantIdstringOuiUUID marchand

Corps de requête

NomTypeRequisDescription
urlstringOuiURL de réception HTTPS
eventsstring[]—Liste d'événements ou * pour tous
statusstring—ACTIVE ou DISABLED

Exemple requête

json
{
  "url": "https://api.merchant.example/webhooks/izzi",
  "events": [
    "payment.succeeded",
    "checkout.session.completed"
  ]
}

Réponse (data)

NomTypeRequisDescription
idstringOuiendpointId
secretstring—Secret affiché une seule fois (whsec_…)

Exemple réponse

json
{
  "success": true,
  "data": {
    "id": "we_abc123",
    "url": "https://api.merchant.example/webhooks/izzi",
    "secret": "whsec_…",
    "events": [
      "payment.succeeded"
    ]
  }
}

Exemples

bash
curl -X POST https://api.dev.izzi-finance.com/api/v1/api/v1/merchant/merchants/:merchantId/webhook-endpoints \
  -H "Authorization: Bearer izzi_mk_sandbox_…" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://api.merchant.example/webhooks/izzi",
  "events": [
    "payment.succeeded",
    "checkout.session.completed"
  ]
}'

Voir aussi

GET/api/v1/merchant/merchants/:merchantId/webhook-endpointsPermission · merchant.webhooks.manage

Lister les endpoints webhook

Liste des endpoints configurés pour un marchand.

Paramètres de chemin

NomTypeRequisDescription
merchantIdstringOuiUUID marchand

Réponse (data)

NomTypeRequisDescription
idstringOuiendpointId

Exemple réponse

json
{
  "success": true,
  "data": [
    {
      "id": "we_abc123",
      "url": "https://api.merchant.example/webhooks/izzi"
    }
  ]
}

Exemples

bash
curl -X GET https://api.dev.izzi-finance.com/api/v1/api/v1/merchant/merchants/:merchantId/webhook-endpoints \
  -H "Authorization: Bearer izzi_mk_sandbox_…" \
  -H "Content-Type: application/json"

Voir aussi

GET/api/v1/merchant/merchants/:merchantId/webhook-deliveriesPermission · merchant.webhooks.manage

Historique des livraisons

Tentatives de livraison webhook avec statut et erreurs.

Paramètres de chemin

NomTypeRequisDescription
merchantIdstringOuiUUID marchand

Réponse (data)

NomTypeRequisDescription
eventTypestringOuiType d'événement
statusstringOuiDELIVERED, FAILED, PENDING

Exemple réponse

json
{
  "success": true,
  "data": [
    {
      "id": "wd_001",
      "eventType": "payment.succeeded",
      "status": "DELIVERED",
      "attempts": 1
    }
  ]
}

Exemples

bash
curl -X GET https://api.dev.izzi-finance.com/api/v1/api/v1/merchant/merchants/:merchantId/webhook-deliveries \
  -H "Authorization: Bearer izzi_mk_sandbox_…" \
  -H "Content-Type: application/json"

Voir aussi

POST/api/v1/merchant/merchants/:merchantId/webhook-deliveries/:deliveryId/retryPermission · merchant.webhooks.manage

Relancer une livraison

Rejoue une livraison webhook échouée.

Paramètres de chemin

NomTypeRequisDescription
merchantIdstringOuiUUID marchand
deliveryIdstringOuiIdentifiant livraison

Réponse (data)

NomTypeRequisDescription
statusstringOuiNouveau statut

Exemple réponse

json
{
  "success": true,
  "data": {
    "id": "wd_001",
    "status": "PENDING",
    "attempts": 2
  }
}

Exemples

bash
curl -X POST https://api.dev.izzi-finance.com/api/v1/api/v1/merchant/merchants/:merchantId/webhook-deliveries/:deliveryId/retry \
  -H "Authorization: Bearer izzi_mk_sandbox_…" \
  -H "Content-Type: application/json"

Voir aussi

Événements webhook

payment.succeeded

Paiement réussi

Émis lorsqu'un paiement checkout ou une charge est capturée avec succès.

Déclenché par : POST /checkout/pay/:sessionId/complete (succès) ou charge CAPTURED

json
{
  "id": "evt_001",
  "type": "payment.succeeded",
  "createdAt": "2026-08-17T14:30:00.000Z",
  "data": {
    "chargeId": "a76c830e-b7f1-4fd4-b5b6-618ffdb76b62",
    "paymentIntentId": "b04cb5ed-3e0b-446a-b3cd-8ef2e2836b8d",
    "sessionId": "cs_38b62a204d2da0bcdd312c59",
    "amount": "2500",
    "currency": "USD",
    "status": "SUCCEEDED"
  }
}

payment.failed

Paiement échoué

Émis lorsqu'un paiement ne peut pas être finalisé.

Déclenché par : Échec provider ou validation lors du /complete

json
{
  "type": "payment.failed",
  "data": {
    "sessionId": "cs_38b62a204d2da0bcdd312c59",
    "status": "FAILED",
    "failureCode": "INSUFFICIENT_FUNDS",
    "failureMessage": "Votre compte mobile money n'a pas assez de fonds pour ce paiement.",
    "reason": "INSUFFICIENT_BALANCE",
    "amount": "2500",
    "currency": "USD"
  }
}

payment.refunded

Remboursement effectué

Émis après un remboursement charge réussi.

Déclenché par : POST /merchant/charges/:chargeId/refund

json
{
  "type": "payment.refunded",
  "data": {
    "chargeId": "a76c830e-b7f1-4fd4-b5b6-618ffdb76b62",
    "refundId": "ref_abc123",
    "amount": "500",
    "currency": "USD"
  }
}

checkout.session.completed

Session checkout terminée

Session passée à SUCCEEDED.

Déclenché par : Finalisation checkout réussie

json
{
  "type": "checkout.session.completed",
  "data": {
    "sessionId": "cs_38b62a204d2da0bcdd312c59",
    "merchantId": "7baa3a61-697f-4cb5-a9d9-537b3375d851",
    "amount": "2500",
    "currency": "USD"
  }
}

checkout.session.expired

Session checkout expirée

Session expirée sans paiement.

Déclenché par : TTL dépassé ou expiration manuelle

json
{
  "type": "checkout.session.expired",
  "data": {
    "sessionId": "cs_38b62a204d2da0bcdd312c59",
    "expiresAt": "2026-08-17T12:00:00.000Z"
  }
}

wallet.credited

Wallet crédité

Solde marchand augmenté après encaissement.

Déclenché par : Crédit wallet post-paiement ou settlement

json
{
  "type": "wallet.credited",
  "data": {
    "walletId": "6015fa0e-0e44-461e-9ec8-b598ca19c14b",
    "amount": "2437.5",
    "currency": "USD",
    "reference": "checkout:cs_38b62a:credit"
  }
}

payout.created

Décaissement créé

Nouveau payout initié.

Déclenché par : POST /payments/payouts

json
{
  "type": "payout.created",
  "data": {
    "payoutId": "po_xyz789",
    "amount": "500",
    "status": "AWAITING_APPROVAL"
  }
}

payout.awaiting_approval

Décaissement en attente

Payout nécessite une approbation institution.

Déclenché par : Création payout avec approbation requise

json
{
  "type": "payout.awaiting_approval",
  "data": {
    "payoutId": "po_xyz789",
    "amount": "500"
  }
}

payout.completed

Décaissement terminé

Fonds envoyés au bénéficiaire.

Déclenché par : Exécution payout réussie

json
{
  "type": "payout.completed",
  "data": {
    "payoutId": "po_xyz789",
    "status": "COMPLETED"
  }
}

payout.failed

Décaissement échoué

Échec d'exécution du payout.

Déclenché par : Erreur provider ou validation

json
{
  "type": "payout.failed",
  "data": {
    "payoutId": "po_xyz789",
    "failureReason": "provider_error"
  }
}

payout.rejected

Décaissement rejeté

Payout refusé par un approbateur.

Déclenché par : POST /payments/payouts/:id/reject

json
{
  "type": "payout.rejected",
  "data": {
    "payoutId": "po_xyz789",
    "reason": "insufficient_balance"
  }
}

settlement.created

Règlement créé

Lot de règlement généré pour le marchand.

Déclenché par : Job de settlement planifié

json
{
  "type": "settlement.created",
  "data": {
    "settlementId": "set_001",
    "amount": "10000",
    "currency": "USD"
  }
}

settlement.completed

Règlement terminé

Fonds du règlement disponibles.

Déclenché par : Settlement traité

json
{
  "type": "settlement.completed",
  "data": {
    "settlementId": "set_001",
    "netAmount": "9750"
  }
}