Transactions

Transaction webhook events and example payloads.

Transaction webhooks track blockchain activity for incoming payments.

Use these events to monitor on-chain state before payment state is finalized.

Field descriptions

Transaction webhook events use data.transaction.

They also include data.session for the related payment session.

Transaction object

Field	Type	Description
data.transaction.id	string	Unique transaction identifier.
data.transaction.txHash	string	Blockchain transaction hash.
data.transaction.fromAddress	string	Sender address.
data.transaction.toAddress	string	Destination address.
data.transaction.amount	string	Crypto amount received.
data.transaction.asset	string	Crypto asset code.
data.transaction.chain	string	Blockchain network.
data.transaction.status	string	Transaction status.
data.transaction.confirmations	number	Confirmation count.
data.transaction.createdAt	string	Detection timestamp.
data.transaction.confirmedAt	string | null	Confirmation timestamp.
data.transaction.failureReason	string | null	Failure reason when present.

Related session object

Field	Type	Description
data.session.id	string	Related session identifier.
data.session.reference	string	Your order or payment reference.
data.session.title	string	Session title.
data.session.description	string | null	Optional session description.
data.session.state	'open' | 'closed'	Session state.
data.session.type	string	Session type.
data.session.amount	string	Requested amount.
data.session.currency	string	Requested currency.
data.session.settlements	object | null	Settlement breakdown.
data.session.payment.status	string	Payment status inside the related session.
data.session.payment.asset	string	Crypto asset code.
data.session.payment.chain	string	Blockchain network.
data.session.payment.amount	string	Required crypto amount.
data.session.payment.amountReceived	string	Amount received so far.
data.session.payment.conversionRate	string	Fiat to crypto conversion rate used.
data.session.payment.gasFee	string	Network gas fee.
data.session.payment.address	string	Deposit address.
data.session.payment.feePaidBy	'merchant' | 'customer'	Who pays the network fee.
data.session.customer	object	Customer information.
data.session.metadata	object | null	Custom metadata.
data.session.successUrl	string	Redirect URL used after success.
data.session.cancelUrl	string	Redirect URL used after cancellation.
data.session.createdAt	string	Session creation timestamp.
data.session.expiresAt	string	Session expiry timestamp.
data.session.completedAt	string | null	Session completion timestamp.

The related data.session object uses the same shape as payment webhook events.

Events

• transaction.received
• transaction.confirmed

transaction.received

Sent when an incoming transaction is first detected on-chain.

Use this event for early detection.

Do not treat it as final confirmation.

{
  "event": "transaction.received",
  "data": {
    "transaction": {
      "id": "tx_123",
      "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "fromAddress": "0x1234567890abcdef1234567890abcdef12345678",
      "toAddress": "0xabcdef1234567890abcdef1234567890abcdef1234",
      "confirmations": 1,
      "amount": "100.55",
      "asset": "USDT",
      "chain": "ethereum",
      "status": "pending",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "confirmedAt": null,
      "failureReason": null
    },
    "session": {
      "id": "cs_123456789_abcdef",
      "reference": "ORDER-2024-001",
      "title": "Order #2024-001",
      "description": "Payment for premium subscription",
      "state": "open",
      "type": "payment",
      "amount": "100.00",
      "currency": "USD",
      "settlements": null,
      "payment": {
        "status": "pending",
        "asset": "USDT",
        "chain": "ethereum",
        "amount": "100.55",
        "amountReceived": "0",
        "conversionRate": "1.0055",
        "gasFee": "0.05",
        "address": "0x1234567890abcdef1234567890abcdef12345678",
        "feePaidBy": "customer"
      },
      "customer": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "email": "[e-mail]",
        "phone": "[phone]",
        "firstName": "John",
        "lastName": "Doe"
      },
      "metadata": {
        "orderId": "ORDER-2024-001",
        "userId": "user_123"
      },
      "successUrl": "https://example.com/success",
      "cancelUrl": "https://example.com/cancel",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "expiresAt": "2024-01-15T11:30:00.000Z",
      "completedAt": "2024-01-15T10:35:00.000Z"
    }
  }
}

transaction.confirmed

Sent when a transaction reaches the required confirmation count.

Use this event when you need confirmed blockchain state.

{
  "event": "transaction.confirmed",
  "data": {
    "transaction": {
      "id": "tx_123",
      "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "fromAddress": "0x1234567890abcdef1234567890abcdef12345678",
      "toAddress": "0xabcdef1234567890abcdef1234567890abcdef1234",
      "confirmations": 12,
      "amount": "100.55",
      "asset": "USDT",
      "chain": "ethereum",
      "status": "confirmed",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "confirmedAt": "2024-01-15T10:35:00.000Z",
      "failureReason": null
    },
    "session": {
      "id": "cs_123456789_abcdef",
      "reference": "ORDER-2024-001",
      "title": "Order #2024-001",
      "description": "Payment for premium subscription",
      "state": "open",
      "type": "payment",
      "amount": "100.00",
      "currency": "USD",
      "settlements": null,
      "payment": {
        "status": "pending",
        "asset": "USDT",
        "chain": "ethereum",
        "amount": "100.55",
        "amountReceived": "100.55",
        "conversionRate": "1.0055",
        "gasFee": "0.05",
        "address": "0x1234567890abcdef1234567890abcdef12345678",
        "feePaidBy": "customer"
      },
      "customer": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "email": "[e-mail]",
        "phone": "[phone]",
        "firstName": "John",
        "lastName": "Doe"
      },
      "metadata": {
        "orderId": "ORDER-2024-001",
        "userId": "user_123"
      },
      "successUrl": "https://example.com/success",
      "cancelUrl": "https://example.com/cancel",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "expiresAt": "2024-01-15T11:30:00.000Z",
      "completedAt": "2024-01-15T10:35:00.000Z"
    }
  }
}