Invoices
Invoice webhook events and example payloads.
Invoice webhooks track invoice creation, updates, payment, and expiry.
Use these events to keep invoice state in sync with your system.
Field descriptions
Invoice webhook events use data.invoice.
Some invoice events also include data.payments.
data.invoice.id
string
Unique invoice identifier.
data.invoice.reference
string
Your invoice reference.
data.invoice.amount
string
Invoice amount as a decimal string.
data.invoice.amountPaid
string
Amount paid so far.
data.invoice.currency
string
Invoice currency.
data.invoice.status
string
Invoice payment status.
data.invoice.isRefunded
boolean
Whether the invoice has been refunded.
data.invoice.state
'open' | 'closed'
Invoice state.
data.invoice.description
string | null
Optional invoice description.
data.invoice.expiresAt
string | null
Expiry timestamp.
data.invoice.paidAt
string | null
Paid timestamp when available.
data.invoice.periodStart
string | null
Billing period start when applicable.
data.invoice.periodEnd
string | null
Billing period end when applicable.
data.invoice.nextPaymentDate
string | null
Next scheduled payment date.
data.invoice.metadata
object | null
Custom metadata.
data.invoice.successUrl
string
Redirect URL used after success.
data.invoice.cancelUrl
string
Redirect URL used after cancellation.
data.invoice.customer
object
Customer information.
data.invoice.customer.telegramId
string | null
Customer Telegram ID when available.
data.invoice.createdAt
string
Creation timestamp.
data.invoice.updatedAt
string
Last update timestamp.
data.payments
array | null
Payment activity linked to the invoice.
Events
invoice.createdinvoice.updatedinvoice.paidinvoice.expired
invoice.created
Sent when an invoice is created.
Use this event to create an invoice record or start an expiry timer.
invoice.updated
Sent when an invoice receives a payment or changes state.
Use this event to refresh totals and partial payment state.
invoice.paid
Sent when an invoice is fully paid.
Use this event to fulfill the order.
invoice.expired
Sent when an invoice expires.
Use this event to close unpaid invoices.
Last updated
Was this helpful?