Sign in
Introductie/Algemene informatie

Algemene informatie

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

Bekijk als Markdown·llms.txt

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
  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 om te leren hoe je verzoeken ondertekent
  5. Doe je eerste Betaling aanmaken-aanroep

Base URL

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

Text
https://api.2328.io/api

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

VereisteAanbevolen patroonWaarom
Laat de klant kiezen hoe te betalenGehoste checkoutMaak een betaling aan en stuur door naar result.url; 2328.io presenteert momenteel beschikbare richtingen.
Houd de klant binnen je eigen checkoutDirect gericht op H2H factuurVerstuur 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 rekeningCrypto-gedeclareerde factuurZet de cryptocurrency in currency en het exacte decimale bedrag in amount.
Geef elke gebruiker een herbruikbaar stortingsadresStatische walletHet adres is permanent en kan meerdere onafhankelijke stortingen ontvangen.
Normaliseer binnenkomende activa naar één balansvalutaAutomatisch converterenConfigureer projectregels in het dashboard en gebruik het convert-resultaat wanneer de conversie voltooid is.
Ruil een bestaande merchant-balanceHandmatig converterenVoorbeeld weergeven met /v1/convert/price, en vervolgens uitvoeren met /v1/convert.
Stuur fondsen naar een blockchain-adresUitbetalingGebruik de aparte Payout API-sleutel, bereken eerst, en stem de uitbetalingsstatus af.

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.

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.