transaction.failed

Sent when a transaction fails. Payment was not completed and no funds were transferred.

When it triggers

• Blockchain transaction failed

• Transaction reverted

• Insufficient gas

• Other blockchain errors

Payload

{
  "id": "evt_1704067320000_ghi789",
  "type": "transaction.failed",
  "createdAt": "2025-01-25T10:02:00.000Z",
  "data": {
    "_id": "689324309eb9e6e8e0f842cd",
    "price": 0.015,
    "hash": "0xb6accc136297ad17ab831028f967cbf2bdd9ff67b8fab5d4e8e4f34f8681eb59",
    "status": "Failed",
    "type": "Contract",
    "user": {
      "_id": "688c82d81c6a157748c5ca7b",
      "username": "john_doe"
    },
    "link": "6891c0896aad1cd3bf2f3490",
    "source": "7",
    "createdAt": "2025-01-25T10:00:00.000Z",
    "updatedAt": "2025-01-25T10:02:00.000Z",
    "error": "Transaction reverted due to insufficient gas"
  }
}

Fields

Field	Type	Description
_id	string	Transaction ID
price	number	Amount attempted
hash	string	Blockchain transaction hash
status	string	Always "Failed"
user._id	string	User ID
user.username	string	Username
link	string	Payment link ID
source	string	Source chain ID
error	string	Error message
createdAt	string	When transaction was created
updatedAt	string	When transaction failed

What to do

• Update order status to failed

• Release inventory reservations

• Notify user about the failure

• Log error for debugging

• Offer retry or alternative payment method

What NOT to do

• ❌ Don't fulfill the order

• ❌ Don't charge the user again automatically

• ❌ Don't panic - transaction failures happen

Example handler

async function handleTransactionFailed(transaction) {
  // Update order status
  await db.orders.update(
    { transactionId: transaction._id },
    {
      status: 'failed',
      error: transaction.error,
      failedAt: new Date()
    }
  );
  // Notify user
  await sendEmail(transaction.user.username, {
    subject: 'Payment Failed',
    body: `Your payment failed: ${transaction.error}. Please try again.`,
    retryLink: `https://checkout.kira-pay.com/${order.id}`
  });

  console.log(`Transaction ${transaction._id} failed: ${transaction.error}`);
}