Quickstart
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.
1. Sign in and create a shop
Section titled “1. Sign in and create a shop”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
Section titled “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
Section titled “3. Pick a network and token”curl https://platform.invoise.me/api/v1/networksTake 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
Section titled “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. Send the payer to checkout
Section titled “5. Send the payer to checkout”The creating response already has the payment address and payment_url, and the invoice is open. Send the payer to that payment_url: it is the hosted checkout, with the address, a QR code and live status already built.
If creation returns 503 address_unavailable, the address could not be derived at that moment: retry the same request with the same Idempotency-Key.
6. Check whether it is paid
Section titled “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
Section titled “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-Signaturewith that secret and deduplicate byInvoise-Event-ID. See the signature verification example. transfer.confirmedreports a confirmed incoming transfer. Takedata.issuance_idand read the invoice through the GET below: a single transfer may cover only part of the amount.- If
statusisfundedorsettledandcancelled_atisnull, mark the order paid once. Separately,payout.confirmedconfirms complete settlement accounting for the recipient payout.
Through the API
Section titled “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. reconciling does 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
Section titled “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.