How to manage interventions via API

Overview

Intervention is a manual review flow for invoice payments where the received amount does not match the expected invoice amount.

Interventions are relevant only for SINGLE and SINGLE_FIAT invoices.

Intervention types

Type	Meaning
UNDERPAY	The customer paid less than the required invoice amount.
OVERPAY	The customer paid more than the required invoice amount.

When an intervention is required, the invoice state changes to PENDING_INTERVENTION, and the invoice contains:

Field	Meaning
interventionType	UNDERPAY or OVERPAY.
isInterventionResolved	Shows whether the merchant has resolved the intervention with the customer.

Integration flow

1. Subscribe to the INVOICE_PENDING_INTERVENTION webhook event.
2. When the webhook is received, get the invoice details by using [POST] invoice.
3. Check state, interventionType, amount, totalDebitAmount, and isInterventionResolved.
4. Decide whether to accept the received amount and continue processing.
5. If you accept the payment, resolve the intervention by using [POST] invoice/return-to-paid.
6. After the customer-facing case is handled, mark the intervention as resolved by using [POST] invoice/close-intervention.

Subscribe to intervention webhooks

Use [POST] subscription/webhook/create and subscribe to INVOICE_PENDING_INTERVENTION.

{
  "timestamp": 1761650432438,
  "account": "0x0000000000000000000000000000000000000000",
  "payload": {
    "notificationEventTypes": [
      "INVOICE_PENDING_INTERVENTION"
    ],
    "requestId": "bf9348b7-2c14-46d7-868c-b597852da319",
    "url": "https://merchant.com/webhooks/calypso"
  }
}

Webhook example

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

Check invoice details

Use [POST] invoice to get the current invoice state.

Field	Expected value during intervention
state	PENDING_INTERVENTION
interventionType	UNDERPAY or OVERPAY
isInterventionResolved	false
totalDebitAmount	Amount received on the invoice address.
amount	Expected invoice amount.

Resolve intervention

If the merchant accepts the received amount, use [POST] invoice/return-to-paid.

After the request is processed, the invoice state changes to PAID, and the invoice can continue through the normal processing flow.

Close intervention

Use [POST] invoice/close-intervention when the case has been resolved with the customer.

This request changes isInterventionResolved to true. It marks the intervention case as handled, but it does not replace invoice payment processing.

Related docs

Document	Link
Create invoice via API	How to create an Invoice via API
Invoice webhooks	Invoice webhooks
Webhook API reference	Webhook API