Événements - Mercy Pay

Vous choisissez les événements que reçoit chaque endpoint.

Événement	Déclencheur
`payment.succeeded`	Un paiement est encaissé. Le solde est crédité.
`payment.failed`	Un paiement est refusé, annulé ou expiré (une carte non terminée expire après 24 heures). Le motif est dans `failure_code`/`failure_reason`. Pour une carte, un `payment.succeeded` peut suivre si le client réessaie.
`payment.refunded`	Un paiement est entièrement remboursé. Son statut passe à `refunded`.
`refund.succeeded`	Un remboursement est arrivé chez le client.
`refund.failed`	Un remboursement n’a pas pu être envoyé. Le montant et les frais sont revenus sur votre solde, le motif est dans `failure_reason`.
`refund.canceled`	Un remboursement retardé par un opérateur indisponible a été annulé. Le montant et les frais sont revenus sur votre solde.
`payout.paid`	Un retrait est versé sur le compte du bénéficiaire.
`payout.failed`	Un retrait échoue ou est refusé. Le motif est dans `failure_code` et `failure_reason`.
`payout.canceled`	Un retrait a été annulé : avant son examen, ou pendant qu’il attendait un opérateur indisponible. Aucun argent n’a bougé.
`checkout_session.completed`	Une session de checkout est payée. Porte le lien de paiement d’origine (`payment_link`), le téléphone et l’adresse du payeur s’ils ont été demandés, et les réponses aux champs personnalisés (`custom_fields`).
`provider_status.changed`	Un opérateur mobile money tombe en panne, se dégrade ou revient (`provider`, `country`, `status`, `previous_status`). Envoyé seulement aux endpoints qui l’ont coché, pour griser un opérateur sur votre site sans interroger `GET /api/v1/provider_status`.
`subscription.created`	Un abonnement démarre : premier paiement réussi, ou moyen de paiement enregistré pour un essai. Jamais pour une inscription pas encore payée.
`subscription.updated`	Un changement de plan est prévu ou retiré, une annulation en fin de période est prévue ou retirée, un abonnement en retard redevient à jour, ou ses informations changent.
`subscription.past_due`	Une échéance carte n’a pas pu être encaissée. De nouvelles tentatives sont programmées.
`subscription.unpaid`	Une échéance mobile money est passée sans paiement. Coupez l’accès à votre service : les relances continuent jusqu’à J+7, et `subscription.updated` arrive quand le client paie.
`subscription.paused`	Un abonnement est mis en pause.
`subscription.resumed`	Un abonnement en pause reprend.
`subscription.canceled`	Un abonnement s’arrête : annulation, dernière échéance d’un `max_cycles` atteinte, ou échec de toutes les tentatives.
`invoice.created`	Une facture est créée : à l’échéance d’un abonnement carte, ou 2 jours avant en mobile money.
`invoice.upcoming`	Une échéance arrive dans 3 jours. `data` est l’abonnement, avec `next_billing_at`.
`invoice.paid`	Une facture est payée, par carte ou par mobile money.
`invoice.canceled`	Le marchand a annulé une facture impayée. Elle ne sera plus relancée, l’abonnement continue.
`invoice.payment_failed`	Une tentative d’encaissement échoue. Le motif est dans `failure_reason`, la prochaine tentative dans `next_attempt_at`.
`webhook.test`	Envoyé à la demande, depuis la console ou l’API, pour vérifier votre endpoint. Toujours reçu, même s’il n’est pas coché. `data` contient seulement un `message`.

Enveloppe

Chaque événement suit la même structure :

Champ	Description
`id`	Identifiant unique, de la forme `evt_…`. Un même événement garde le même `id` sur tous vos endpoints et à chaque nouvel essai. Sert à dédupliquer.
`object`	Toujours `event`.
`type`	Nom de l’événement, par exemple `payout.paid`.
`created`	Date de l’événement, au format ISO 8601.
`livemode`	`true` en live, `false` en sandbox.
`data`	Ressource concernée.

Exemple `payout.paid`

{
  "id": "evt_01J9Z6P0E3VW8KZ2RMQ4YTB7XN",
  "object": "event",
  "type": "payout.paid",
  "created": "2026-10-03T10:12:00+00:00",
  "livemode": true,
  "data": {
    "id": "po_a9d4e6f21b3c4e5d8f702c9b6a1e3d48",
    "object": "payout",
    "livemode": true,
    "created": "2026-10-03T10:12:00+00:00",
    "amount": 4000,
    "fee_amount": 80,
    "net_amount": 3920,
    "currency": "XAF",
    "destination": {
      "type": "mobile_money",
      "country": "CMR",
      "provider": "MTN_MOMO_CMR",
      "phone": "237680000000"
    },
    "status": "paid",
    "failure_code": null,
    "failure_reason": null,
    "metadata": null
  }
}

Exemple `payment.failed`

{
  "id": "evt_01J9Z6Q1F4WX9L03SNR5ZUC8YP",
  "object": "event",
  "type": "payment.failed",
  "created": "2026-10-04T10:20:00+00:00",
  "livemode": true,
  "data": {
    "id": "pay_5e0c8a7b3d1f4a2e9c648b7f0d2e1a93",
    "object": "payment",
    "livemode": true,
    "created": "2026-10-04T10:20:00+00:00",
    "checkout_session": null,
    "amount": 1000,
    "fee_amount": 50,
    "net_amount": 950,
    "currency": "XAF",
    "payment_method": "mobile_money",
    "mobile_money_country": "CMR",
    "mobile_money_provider": "MTN_MOMO_CMR",
    "status": "failed",
    "failure_code": "insufficient_balance",
    "failure_reason": "Le solde du payeur est insuffisant pour effectuer ce paiement.",
    "metadata": null,
    "next_action": null
  }
}

Testez toujours failure_code dans votre code, jamais failure_reason : c’est un texte en français fait pour être affiché, pas comparé. Voir la liste complète des codes. Les champs de data sont décrits dans :

Paiements pour payment.* ;
Retraits pour payout.* ;
Sessions de checkout pour checkout_session.completed ;
Abonnements pour subscription.* et invoice.upcoming ;
Factures pour invoice.created, invoice.paid, invoice.canceled et invoice.payment_failed.