> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mercy-pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Événements

> Les événements envoyés aux marchands, avec leur contenu.

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`

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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`

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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](https://docs.mercy-pay.com/api/payments/create.md#failure_code).

Les champs de `data` sont décrits dans :

* [Paiements](https://docs.mercy-pay.com/api/payments/create.md) pour `payment.*` ;
* [Retraits](https://docs.mercy-pay.com/api/payouts/create.md) pour `payout.*` ;
* [Sessions de checkout](https://docs.mercy-pay.com/api/checkout-sessions/create.md) pour `checkout_session.completed` ;
* [Abonnements](https://docs.mercy-pay.com/api/subscriptions/create.md) pour `subscription.*` et `invoice.upcoming` ;
* [Factures](https://docs.mercy-pay.com/api/invoices/list.md) pour `invoice.created`, `invoice.paid`, `invoice.canceled` et `invoice.payment_failed`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.