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",
    "amount": 100,
    "currency": "KES",
    "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"
}

Amounts and fees

The webhook includes amount and currency. For a standard collection, these represent the amount collected on the source side (senderAmount and senderCurrency). The webhook amount is not adjusted for HoneyCoin fees.

When you need the receiving-side amount or fee details, retrieve the transaction with Get Transaction. For standard collections, receiverAmount is the gross receiving-side amount after any currency conversion, while fees are returned separately as fee.feeAmount and fee.currency.

For a successful collection:

If fee.currency and receiverCurrency are the same, the net amount added to your HoneyCoin balance is receiverAmount - fee.feeAmount.
If the currencies differ, treat the received amount and fee as separate movements in their respective currencies.

Whether you credit your customer the gross receiverAmount or an amount adjusted for fees depends on your own fee policy.

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "test123",
    "amount": 100,
    "currency": "KES",
    "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",
    "amount": 100,
    "currency": "KES",
    "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.