# Algemene informatie

> Technische specificatie voor de integratie van crypto-betalingsverwerking en uitbetalingen met 2328.io.

Welkom bij de 2328.io API-documentatie. Deze referentie beschrijft hoe je crypto-betalingsverwerking en uitbetalingen in je applicatie integreert.

## Aan de slag

Om te beginnen met de integratie:

1. Maak een merchantaccount en project aan op [2328.io](https://2328.io)
2. Haal je **project UUID** en **API key** op uit de projectinstellingen
3. Genereer een aparte **Payout API key** als je uitbetalingen wilt gebruiken
4. Lees de sectie [Authenticatie](/docs/authentication) om te leren hoe je verzoeken ondertekent
5. Doe je eerste [Betaling aanmaken](/docs/payments)-aanroep

## Base URL

Alle API-verzoeken in productie gebruiken de volgende base URL:

```
https://api.2328.io/api
```

> **WARNING:** Alle verzoeken moeten via **HTTPS** worden gedaan. Verzoeken zonder HTTPS worden geblokkeerd.

## Wat je kunt doen

Met de 2328.io API kun je:

- **Crypto-betalingen accepteren** — betalingssessies aanmaken en klanten doorverwijzen naar een gehoste checkout of Telegram MiniApp
- **Geld uitbetalen** — uitbetalingen vanaf je merchantsaldo programmatisch versturen naar elk blockchain-adres
- **Saldi controleren** — bekijk merchant-saldi per valuta, USD-equivalenten en door AML vergrendelde bedragen
- **Statische wallets gebruiken** — permanente stortingsadressen aanmaken die gekoppeld zijn aan een gebruiker of order
- **Wisselkoersen ophalen** — realtime wisselkoersen voor fiat- en cryptoparen ophalen
- **Webhooks ontvangen** — direct een melding krijgen wanneer de status van een betaling verandert
## Rate limits

De API staat tot **10 verzoeken per seconde per project** toe. Verzoeken boven de limiet krijgen een HTTP `429 Too Many Requests`-response — wacht even en probeer opnieuw.

## Kies het juiste integratiepatroon

| Vereiste | Aanbevolen patroon | Waarom |
|-------------|---------------------|-----|
| Laat de klant kiezen hoe te betalen | Gehoste checkout | Maak een betaling aan en stuur door naar `result.url`; 2328.io presenteert momenteel beschikbare richtingen. |
| Houd de klant binnen je eigen checkout | Direct gericht op **H2H** factuur | Verstuur `to_currency` en `network` bij het aanmaken van de betaling; render de terugontvangen `address`, `payer_amount` en `qr`. |
| Breng precies `25 USDT` of `0.001 BTC` in rekening | Crypto-gedeclareerde factuur | Zet de cryptocurrency in `currency` en het exacte decimale bedrag in `amount`. |
| Geef elke gebruiker een herbruikbaar stortingsadres | Statische wallet | Het adres is permanent en kan meerdere onafhankelijke stortingen ontvangen. |
| Normaliseer binnenkomende activa naar één balansvaluta | Automatisch converteren | Configureer projectregels in het dashboard en gebruik het `convert`-resultaat wanneer de conversie voltooid is. |
| Ruil een bestaande merchant-balance | Handmatig converteren | Voorbeeld weergeven met `/v1/convert/price`, en vervolgens uitvoeren met `/v1/convert`. |
| Stuur fondsen naar een blockchain-adres | Uitbetaling | Gebruik de aparte Payout API-sleutel, bereken eerst, en stem de uitbetalingsstatus af. |

> **INFO:** Hosted checkout en H2H zijn twee presentaties van dezelfde Payment API. H2H creëert geen zwakkere of niet-ondertekende betaling: de backend maakt nog steeds de factuur aan, 2328.io blijft eigenaar van het adres en de status, en ondertekende webhooks blijven gezaghebbend voor de afwikkeling.

## Integratie-invarianten

Deze regels gelden voor elke productie-integratie:

- **Backend only** — hou API-sleutels buiten browsers, mobiele applicaties, logs, analytics en ondersteuningsscreenshots.
- **Decimal strings** — stuur en sla geld op als strings. Rond nooit cryptocurrency of wisselkoersen af met binaire drijvende-komma rekenkunde.
- **Immutable idempotency keys** — genereer `order_id` voor het eerste verzoek en bewaar het volledige verzoek ermee. Een retry met hetzelfde `order_id` kan het originele object teruggeven in plaats van gewijzigde velden toe te passen.
- **Webhook-first settlement** — redirects, client polling, transactie-hashes aangeleverd door gebruikers, en HTTP-timeouts zijn geen bewijs van betaling.
- **Verify, deduplicate, then mutate** — verifieer de HMAC, claim een idempotentiedossier atomair, werk de bestelling/saldo eenmaal bij, en geef snel HTTP 200 terug.
- **Reconciliation** — vraag periodiek de status van betaling, statische wallet en uitbetaling op zodat een verloren webhook geen blijvend meningsverschil kan veroorzaken.
- **Dynamic availability** — valideer valuta/netwerkparen met `/v1/directions`; een ondersteund activum kan nog steeds tijdelijk één stortings- of opnamrichting uitgeschakeld hebben.
- **Explicit status policy** — bepaal hoe uw product omgaat met gedeeltelijke betaling, overbetaling, verval, AML-vergrendeling, conversie-backup en ambigu upstream-time-outs voordat u live gaat.

## Aanbevolen gegevens om te bewaren

Voor betalingen, sla minimaal `uuid`, `order_id`, het originele request body, `amount`, `currency`, `payer_currency`, `payer_amount`, `network`, `address`, `expires_at`, de laatste `payment_status`, `txid`, `payment_amount`, `merchant_amount`, het optionele `convert`-blok, en de ruwe geverifieerde webhook-payload op.

Voor statische wallets, houd de wallet `uuid`, het adres, de valuta, het netwerk, de klant-/accountreferentie, de status en de callback-URL apart van stortingsrecorden. Elke storting heeft zijn eigen transactie `uuid`, `txid`, status, ontvangen bedrag, handelsbedrag en conversieresultaat nodig.