# Invoice and deposit status

Check an invoice or deposit through the API, with or without webhooks.

Source: https://docs.invoise.me/payments/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:

```bash
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):

```json
{
  "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`](https://docs.invoise.me/integration/webhooks/#2-choose-the-events-you-need). 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](https://docs.invoise.me/integration/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

```bash
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](https://docs.invoise.me/integration/webhooks/).