Webhooks

Webhook events

One example payload per event family, with the exact object shapes.

Every event has the same envelope: id, object: "event", type, livemode, created_at and data.object. data.object is the object in its state when the event is delivered, in the same format as the API. The examples below are complete. The list of types is on Webhooks.

Collections

collection.succeeded, collection.failed, collection.expired. data.object is a collection. On failure, failure_code is failed or expired and failure_message may give a reason.

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

Payouts

payout.succeeded, payout.failed. data.object is a payout. On payout.failed, the amount and the fee are back on your balance.

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

Settlements

settlement.succeeded, settlement.failed. data.object is a settlement.

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

Cardholders

cardholder.created, cardholder.kyc_updated. data.object is a cardholder. Read verification.status; when it is rejected, verification.reason says why (for example “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"
    }
  }
}

Cards

card.created, card.issued, card.issue_failed, card.frozen, card.unfrozen, card.terminated. data.object is a card.

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

Card transactions

card.funded, card.withdrawn, card.transaction, card.refunded, card.reversed. data.object is a transaction with the card ID in card. Amounts are in US cents, signed from the card’s point of view: a payment is negative.

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

Declined authorizations

card.authorization_declined. data.object is not a stored object: it describes the attempt, with the full card.

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

Field	Description
`object`	Always `authorization`.
`card`	The card, in its current state.
`amount`	Amount of the attempt, in US cents.
`currency`	Always `USD`.
`merchant`	Merchant name, when known.
`reason`	Why the attempt was declined, when known.

Cards balance

cards_balance.credited. data.object is a transaction of 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"
    }
  }
}

Webhook events

Collections#

Payouts#

Settlements#

Cardholders#

Cards#

Card transactions#

Declined authorizations#

Cards balance#

Collections

Payouts

Settlements

Cardholders

Cards

Card transactions

Declined authorizations

Cards balance