Invoice webhooks

Overview

Invoice webhooks notify the merchant system about invoice creation, payment detection, compliance checks, intervention cases, expiration, and final processing 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 SINGLE or SINGLE_FIAT invoice creation	A SINGLE or SINGLE_FIAT invoice was created.
INVOICE_CREATE_UNLIMITED_INVOICE	Required for UNLIMITED invoice creation	An UNLIMITED invoice was created.
INVOICE_CREATE_UNLIMITED_LINKED_INVOICE	Required for UNLIMITED_LINKED invoice creation	An UNLIMITED_LINKED invoice was created.
INVOICE_CREATE_BOUND_INVOICE	Required for BOUND invoice creation	A BOUND invoice was created.
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.

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 events
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	External ID used during invoice creation.
externalId	string	Merchant-side invoice ID, if provided during invoice 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 crypto currency.
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 events	Save the invoice ID and idempotencyKey in the merchant system.
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 the invoice details. This is a conditional branch after funds are received, not a mandatory event for every 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 invoice 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 via API	How to create an Invoice via API
Manage interventions	How to manage interventions via API
Webhook API reference	Webhook API