Invoice Webhooks

Webhook notifications for invoices are based on the webhook notification type provided when creating the invoice. Currently supported webhook types for invoices are:

• invoice.paid: Notification for a successfully paid invoice event. This event is triggered after the payment of an invoice, but it does not mean the invoice has been completed. Rely only on the invoice.completed event notification for confirmation.
• invoice.partial_completed: The invoice has experienced a partial payment during its validity period, but the amount paid is less than the total invoice amount. Merchants MUST use the paidAmount field to ascertain the current paid amount.
• invoice.completed: Notification for a completed invoice event. This event is triggered after the completion of an invoice, representing the confirmation that the invoice has been successfully completed.
• invoice.expired: Notification for an expired invoice event. This event is triggered after an invoice has expired, representing that the invoice has expired.

Important Read:

The invoice.partial_completed type indicates that the payment ticket has not been fully paid. You MUST use the paidAmount field rather than the overall totalAmount to obtain the precise paid amount for your logic processing.

The data returned for invoice.paid, invoice.partial_completed, and invoice.completed is identically structured as follows:

Field	Type	Description
invoiceId	string	Invoice ID
merOrderId	string	Merchant-side merchant order number
fiat	string	ISO 4217 3-character currency code
currency	string	Cryptocurrency currency, e.g., USDT, BTC, etc. View the currency list
fiatAmount	decimal	The fiat amount required for payment of this invoice
paidAmount	decimal	The cryptocurrency amount that has been paid
totalAmount	decimal	The cryptocurrency amount required for payment of this invoice
currencyExchange	decimal	If this invoice is converted to a cryptocurrency type, the current exchange rate will be displayed
tradeTime	long	Payment timestamp
channel	string	Payment channel (biqu_pay: BasicEx Pay, chain_pay: Chain Pay)
metadata	map	Structured metadata passed in for the merchant's own record, which will be returned as-is in subsequent responses
chainPaymentInfo	InvoiceChainPaymentInfo	Information about the chain payment if chain payment is used

InvoiceChainPaymentInfo

Field	Type	Description
network	string	The chain network the user paid with
payerAddress	string	The wallet address or ID that the user uses to make payments
payeeAddress	string	The recipient address
transactionId	string	Transaction ID of the user's payment on the public chain
blockHash	string	Block hash of the user's transaction packed on the chain
blockHeight	long	Block height of the user's transaction packed on the chain
packageTime	long	Package time of the user's transaction packed on the chain