API webhooks : Izzi Pay | Portail marchand izzi-pay

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

Nom	Type	Requis	Description
merchantId	string	Oui	UUID marchand

Corps de requête

Nom	Type	Requis	Description
url	string	Oui	URL de réception HTTPS
events	string[]	Non	Liste d'événements ou * pour tous
status	string	Non	ACTIVE ou DISABLED

Exemple requête

json

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

Réponse (data)

Nom	Type	Requis	Description
id	string	Oui	endpointId
secret	string	Non	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.izzi-finance.com/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

Nom	Type	Requis	Description
merchantId	string	Oui	UUID marchand

Réponse (data)

Nom	Type	Requis	Description
id	string	Oui	endpointId

Exemple réponse

json

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

Exemples

bash

curl -X GET https://api.izzi-finance.com/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

Nom	Type	Requis	Description
merchantId	string	Oui	UUID marchand

Réponse (data)

Nom	Type	Requis	Description
eventType	string	Oui	Type d'événement
status	string	Oui	DELIVERED, 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.izzi-finance.com/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

Nom	Type	Requis	Description
merchantId	string	Oui	UUID marchand
deliveryId	string	Oui	Identifiant livraison

Réponse (data)

Nom	Type	Requis	Description
status	string	Oui	Nouveau statut

Exemple réponse

json

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

Exemples

bash

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

Voir aussi

POST/api/v1/merchant/merchants/:merchantId/webhook-endpoints/:endpointId/rotate-secretPermission · merchant.webhooks.manage

Rotation du secret webhook

Génère un nouveau secret de signature (whsec_…) pour un endpoint existant. Le secret précédent est invalidé immédiatement.

Paramètres de chemin

Nom	Type	Requis	Description
merchantId	string	Oui	UUID marchand
endpointId	string	Oui	Identifiant endpoint (we_…)

Réponse (data)

Nom	Type	Requis	Description
secret	string	Non	Nouveau secret affiché une seule fois

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.izzi-finance.com/api/v1/merchant/merchants/:merchantId/webhook-endpoints/:endpointId/rotate-secret \
  -H "Authorization: Bearer izzi_mk_sandbox_…" \
  -H "Content-Type: application/json"

Voir aussi

Événements webhook

payment.succeeded

Paiement réussi

Un paiement checkout ou une charge a été encaissée avec succès.

Déclenché par : POST /checkout/pay/:sessionId/complete réussi, ou charge au statut CAPTURED

json

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

payment.failed

Paiement échoué

Le paiement n'a pas pu être finalisé.

Déclenché par : Échec prestataire ou validation à l'appel /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é

Un remboursement sur charge a été enregistré.

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"
  }
}

refund.rejected

Remboursement rejeté

Un remboursement a été refusé par l'institution.

Déclenché par : Décision de rejet sur une demande de remboursement

json

{
  "type": "refund.rejected",
  "data": {
    "chargeId": "a76c830e-b7f1-4fd4-b5b6-618ffdb76b62",
    "refundId": "ref_abc123",
    "status": "REJECTED",
    "reason": "insufficient_balance"
  }
}

checkout.session.completed

Session de paiement terminée

La session de paiement est au statut SUCCEEDED.

Déclenché par : Paiement checkout finalisé avec succès

json

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

checkout.session.expired

Session de paiement expirée

La session a expiré sans paiement.

Déclenché par : Délai dépassé ou fermeture manuelle

json

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

wallet.credited

Portefeuille crédité

Le solde marchand augmente après un encaissement.

Déclenché par : Crédit portefeuille après paiement ou règlement

json

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

payout.created

Décaissement créé

Un décaissement a été 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 d'approbation

Le décaissement attend une validation de l'institution.

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

json

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

payout.completed

Décaissement terminé

Les fonds ont été envoyés au bénéficiaire.

Déclenché par : Exécution du décaissement réussie

json

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

payout.failed

Décaissement échoué

L'exécution du décaissement a échoué.

Déclenché par : Erreur prestataire ou validation

json

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

payout.rejected

Décaissement rejeté

Le décaissement a été refusé par un valideur.

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

json

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

settlement.created

Règlement créé

Un lot de règlement a été créé pour le marchand.

Déclenché par : Traitement planifié des règlements

json

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

settlement.completed

Règlement terminé

Le règlement est traité et les fonds sont disponibles.

Déclenché par : Lot de règlement clôturé

json

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