Transaction events

Transaction events fire when a transaction is created and whenever its status changes.

`transaction_created`

Sent as soon as the transaction record exists, before any money has moved.

{
  "event": "transaction_created",
  "data": {
    "transactionId": "BeOfXV1NVIcZlsSVeQAF",
    "status": "pending",
    "type": "withdrew",
    "externalReference": "unique-ref"
  },
  "timestamp": "2024-10-03T16:33:14.600Z"
}

`transaction_updated`

Sent on every status change, and whenever the transaction needs the customer to do something.

Full shape

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "string",
    "status": "string",
    "type": "string",
    "externalReference": "string",
    "stepRequired": "string",
    "redirectUrl": "https://test-redirect.com",
    "method": "string",
    "thirdPartyReference": "string",
    "note": "string",
    "originalTransactionId": "string"
  },
  "timestamp": "ISO-8601 timestamp"
}

Field	Notes
`stepRequired`	Optional. e.g. `otp`, `redirect`, `pin`, `address_verification`
`redirectUrl`	Provided when `stepRequired` is `redirect`
`method`	Optional. e.g. `momo`, `bank`, `card`, `opay`
`thirdPartyReference`	Optional. e.g. an M-Pesa reference
`note`	Optional. Often carries the error or provider message
`originalTransactionId`	Returned on refund transaction updates only

Terminal outcomes

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "BeOfXV1NVIcZlsSVeQAF",
    "status": "successful",
    "type": "deposit",
    "externalReference": "order_12345",
    "method": "momo",
    "thirdPartyReference": "TEQTEYRU"
  },
  "timestamp": "2024-10-03T16:34:02.100Z"
}

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "BeOfXV1NVIcZlsSVeQAF",
    "status": "failed",
    "type": "deposit",
    "externalReference": "order_12345",
    "method": "momo",
    "note": "User could not be reached by stk"
  },
  "timestamp": "2024-10-03T16:34:02.100Z"
}

Step required

These arrive with status: "pending" — the transaction is paused waiting on the customer, not failed.

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "test123",
    "status": "pending",
    "type": "deposit",
    "externalReference": "mnvmcvcmvlc",
    "stepRequired": "redirect",
    "redirectUrl": "https://test-redirect.com",
    "method": "momo"
  },
  "timestamp": "ISO-8601 timestamp"
}

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "test123",
    "status": "pending",
    "type": "deposit",
    "externalReference": "mnvmcvcmvlc",
    "stepRequired": "otp",
    "method": "momo"
  },
  "timestamp": "ISO-8601 timestamp"
}

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "luQybnMnvjgnWEF6ZFyJ",
    "status": "pending",
    "type": "deposit",
    "externalReference": "1234567890",
    "stepRequired": "pin",
    "method": "card"
  },
  "timestamp": "2026-03-05T19:39:30.624Z"
}

How to act on each value is covered in charges overview.

Refund updates

Refunds use the standard transaction_updated event with type: "refund". Here transactionId is the refund transaction, and originalTransactionId is the deposit being reversed.

Refund successful

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "unique-refund-transaction-id",
    "originalTransactionId": "lBK9bMny2gs4hLsG3XGq",
    "status": "successful",
    "type": "refund",
    "externalReference": "refund_order_12345",
    "amount": 25,
    "currency": "KES",
    "method": "momo"
  },
  "timestamp": "ISO-8601 timestamp"
}

Match refunds back to the original order through originalTransactionId, not transactionId — the latter is a new transaction in its own right.

Status values

Status	Meaning
`pending`	The transaction is being processed.
`successful`	The transaction completed successfully.
`failed`	The transaction failed.

Only successful means funds moved. A pending event carrying a stepRequired value is a request for customer action, not an outcome — keep waiting for a terminal status.

Testing your handler

Use Simulate Webhook in the sandbox to fire any of these shapes at your endpoint on demand, without needing to drive a real transaction into the matching state.

Get Started

Before You Build

Charges

Payouts

Webhooks

Testing

Errors

Transaction events

`transaction_created`

`transaction_updated`

Terminal outcomes

Step required

Refund updates

Status values

Testing your handler

​transaction_created

​transaction_updated

​Terminal outcomes

​Step required

​Refund updates

​Status values

​Testing your handler

`transaction_created`

`transaction_updated`

Terminal outcomes

Step required

Refund updates

Status values

Testing your handler