Crypto payment gateway API: facturen, webhooks, uitbetalingen en white label

Wat doet een crypto payment gateway API?

De API schermt de blockchain af van uw code. In plaats van nodes te draaien, adressen af te leiden en bevestigingen te tellen, roept u een endpoint aan om een factuur aan te maken, slaat u de identifier van de gateway op en wacht u op notificaties. De gateway levert de wisselkoers, bewaakt de netwerken, past AML-screening toe en rekent af op uw saldo.

De meeste gateways bieden dezelfde bouwstenen onder verschillende namen: facturen of orders voor inkomende betalingen, IPN of callbacks voor notificaties, omzet- en saldo-endpoints, en uitbetalingen of opnames voor uitgaande overboekingen. Bij de meeste aanbieders bestaan sandboxes, bijvoorbeeld een aparte sandboxhost bij CoinGate en een sandboxaccount bij NOWPayments, en die gebruikt u vóór elke test op het hoofdnetwerk.

• Factuur-API: betaalverzoeken aanmaken, opvragen en annuleren met fiatprijs, geaccepteerde munten, orderreferentie en callback-URL
• Notificaties: webhooks of IPN bij elke statuswijziging, meestal ondertekend
• Uitbetalings-API: crypto of fiat versturen naar klanten, partners of uw eigen wallet
• Koersen en valuta: ondersteunde munten, netwerken, minimumbedragen en actuele koersen opvragen
• Plug-ins en SDK's: kant-en-klare modules voor e-commerceplatforms op dezelfde API

Hoe werkt de factuurlevenscyclus?

Elke gateway heeft een eigen statusmodel, dus zet ze om naar een kleine interne set voordat u bedrijfslogica schrijft. Alleen een definitieve betaalstatus mag goederen vrijgeven; tussenstatussen bestaan omdat een transactie lang voordat ze veilig te accepteren is al op de blockchain zichtbaar kan zijn.

De tabel koppelt twee gepubliceerde statusmodellen aan de toestanden die de meeste platforms nodig hebben. CoinGate laat een onbetaalde factuur bijvoorbeeld 20 minuten nadat de klant een munt heeft gekozen verlopen en markeert betalingen die door AML-controles zijn aangemerkt als ongeldig.

Hoe verifieert u crypto-webhooks en IPN?

Behandel elke notificatie als onbetrouwbaar totdat ze is geverifieerd. Gateways gebruiken verschillende schema's: NOWPayments ondertekent de gesorteerde JSON-body met HMAC-SHA512 en stuurt die mee in de header x-nowpayments-sig, CoinGate stuurt een token dat u op de order instelt, en BitPay raadt aan om na elke notificatie de factuur uit de API op te halen in plaats van de body te vertrouwen.

Het veiligste patroon combineert beide: controleer de handtekening, lees daarna de factuur uit de API en handel op basis van dat antwoord. Het kost één request per statuswijziging en beschermt u tegen vervalste of opnieuw afgespeelde callbacks.

• Controleer handtekeningen met een vergelijking in constante tijd en weiger niet-ondertekende requests
• Haal de factuur opnieuw op via het gateway-ID voordat u de orderstatus wijzigt
• Geef snel HTTP 200 terug en verwerk asynchroon; gateways proberen het opnieuw bij fouten
• Sla elke notificatie op met haar gebeurtenis of status, zodat duplicaten worden genegeerd
• Vertrouw nooit op bedragen of valuta die in de browserredirect worden meegestuurd

Hoe gaat u om met onderbetalingen, overbetalingen en late betalingen?

Wallets en exchanges houden opnamekosten in en klanten kopiëren bedragen onnauwkeurig, dus u kunt niet uitgaan van een exacte betaling. Bepaal vóór de lancering een tolerantie en een regel voor elk geval, en maak de uitkomst zichtbaar voor medewerkers van support.

Hoe werken idempotentie en reconciliatie?

Maak facturen aan met uw eigen orderreferentie en zorg dat de aanroep veilig herhaald kan worden: als het request een time-out geeft, zoek de factuur dan op referentie op voordat u een nieuwe aanmaakt, of gebruik een idempotency key als de gateway die ondersteunt. Hetzelfde geldt voor uitbetalingen, waar een dubbel request echt geld twee keer verstuurt.

Sla voor reconciliatie het factuur-ID van de gateway, de transactiehash, het fiatbedrag, het cryptobedrag, de koers en de kosten op. Afwikkelingsrapporten tonen uitbetalingen als batches, dus de koppeling loopt van order naar factuur naar uitbetaling en niet van order naar bankregel.

Wat vraagt een uitbetalings-API vanwege de Travel Rule?

Uitbetalingsendpoints versturen crypto van uw gatewaysaldo naar een adres, vaak in batches voor commissies van affiliates, verkopers op een marktplaats of opnames van klanten. De meeste vereisen een whitelist van adressen, goedkeuring met tweefactorauthenticatie of een API-sleutel met aparte uitbetalingsrechten.

In de EU verplicht Verordening (EU) 2023/1113 de gateway om bij elke overboeking gegevens van de opdrachtgever en de begunstigde door te geven en het eigendom van self-hosted wallets boven EUR 1.000 te verifiëren. Reken erop dat uitbetalingsverzoeken de naam van de begunstigde en het type adres moeten bevatten, en houd rekening met overboekingen die op deze gegevens wachten.

Welke white-label crypto payment gateway-opties zijn er?

Platforms die betalingen doorverkopen aan hun eigen verkopers willen de betaalpagina vaak onder hun eigen merk aanbieden. Er zijn drie niveaus, en de prijs stijgt met de controle. Plisio noemt bijvoorbeeld 0,5% voor zijn API en 1,5% voor white label, en NOWPayments verkoopt een apart white-labelproduct.

Volledige white label verschuift naast de branding ook de verantwoordelijkheid. Als u verkopers onboardt en hun saldo's beheert, hebt u mogelijk een eigen MiCA-vergunning nodig; met het submerchantmodel van een vergunde gateway blijft die verplichting bij de gateway.

Hoe koppelt u crypto gateway-API's via OrsunPay?

OrsunPay normaliseert statussen, webhooks en terugbetalingen van cryptogateways in één API naast uw kaart- en bankaanbieders, met uw eigen gatewayaccounts. OrsunPay bewaart geen crypto en voert geen uitbetalingen uit vanaf een eigen saldo; het routeert verzoeken naar de gateway van uw keuze en geeft ondertekende, ontdubbelde gebeurtenissen door.

Een cryptocurrency payment gateway API integreren

1. Open sandboxaccounts Maak sandbox- en productieaccounts aan bij de gateway, genereer aparte API-sleutels voor facturen en uitbetalingen en stel het IPN-geheim in.
2. Koppel statussen Vertaal de statussen van de gateway naar uw interne toestanden en bepaal welke toestand goederen vrijgeeft.
3. Maak facturen idempotent aan Stuur fiatbedrag, valuta, orderreferentie en callback-URL mee; zoek op referentie voordat u een aanroep met time-out herhaalt.
4. Verifieer notificaties Controleer de handtekening, haal de factuur opnieuw op uit de API en verwerk de gebeurtenis één keer.
5. Behandel uitzonderingen Implementeer tolerantie, bijstorting, terugbetaling en verloop, en test elk geval in de sandbox.
6. Reconcilieer afwikkelingen Sla per factuur transactiehash, koers en kosten op en koppel uitbetalingsbatches dagelijks aan bestellingen.