Transaction Events

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

Failed off-ramp with automatic refund:

Automatic off-ramp refunds use the original type: "offramp" transaction. The failed webhook confirms that the fiat payout failed and may arrive before the on-chain refund is submitted:

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "zQQvoWnhYED3yXYEo7y7",
    "status": "failed",
    "type": "offramp",
    "externalReference": "offramp_user_001",
    "method": "momo",
    "depositAddress": "0x318aa0c46120bb214f7da0d53183d0b1c9be7047",
    "txId": "0xc3acfde7f212fcb902045119ee41299249ca153fc5c2730b0e8adba749846b53",
    "note": "Payout failed."
  },
  "timestamp": "ISO-8601 timestamp"
}

status: "failed" is not refund confirmation. Honeycoin does not send a separate refund webhook when the original off-ramp's refundTransactionHash is added. Query GET /api/b2b/transactions/{transactionId} and treat the refund as confirmed only when refundTransactionHash is present.

If the failed off-ramp has no deposit txId, Honeycoin did not detect crypto for that transaction and no automatic refund is created.

Status Values:

pending: Transaction is being processed.
successful: Transaction successfully completed.
failed: Transaction failed.