Webhooks

Kazza uses webhooks to notify your server in real time whenever a payment event occurs. These webhooks ensure you always have the most up-to-date transaction status without needing to continuously pol

🔔 Event Types

1. incoming_deposit_transaction_confirmation

Triggered when a payment has been detected on the blockchain, but is still awaiting required confirmations.

Payload Example

{
  "received_amount": "1.35612",
  "currency": "USDC",
  "network": "BASE",
  "event_type": "incoming_deposit_transaction_confirmation",
  "expected_amount": "1.35612",
  "reference_id": "checkout_12345",
  "payment_transaction": {
    "status": "pending",
    "confirmations": 2,
    "required_confirmations": 12,
    "transaction_hash": "0xabc123def456..."
  }
}

---

2. deposit_transaction_confirmed

Triggered when the deposit has received all required confirmations and is now finalized.

Payload Example

{
  "received_amount": "1.35612",
  "currency": "USDC",
  "network": "BASE",
  "event_type": "deposit_transaction_confirmed",
  "reference_id": "checkout_12345",
  "payment_transaction": {
    "status": "confirmed",
    "confirmations": 12,
    "required_confirmations": 12,
    "transaction_hash": "0xabc123def456..."
  }
}

---

📌 Field Definitions

Field	Type	Description
received_amount	string	Actual amount received on-chain.
expected_amount	string	Expected crypto amount (only present in incoming_deposit_transaction_confirmation).
currency	string	Currency code of the payment (e.g., USDC, USDT).
network	string	Blockchain/network the payment was made on (e.g., BASE, POLYGON, SOLANA).
event_type	string	Type of webhook event.
reference_id	string	Unique merchant reference ID provided during checkout.
payment_transaction	object	Detailed information about the blockchain transaction.
└ status	string	Transaction status (pending, confirmed).
└ confirmations	number	Number of confirmations received so far.
└ required_confirmations	number	Number of confirmations required for finality.
└ transaction_hash	string	Unique blockchain transaction hash (TXID).

---

🧑‍💻 Developer Notes

• Always use the reference_id to reconcile payments with your orders.

• Your webhook endpoint must return HTTP 200 OK to acknowledge receipt.

• If you fail to acknowledge, Kazza will retry webhook delivery.

• Handle idempotency: the same webhook may be sent more than once. Ensure your system processes each transaction once.

• Treat incoming_deposit_transaction_confirmation as informational. Only mark orders as paid after receiving deposit_transaction_confirmed.