---
title: Facturen
description: Een factuur aanmaken via de Coinetic API: velden, assets zoals USDT en Bitcoin, idempotentie, statussen, bedragen en koers, betaling na de vervaltermijn.
url: https://coinetic.money/nl/docs/invoices/
lang: nl
---

# Facturen

Een factuur is één aankoop: een prijs in fiat of een stablecoin, een geldigheidsduur en — zodra de klant heeft gekozen — de betaalvaluta en het depositoadres.

## Aanmaken

`POST /v1/invoices`

Headers: `Authorization` ([CP-HMAC](https://coinetic.money/nl/docs/authentication/)), `Idempotency-Key`, `Content-Type: application/json`.

`request-body`

```json
{
  "order_id": "ORDER-1001",
  "price_amount": "49.99",
  "price_currency": "USD",
  "allowed_assets": ["USDT-TRON", "USDC-BASE", "BTC"],
  "return_url": "https://shop.example/orders/ORDER-1001",
  "expires_in_seconds": 1800,
  "metadata": { "user_id": "42", "plan": "pro" }
}
```

| Veld | Verplicht | Regels |
| --- | --- | --- |
| `order_id` | ja | 1–128 tekens, uniek per merchant (herhaling geeft `409 duplicate_order`) |
| `price_amount` | ja | Decimale **string** > 0, maximaal 18 cijfers achter de punt |
| `price_currency` | ja | `USD`, `EUR`, `USDT` of `USDC` |
| `allowed_assets` | nee | Maximaal 30 asset-id's (`GET /v1/assets`). Leeg betekent alle beschikbare. De factuur krijgt de **doorsnede** met de beschikbare assets; is die leeg, dan volgt `422 invalid_allowed_assets` |
| `return_url` | nee | `https://…` — de knop ‘Terug naar de winkel’ |
| `expires_in_seconds` | nee | 300–86.400, standaard 1800 (30 minuten) |
| `metadata` | nee | Maximaal 20 sleutels `[A-Za-z0-9_.-]{1,64}`, waarden tot 500 tekens; ze komen terug in de factuur |

Response `201`:

```json
{
  "id": "inv_x7k2…",
  "order_id": "ORDER-1001",
  "status": "created",
  "price_amount": "49.99",
  "price_currency": "USD",
  "allowed_assets": ["USDT-TRON", "BTC"],
  "checkout_url": "https://pay.coinetic.money/pay/inv_x7k2…#t=…",
  "return_url": "https://shop.example/orders/ORDER-1001",
  "expires_at": "2026-10-12T15:30:00Z",
  "created_at": "2026-10-12T15:00:00Z",
  "quote": null,
  "paid_amount": "0", "outstanding_amount": "0", "overpaid_amount": "0",
  "refunded_amount": "0", "refundable_amount": "0",
  "payments": [],
  "metadata": { "user_id": "42", "plan": "pro" },
  "livemode": true
}
```

- `price_amount` komt terug in canonieke vorm zonder nullen aan het eind: `"3.00"` wordt `"3"`. Vergelijk bedragen als decimalen, niet als float en niet byte voor byte.
- `checkout_url` bevat na `#` het token van de betaalpagina. Log en publiceer het niet.
- `livemode: false` — een sandboxfactuur. Uw productiewinkel moet zulke facturen weigeren.

### Welke assets in de factuur komen

Een asset is beschikbaar als het in Coinetic is ingeschakeld, u een actieve ontvangstwallet op dat netwerk hebt en u het niet hebt uitgesloten in het dashboard (‘Instellingen’ → ‘Geaccepteerde assets’). Elke asset heeft een minimum (`min_amount` in `GET /v1/assets`): is het factuurbedrag in die asset lager, dan komt de asset niet in de factuur. Voorbeeld: een factuur van 3 USD bij BTC = 60.000 USD is 5.000 sat, terwijl het minimum 10.000 is — zo'n factuur krijgt alleen stablecoins.

Het veld `selectable_assets` bevat de assets uit `allowed_assets` die op dit moment te kiezen zijn; de betaalpagina biedt alleen die aan.

## Idempotentie

- `Idempotency-Key`: 8–128 afdrukbare ASCII-tekens zonder spaties, niet beginnend met `d:`. Handig is een sleutel op basis van het ordernummer: `order-ORDER-1001`.
- Dezelfde sleutel met dezelfde body geeft **dezelfde response** (dezelfde factuur).
- Dezelfde sleutel met een andere body geeft `409 idempotency_conflict`.
- Loopt het eerste request nog, dan krijgt u `409 idempotency_in_progress`; probeer het na een seconde opnieuw.
- Ook een weigering op grond van een bedrijfsregel (bijvoorbeeld `422`) wordt onthouden.

## Opvragen

`GET /v1/invoices/{id}`

Zodra de klant een valuta heeft gekozen, verschijnt `quote` in de factuur:

`quote`

```json
{
  "asset_id": "USDT-TRON", "network": "tron", "token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "address": "TX…", "amount_due": "49990000", "decimals": 6, "display_amount": "49.99",
  "payment_uri": "tron:…", "rate": "1", "rate_valid_until": null,
  "network_warning": "Verstuur alleen USDT op het TRON-netwerk (TRC-20)…"
}
```

`payments` — de betalingen: `tx_hash`, `amount` (in de kleinste eenheid), `confirmations`, `required_confirmations`, `state` (`mempool`, `included`, `confirmed`, `reorged`, `replaced`, `failed`, `dropped`).

`unmatched_payments` — overboekingen naar het factuuradres die **niet zijn meegeteld**: op een ander EVM-netwerk (`wrong_network`) of met een token dat niet op de whitelist staat (`token_not_whitelisted`). Ze veranderen de status en `paid_amount` niet.

## Lijst

`GET /v1/invoices?status=paid&from=…&to=…&limit=50&cursor=…`

Response: `{ "items": [...], "next_cursor": "…" | null }`, van nieuw naar oud, `limit` 1–200.

## Statussen

| Status | Betekenis | Wat de winkel doet |
| --- | --- | --- |
| `created` | Factuur aangemaakt, nog geen valuta gekozen | wachten |
| `awaiting_payment` | Valuta gekozen, adres verstrekt | wachten |
| `detected` | Betaling zichtbaar op het netwerk (mempool) | ‘betaling gevonden’ tonen, **niet leveren** |
| `confirming` | In een blok, nog niet genoeg bevestigingen | voortgang tonen, **niet leveren** |
| `paid` | Volledig betaald en bevestigd | **bestelling leveren** |
| `overpaid` | Meer betaald dan nodig | bestelling leveren; het teveel op verzoek terugbetalen |
| `underpaid` | Minder bevestigd dan nodig (na aftrek van de tolerantie) | vragen het restant bij te betalen naar hetzelfde adres |
| `expired` | Termijn verstreken, geen betaling | een nieuwe factuur aanbieden (zie hieronder) |
| `late_payment` | Betaling binnengekomen na de termijn | u beslist: leveren of terugbetalen |
| `manual_review` | Betaling in AML-controle | wachten op het besluit; niet leveren |
| `refunded`, `cancelled` | Gesloten | niet leveren |

> **De belangrijkste regel.** Lever een bestelling alleen bij `paid` of `overpaid`, opgehaald via `GET /v1/invoices/{id}`.

### Betaling met een stablecoin na de termijn

Bij USDT of USDC voor een factuur in USD is er geen koersrisico, dus een betaling na de termijn (tot 30 dagen) wordt automatisch meegeteld: een factuur die al `invoice.expired` heeft gekregen, wordt `paid` en u ontvangt `invoice.paid` met `data.late: true`. **Sluit een bestelling daarom niet definitief af bij `invoice.expired`**. Bij volatiele assets leidt zo'n betaling tot `late_payment`.

## Bedragen en koers

- De prijs wordt opgegeven in de factuurvaluta. Het bedrag in crypto legt Coinetic vast op het moment dat de klant een valuta kiest.
- **Stablecoin in de eigen valuta** (USDT voor een factuur in USD): 1:1, het bedrag ligt vast tot het einde van de factuur.
- **Volatiele asset** (BTC, ETH enz.): mediaan van de koersen van Kraken, Coinbase en Bitstamp, 20 minuten vastgezet.
- `amount_due` — in de kleinste eenheid van de asset (USDT op TRON heeft 6 decimalen: `"49990000"` = 49,99). `display_amount` — hetzelfde in gewone notatie.
- De tolerantie voor onderbetaling (standaard 0,5%) vangt afrondingen door wallets op.

De referentiekoers vraagt u op met `GET /v1/rates?base=BTC&quote=USD`. Toon de klant op basis daarvan geen ‘exact’ cryptobedrag: alleen de factuur geeft een bindend bedrag.