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

Headers: Authorization (CP-HMAC), Idempotency-Key, Content-Type: application/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" }
}

Response 201:

{
  "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

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

{
  "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

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

Statussen

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.