Guides

Transaction Events

Triggered when a transaction's status changes.

transaction_created:

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

transaction_updated:

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "string",
    "status": "string",
    "type": "string",
    "externalReference": "string",
    "stepRequired": "string", // optional e.g otp, redirect.
    "redirectUrl": "https//test-redirect.com", // provided when stepRequired is "redirect"
    "method": "string", // optional e.g momo, bank etc
    "thirdPartyReference": "string", // optional. e.g Mpesa reference
    "note": "string", // optional. e.g error message,
    "txId": "string", // optional e.g offramp/onramp transaction hashes
    "originalTransactionId": "string" // optional, only returned on refund transaction updates
  },
  "timestamp": "ISO-8601 timestamp"
}
{
  "event": "transaction_updated",
  "data": {
    "transactionId": "test123",
    "status": "pending",
    "type": "deposit",
    "externalReference": "mnvmcvcmvlc",
    "stepRequired": "redirect",
    "redirectUrl": "https//test-redirect.com",
		"method": "momo"// optional e.g momo, bank etc
  },
  "timestamp": "ISO-8601 timestamp"
}
{
  "event": "transaction_updated",
  "data": {
    "transactionId": "test123",
    "status": "pending",
    "type": "deposit",
    "externalReference": "mnvmcvcmvlc",
    "stepRequired": "otp",
		"method": "momo" // optional e.g momo, bank etc
  },
  "timestamp": "ISO-8601 timestamp"
}

Refund transaction update:

Refunds use the standard transaction_updated event. In the payload, transactionId is the refund transaction ID and originalTransactionId is the original deposit transaction being refunded.

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

Status Values:

  1. pending: Transaction is being processed.
  2. successful: Transaction successfully completed.
  3. failed: Transaction failed.