Invoice Payment Widget webhooks

Overview

Invoice Payment Widget creates invoices. Payment status changes for these invoices are delivered through Invoice webhook events.

Use webhooks as the main way to update order status in the merchant system. If you need to verify the current invoice state, use [POST] invoice.

Event types

Event type	Delivery	When it is sent
INVOICE_CREATE_INVOICE	Required for invoice creation from widget	An invoice was created from a SINGLE_FIAT widget.
INVOICE_MEM_POOL_FOUND	Optional	A transaction was detected in the blockchain mempool. This event is not guaranteed.
INVOICE_PENDING_COMPLIANCE	Optional	A detected transaction is under compliance review. This event may be skipped if the transaction automatically passes compliance.
INVOICE_COMPLIANCE_DECLINED	Required for negative compliance result	A transaction was declined by compliance.
INVOICE_FUNDS_RECEIVED_FOR_INVOICE	Required for received invoice funds	Funds were received on the invoice address. This confirms the deposit, but it may be followed by an intervention or final payment event.
INVOICE_PENDING_INTERVENTION	Optional, conditional	The invoice requires merchant intervention, usually because of underpay or overpay. This event is sent only when intervention is required.
INVOICE_PAID	Required for successful invoice payment	The invoice reached the successful customer-facing payment result.
INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED	Required when funds are credited	Funds were transferred from the invoice address to the merchant account balance.
INVOICE_EXPIRED	Required when invoice expires before successful payment	The invoice expiration date passed before successful payment.
INVOICE_FAILED	Required when invoice processing fails	Invoice processing failed.

Widget, invoice, and webhook identifiers

Identifier	Where it appears	How to use it
Widget idempotencyKey	Payment Widget API response and widgetKey URL parameter.	Opens the widget page.
invoiceIdempotencyKey	invoices array in Payment Widget API response.	Checks the created invoice through Invoice API.
Webhook data.idempotencyKey	Invoice webhook payload.	Identifies the invoice related to the webhook event.
externalId	Payment widget and invoice objects, if provided during creation.	Maps Calypso objects to merchant-side orders or customers.

Invoice state and webhook event names

The invoice state field and webhook eventType are related, but they are not identical.

Invoice state	Related webhook event
PENDING_PAYMENT	Invoice creation event
MEM_POOL_FOUND	INVOICE_MEM_POOL_FOUND
PENDING_COMPLIANCE_CHECK	INVOICE_PENDING_COMPLIANCE, optional intermediate event
DECLINED	INVOICE_COMPLIANCE_DECLINED, terminal negative compliance result
PENDING_INTERVENTION	INVOICE_PENDING_INTERVENTION
PAID	INVOICE_PAID
COMPLETED	INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED
ARCHIVED	INVOICE_EXPIRED or archive-related processing
CANCEL	Cancellation-related processing
REVERSED	Reversal-related processing

Webhook event types use the INVOICE_ prefix. Invoice states returned in state do not use this prefix.

Webhook payload structure

Each webhook request contains a common envelope and an event-specific data object.

Field	Type	Description
requestId	string	Webhook request ID.
id	number	Calypso webhook event ID.
createdDate	string	Event creation date and time.
level	string	Event level, for example SUCCESS.
service	string	Service that produced the event. For invoice events, the value is INVOICE.
eventType	string	Invoice webhook event type.
data	object	Event-specific invoice data.

Common data fields

Field	Type	Description
type	string	Event type. Usually matches eventType.
parentExternalId	string or number	Calypso invoice ID.
idempotencyKey	string	Invoice idempotencyKey.
externalId	string	Merchant-side ID, if provided during widget creation.
message	string	Invoice text or description.
description	string	Invoice description, if included in the event.
createdDate	string	Invoice creation date and time, if included in the event.

Payment-related data fields

Field	Type	Description
amount	number	Expected invoice amount or received amount, depending on event type.
realAmount	number	Actual amount paid by the customer.
currency	string	Invoice cryptocurrency.
fiatAmount	number or object	Fiat invoice amount, if applicable.
fiatCurrency	string	Fiat currency, if applicable.
transactionId	array	Calypso deposit IDs related to the event.
transactionIds	array	Calypso deposit IDs related to the event.
transactionHash	string	Blockchain transaction hash.
senderAddress	string	Address that sent funds to the invoice.
invoiceAddress	string	Invoice address that received funds.
paymentDate	string	Deposit transaction creation date and time.
serviceFee	number	Service fee for the invoice deposit.
expirationDate	string	Invoice expiration date and time.

Webhook example

{
  "requestId": "bf9348b7-2c14-46d7-868c-b597852da319",
  "id": 3,
  "createdDate": "2026-06-29T12:13:05.909616",
  "level": "SUCCESS",
  "service": "INVOICE",
  "eventType": "INVOICE_PAID",
  "data": {
    "type": "INVOICE_PAID",
    "parentExternalId": "d9732536-acdd-41bd-87c3-ec40aeeb6a37",
    "idempotencyKey": "5b0ca8da-6af4-4a1c-9efd-5cbfc19ace09",
    "externalId": "order-1001",
    "amount": 100,
    "realAmount": 100,
    "currency": "USDT_TRX",
    "description": "Order #1001"
  }
}

Recommended handling

Event	Recommended merchant action
Invoice creation event	Save the invoice ID and invoice idempotencyKey.
INVOICE_MEM_POOL_FOUND	Show that payment was detected but is not confirmed yet.
INVOICE_PENDING_COMPLIANCE	Keep the order in pending status if this optional webhook is received. It may be skipped when compliance passes automatically.
INVOICE_COMPLIANCE_DECLINED	Mark the payment as declined and follow internal support or refund procedures. This is the terminal webhook for a negative compliance result.
INVOICE_FUNDS_RECEIVED_FOR_INVOICE	Record the received deposit and wait for the next invoice status event. Do not treat this event alone as the final successful payment result.
INVOICE_PENDING_INTERVENTION	Start the intervention flow and check invoice details. This is a conditional branch after funds are received, not a mandatory event for every widget invoice.
INVOICE_PAID	Mark the invoice payment as successful from the customer payment perspective.
INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED	Mark funds as credited to the merchant account balance.
INVOICE_EXPIRED	Stop accepting payment for this invoice and create a new widget if payment is still required.
INVOICE_FAILED	Mark the invoice as failed and verify the current state through [POST] invoice.

Related docs

Document	Link
Create Invoice Payment Widget via API	How to create an Invoice Payment Widget via API
Manage invoice interventions	How to manage interventions via API
Webhook API reference	Webhook API