# Quickstart

Create a shop, issue an invoice and receive the payment with the Invoise REST API.

Source: https://docs.invoise.me/start/quickstart/

**Get started faster with an agent**
Copy this prompt into your agent to set up a shop and check your first invoice.

```text wrap
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](https://docs.invoise.me/agents/sign-in/) instead. This page assumes a human does the
setup.

## 1. Sign in and create a shop

Open [platform.invoise.me](https://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](https://docs.invoise.me/payments/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](https://docs.invoise.me/payments/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:

```text
Authorization: Bearer ivk_...
```

The key works for one shop only and cannot touch your account or your team. See
[API keys](https://docs.invoise.me/integration/api-keys/).

## 3. Pick a network and token

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

## 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`. |

```bash
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](https://docs.invoise.me/payments/deposits-and-invoices/).

## 5. Wait for the address

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

```bash
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.

1. Verify `Invoise-Signature` with that secret and deduplicate by `Invoise-Event-ID`. See the [signature verification example](https://docs.invoise.me/integration/webhooks/#3-verify-before-processing).
2. `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.
3. 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:

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

Relevant response fields after payment:

```json
{
  "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](https://docs.invoise.me/payments/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](https://docs.invoise.me/integration/idempotency-and-errors/).