Quickstart

Copy this prompt into your agent to set up a shop and check your first invoice.

Help me integrate Invoise into my project. Read https://docs.invoise.me/llms.txt, https://docs.invoise.me/openapi.json and https://docs.invoise.me/agents/integration.md.

Use my existing access or help me sign in and create a merchant, shop and API key. If you sign in with a wallet, ask me for my email before creating the merchant. Ask me for the recipient address before creating the shop. Read available networks, tokens, decimals and fees from the API.

Start in Sandbox: create an invoice, get payment_url, connect webhooks with signature verification and deduplication, and check payment through GET. Save Idempotency-Key before sending requests. Finish with the test result and what is needed to accept real payments.

This is the normal way to integrate Invoise into a site or a backend: sign in as a person, set the shop up in the dashboard, then let your server call the API with a key.

Building an unattended agent that has no browser and no email? Go to Agent sign-in instead. This page assumes a human does the setup.

Open platform.invoise.me and sign in with an email code or Google. On first sign-in you create a merchant; a new merchant has no shops yet, so create one.

A shop needs a recipient — the wallet that receives your money — or pays into your Invoise wallet. You can change the recipient and the optional delegate later; invoices and addresses already created keep the ones they were created with.

Create a sandbox shop if you want to rehearse without real funds. See Sandbox.

2. Create an API key

In the shop, create a key with read and write scopes. It starts with ivk_ and is shown once, so save it right away.

Your server sends it on every request:

Authorization: Bearer ivk_...

The key works for one shop only and cannot touch your account or your team. See API keys.

3. Pick a network and token

curl https://platform.invoise.me/api/v1/networks

Take chain_id, token address and decimals from the response. Choose a network enabled for your merchant and a ready token. Available assets change; do not hardcode their list. See Networks and tokens.

4. Issue an invoice

Amounts are integer strings in the token’s smallest units. At 6 decimals, 10000000 is 10 tokens.

Set these environment variables before the request:

Variable	Value
`CHAIN_ID`	The selected network’s `chain_id` from the API.
`TOKEN_ADDRESS`	The selected token’s `tokens[].address` on that network.
`AMOUNT`	Invoice amount in the smallest units, calculated using `tokens[].decimals`.

curl -X POST https://platform.invoise.me/api/v1/shops/{shop_id}/invoices \
  -H 'Authorization: Bearer ivk_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 2a8b1f47-6d0c-4a1f-8f0b-4f2c9f3a77d2' \
  -d "{\"chain_id\":${CHAIN_ID:?},\"token\":\"${TOKEN_ADDRESS:?}\",\"amount\":\"${AMOUNT:?}\"}"

Replace {shop_id} with your shop ID. Generate and save a unique Idempotency-Key for this invoice; the sample key is only an example.

The response is 202 Accepted: save its id as issuance_id. 202 means creation has been accepted, not that the customer has paid.

Want a reusable top-up address with no fixed amount? Call /deposits instead. See Deposits and invoices.

5. Wait for the address

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

Poll until an address comes back, then send the payer to the payment_url from that response. That is the hosted checkout, with the address, a QR code and live status already built.

6. Check whether it is paid

An invoice is paid when its status is funded or settled. funded means the required amount is confirmed; settled means the invoice has closed on chain. Read the status through the API and receive change notifications through webhooks.

Through a webhook

Before your first payment, register your server’s endpoint:

curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/webhooks' \
  -H 'Authorization: Bearer ivk_...' \
  -H 'Idempotency-Key: <saved-webhook-key>' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/invoise","filters":["transfer","invoice","payout"]}'

Replace the URL with your public HTTPS endpoint and save secret from the response.

Verify Invoise-Signature with that secret and deduplicate by Invoise-Event-ID. See the signature verification example.
transfer.confirmed reports a confirmed incoming transfer. Take data.issuance_id and read the invoice through the GET below: a single transfer may cover only part of the amount.
If status is funded or settled and cancelled_at is null, mark the order paid once. Separately, payout.confirmed confirms complete settlement accounting for the recipient payout.

Through the API

Read the invoice from your backend:

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

Relevant response fields after payment:

{
  "status": "funded",
  "amount": "10000000",
  "received": "10000000",
  "cancelled_at": null
}

The full invoice amount is confirmed. Mark the order paid; another GET or webhook must not credit it twice.

For open, keep waiting: the full payment has not arrived yet. You can poll every 3–5 seconds and slow down for long waits. registering and reconciling do not mean success either. If cancelled_at is set, handle the paid, cancelled order separately.

See Invoice and deposit status for all states and deposit-specific behaviour.

One rule to remember

Creating an invoice or deposit requires Idempotency-Key. Keep the key around: if a request times out and you are unsure whether it worked, send the same request with the same key again. You will get the original result instead of a second invoice. See Idempotency and errors.