Webhooks

Événements webhook

Un exemple de contenu par famille d’événements, avec la forme exacte des objets.

Chaque événement a la même enveloppe : id, object: "event", type, livemode, created_at et data.object. data.object est l’objet dans son état au moment de l’envoi, au même format que l’API. Les exemples ci-dessous sont complets. La liste des types figure dans Webhooks.

Encaissements

collection.succeeded, collection.failed, collection.expired. data.object est un encaissement. En cas d’échec, failure_code vaut failed ou expired et failure_message peut donner un motif.

JSON

{
  "id": "3ab70bfc-785d-45ce-99de-fd9ab67e5cd4",
  "object": "event",
  "type": "collection.succeeded",
  "livemode": false,
  "created_at": "2026-10-30T13:47:09.807Z",
  "data": {
    "object": {
      "id": "3b8f6c1e-2a47-4d1b-9e35-7c0a9d2f4e61",
      "object": "collection",
      "livemode": false,
      "status": "succeeded",
      "amount": 5000,
      "currency": "XAF",
      "fee": 125,
      "net": 4875,
      "customer": {
        "name": "Awa Ndiaye",
        "phone": "237670000999",
        "country": "CM"
      },
      "operator": "MTN",
      "description": "Order 42",
      "client_reference": "order_42",
      "metadata": {
        "order_id": "42"
      },
      "next_action": null,
      "failure_code": null,
      "failure_message": null,
      "created_at": "2026-10-30T13:47:06.394Z",
      "updated_at": "2026-10-30T13:47:09.807Z"
    }
  }
}

Paiements

payout.succeeded, payout.failed. data.object est un paiement. Sur payout.failed, le montant et les frais sont revenus sur votre solde.

JSON

{
  "id": "8c3e5a71-0f2d-4b96-a7e4-1d9b6c2f8a03",
  "object": "event",
  "type": "payout.succeeded",
  "livemode": false,
  "created_at": "2026-10-30T13:47:09.807Z",
  "data": {
    "object": {
      "id": "7b05e2b6-6638-4088-a984-7155dfd6a036",
      "object": "payout",
      "livemode": false,
      "status": "succeeded",
      "amount": 150000,
      "currency": "XAF",
      "fee": 2250,
      "recipient": {
        "type": "mobile_money",
        "name": "Kossi Mensah",
        "operator": "MTN",
        "phone": "237670000777",
        "country": "CM"
      },
      "description": "Invoice 2026-118",
      "client_reference": "inv_118",
      "metadata": {},
      "failure_code": null,
      "failure_message": null,
      "created_at": "2026-10-30T13:47:06.394Z",
      "updated_at": "2026-10-30T13:47:09.807Z"
    }
  }
}

Reversements

settlement.succeeded, settlement.failed. data.object est un reversement.

JSON

{
  "id": "4f7a1c92-6b3e-4d08-9e5a-2c81f0b7d364",
  "object": "event",
  "type": "settlement.succeeded",
  "livemode": false,
  "created_at": "2026-10-30T13:47:09.807Z",
  "data": {
    "object": {
      "id": "575f3a4b-ccd5-4949-9c4d-158127ccccd1",
      "object": "settlement",
      "livemode": false,
      "status": "succeeded",
      "amount": 2500000,
      "currency": "XAF",
      "fee": 0,
      "recipient": {
        "type": "bank",
        "name": "Acme SARL",
        "bank_code": "10005",
        "account": "••••0193",
        "country": "CM"
      },
      "description": null,
      "client_reference": null,
      "metadata": {},
      "failure_code": null,
      "failure_message": null,
      "created_at": "2026-10-30T13:47:06.394Z",
      "updated_at": "2026-10-30T13:47:09.807Z"
    }
  }
}

Titulaires

cardholder.created, cardholder.kyc_updated. data.object est un titulaire. Lisez verification.status ; quand il vaut rejected, verification.reason en donne la raison (par exemple « Name/dob mismatch »).

JSON

{
  "id": "a6d29e04-5c71-4f3b-8b20-9e4f1a7c6d58",
  "object": "event",
  "type": "cardholder.kyc_updated",
  "livemode": false,
  "created_at": "2026-10-30T13:47:09.807Z",
  "data": {
    "object": {
      "id": "5df6acd9-4bac-4e19-869c-fcde6b79f389",
      "object": "cardholder",
      "livemode": false,
      "type": "customer",
      "first_name": "Awa",
      "last_name": "Ndiaye",
      "email": "awa@example.com",
      "phone": "+237670000999",
      "country": "CM",
      "city": "Douala",
      "birth_date": "1991-02-03",
      "id_document": "national_id",
      "id_number_last4": "3408",
      "verification": {
        "status": "verified",
        "reason": null,
        "verified_at": "2026-10-30T13:47:09.807Z"
      },
      "created_at": "2026-10-30T13:47:06.394Z",
      "updated_at": "2026-10-30T13:47:09.807Z"
    }
  }
}

