Refunds

Refund webhook events and example payloads.

Refund webhooks track refund creation, completion, and failure.

Use these events to keep refund state in sync with your support and ledger systems.

Field descriptions

Refund webhook events use data.refund.

Field	Type	Description
data.refund.id	string	Unique refund identifier.
data.refund.entity	string	Source entity, such as a session or invoice.
data.refund.reference	string	Refunded session or invoice reference.
data.refund.status	string	Refund status.
data.refund.reason	string | null	Refund reason.
data.refund.chain	string	Blockchain network.
data.refund.asset	string	Crypto asset code.
data.refund.amount	string	Refunded crypto amount.
data.refund.fee	string	Refund fee.
data.refund.feePaidBy	'merchant' | 'customer'	Who pays the refund fee.
data.refund.balanceSource	string	Balance source used for the refund.
data.refund.fiatAmount	string	Fiat equivalent of the refund.
data.refund.fiatCurrency	string	Fiat currency.
data.refund.refundAddress	string	Destination wallet address.
data.refund.txHash	string | null	Blockchain transaction hash when available.
data.refund.explorerUrl	string | null	Block explorer URL.
data.refund.createdAt	string	Creation timestamp.
data.refund.completedAt	string | null	Completion timestamp for successful refunds.
data.refund.failureReason	string | null	Failure reason for failed refunds.

Events

• refund.created
• refund.success
• refund.failed

refund.created

Sent when a refund is created.

Use this event to start refund tracking.

{
  "event": "refund.created",
  "data": {
    "refund": {
      "id": "ref_12345678-1234-1234-1234-123456789abc",
      "entity": "session",
      "reference": "cs_1234567890",
      "status": "pending",
      "reason": "Customer requested refund",
      "chain": "tron",
      "asset": "USDT",
      "amount": "49.50000000",
      "fee": "0.50000000",
      "feePaidBy": "customer",
      "balanceSource": "merchantBalance",
      "fiatAmount": "10000.00",
      "fiatCurrency": "NGN",
      "refundAddress": "TXyz1234567890abcdef",
      "txHash": null,
      "explorerUrl": null,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "completedAt": null,
      "failureReason": null
    }
  }
}

refund.success

Sent when a refund completes successfully.

Use this event to mark the refund as settled.

{
  "event": "refund.success",
  "data": {
    "refund": {
      "id": "ref_12345678-1234-1234-1234-123456789abc",
      "entity": "session",
      "reference": "cs_1234567890",
      "status": "success",
      "reason": "Customer requested refund",
      "chain": "tron",
      "asset": "USDT",
      "amount": "49.50000000",
      "fee": "0.50000000",
      "feePaidBy": "customer",
      "balanceSource": "merchantBalance",
      "fiatAmount": "10000.00",
      "fiatCurrency": "NGN",
      "refundAddress": "TXyz1234567890abcdef",
      "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "explorerUrl": "https://tronscan.org/#/transaction/0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "completedAt": "2024-01-15T10:45:00.000Z",
      "failureReason": null
    }
  }
}

refund.failed

Sent when a refund fails.

Use this event to notify support or retry with a corrected address.

Check data.refund.failureReason when a refund fails.

{
  "event": "refund.failed",
  "data": {
    "refund": {
      "id": "ref_12345678-1234-1234-1234-123456789abc",
      "entity": "session",
      "reference": "cs_1234567890",
      "status": "failed",
      "reason": "Customer requested refund",
      "chain": "tron",
      "asset": "USDT",
      "amount": "49.50000000",
      "fee": "0.50000000",
      "feePaidBy": "customer",
      "balanceSource": "merchantBalance",
      "fiatAmount": "10000.00",
      "fiatCurrency": "NGN",
      "refundAddress": "TXyz1234567890abcdef",
      "txHash": null,
      "explorerUrl": null,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "completedAt": null,
      "failureReason": "Invalid address"
    }
  }
}