Invoice and deposit status

Read the invoice or deposit state through GET requests. Webhooks notify you of changes automatically.

Read an invoice or deposit

Use the id returned when you created the invoice or deposit:

curl 'https://platform.invoise.me/api/v1/shops/{shop_id}/issuances/{issuance_id}' \
  -H 'Authorization: Bearer ivk_...'

Relevant fields from an example response (other fields omitted):

{
  "id": "f06b8a31-19c7-4687-ade3-1c09466d2751",
  "kind": "invoice",
  "status": "funded",
  "amount": "10000000",
  "received": "10000000",
  "token_decimals": 6,
  "expires_at": "2026-10-19T10:00:00Z",
  "cancelled_at": null,
  "disabled_at": null,
  "payout_tx_hash": null
}

Both amounts are integer strings in base units. This example means 10 tokens arrived, but no confirmed payout transaction is shown yet.

Interpret an invoice

status	What to do
registering	Wait for a non-empty address. Do not derive one yourself.
open	Keep waiting. received may show a partial payment.
funded	Enough confirmed funds are available for settlement.
settled	The invoice has closed on chain.
reconciling	Wait for reconciliation; do not treat it as a successful payment.

Also check cancelled_at. It is a timestamp or null, not a status value. It is set when you cancel the invoice, when an unpaid invoice passes its expires_at, or when Invoise staff block the merchant; the invoice.cancelled webhook tells these apart by data.reason. Cancellation hides the checkout but does not stop incoming funds or settlement. Decide explicitly how your business handles a paid, cancelled invoice.

funded means payment received, not payout completed. settled records invoice closure. For complete payout accounting, use payout.confirmed; payout_tx_hash identifies the latest confirmed outgoing transfer to the recipient when available.

If you receive transfer.reverted, Invoise is reporting the reversal of a specific incoming transfer on the network. Identify it through chain_event.reference_event_id, read the invoice’s current state and adjust your record of that transfer once. See Webhooks for the event format.

Track deposits

A deposit address is reusable. It can return to open after a payout, so do not wait for it to become settled permanently.

received is cumulative confirmed incoming money, not the remaining balance. A payout does not subtract from it. It can decrease when a transfer is reverted. Credit each incoming payment only once; webhooks are useful for this because each event has a stable ID.

disabled_at controls checkout availability. Disabling a deposit does not stop monitoring its address.

List invoices and deposits

curl 'https://platform.invoise.me/api/v1/shops/{shop_id}/payments?limit=50' \
  -H 'Authorization: Bearer ivk_...'

With limit (1–100), the response is {"items":[...],"next_cursor":"..."}. Send cursor for the next page until next_cursor is empty. Without pagination parameters, the endpoint returns a limited array; it is not the whole history.

The list supports kind, status and q filters. Its status=paid filter selects funded and settled; paid is not an issuance status returned by the detail endpoint.

The detail endpoint’s transfers field contains only the ten latest confirmed incoming/payout entries. Do not use it as a complete ledger.

Public checkout status

GET /api/v1/checkout/{public_id} needs no credentials. It provides the payment-page state, including status, received, amount and expires_at. Use the authenticated issuance endpoint for your backend’s shop records.

For pushed updates and signature checking, see Webhooks.