Invoice and deposit status
Read the invoice or deposit state through GET requests. Webhooks notify you of changes automatically.
Read an invoice or deposit
Section titled “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
Section titled “Interpret an invoice”status |
What to do |
|---|---|
registering |
Only for a group of several tokens or networks: some options do not have their address yet. Wait; the list’s status=open filter includes it. |
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 you archive its shop, 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
Section titled “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
Section titled “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. q searches the description, the id and the payment addresses, up to 200 characters; it does not search external_id. status takes an issuance status or one of these list-only values:
status |
Selects |
|---|---|
paid |
funded and settled. |
open |
open and registering. |
active / disabled |
deposits that are enabled or disabled. |
cancelled |
cancelled invoices. |
The other status filters leave out cancelled invoices. paid, active, disabled and cancelled are not statuses returned by the detail endpoint.
The detail endpoint’s transfers field contains only the ten latest confirmed incoming/payout entries. The complete list of incoming transfers is GET /api/v1/shops/{shop_id}/deposits: see Reconcile with the journal.
Public checkout status
Section titled “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.