Cartes

card.created, card.issued, card.issue_failed, card.frozen, card.unfrozen, card.terminated. data.object est une carte.

JSON

{
  "id": "c0e7b318-2d94-4a6f-b5c1-7e3d9f8a2b40",
  "object": "event",
  "type": "card.issued",
  "livemode": false,
  "created_at": "2026-10-30T13:47:09.807Z",
  "data": {
    "object": {
      "id": "ce2f0aea-7f87-4cbd-8383-03129d1253e0",
      "object": "card",
      "livemode": false,
      "type": "customer",
      "status": "active",
      "cardholder": "5df6acd9-4bac-4e19-869c-fcde6b79f389",
      "agent_name": null,
      "label": "Subscriptions",
      "network": "visa",
      "last4": "5904",
      "exp_month": 10,
      "exp_year": 2029,
      "currency": "USD",
      "balance": 950,
      "single_use": false,
      "spending_limit": {
        "amount": 20000,
        "interval": "daily"
      },
      "created_at": "2026-10-30T13:47:06.394Z",
      "terminated_at": null
    }
  }
}

Transactions de carte

card.funded, card.withdrawn, card.transaction, card.refunded, card.reversed. data.object est une transaction avec l’identifiant de la carte dans card. Les montants sont en cents de dollar, signés du point de vue de la carte : un paiement est négatif.

JSON

{
  "id": "e93f6b2a-8c15-4d7e-a204-5b1c9d3e7f86",
  "object": "event",
  "type": "card.transaction",
  "livemode": false,
  "created_at": "2026-10-30T13:47:09.807Z",
  "data": {
    "object": {
      "id": "b2d41f7e-9c3a-4e58-a1d6-7f20c4e93b15",
      "object": "transaction",
      "livemode": false,
      "type": "card_payment",
      "amount": -400,
      "currency": "USD",
      "gross": 400,
      "status": "succeeded",
      "description": "Notion",
      "counterparty": "Notion",
      "card": "ce2f0aea-7f87-4cbd-8383-03129d1253e0",
      "source": null,
      "created_at": "2026-10-30T13:47:09.807Z"
    }
  }
}

Autorisations refusées

card.authorization_declined. data.object n’est pas un objet enregistré : il décrit la tentative, avec la carte complète.

JSON

{
  "id": "1b8d4f6e-3a29-4c75-9d0e-6f2a8b5c1e97",
  "object": "event",
  "type": "card.authorization_declined",
  "livemode": false,
  "created_at": "2026-10-30T13:47:09.807Z",
  "data": {
    "object": {
      "object": "authorization",
      "card": {
        "id": "ce2f0aea-7f87-4cbd-8383-03129d1253e0",
        "object": "card",
        "livemode": false,
        "type": "customer",
        "status": "active",
        "cardholder": "5df6acd9-4bac-4e19-869c-fcde6b79f389",
        "agent_name": null,
        "label": "Subscriptions",
        "network": "visa",
        "last4": "5904",
        "exp_month": 10,
        "exp_year": 2029,
        "currency": "USD",
        "balance": 950,
        "single_use": false,
        "spending_limit": {
          "amount": 20000,
          "interval": "daily"
        },
        "created_at": "2026-10-30T13:47:06.394Z",
        "terminated_at": null
      },
      "amount": 2500,
      "currency": "USD",
      "merchant": "Notion",
      "reason": "Insufficient funds"
    }
  }
}

Champ	Description
`object`	Toujours `authorization`.
`card`	La carte, dans son état actuel.
`amount`	Montant de la tentative, en cents de dollar.
`currency`	Toujours `USD`.
`merchant`	Nom du marchand, s’il est connu.
`reason`	Motif du refus, s’il est connu.

Solde cartes

cards_balance.credited. data.object est une transaction de type cards_balance_topup.

JSON

{
  "id": "7d2c9a5f-4e81-4b36-a0f7-3c6e1b8d2a54",
  "object": "event",
  "type": "cards_balance.credited",
  "livemode": false,
  "created_at": "2026-10-30T13:47:09.807Z",
  "data": {
    "object": {
      "id": "f81c2a90-3d5e-4b7f-8e14-6a9c0b2d5e73",
      "object": "transaction",
      "livemode": false,
      "type": "cards_balance_topup",
      "amount": 500000,
      "currency": "USD",
      "gross": 500000,
      "status": "succeeded",
      "description": "USDT deposit",
      "counterparty": null,
      "card": null,
      "source": null,
      "created_at": "2026-10-30T13:47:09.807Z"
    }
  }
}

Événements webhook

Encaissements#

Paiements#

Reversements#

Titulaires#

Cartes#

Transactions de carte#

Autorisations refusées#

Solde cartes#

Encaissements

Paiements

Reversements

Titulaires

Cartes

Transactions de carte

Autorisations refusées

Solde cartes