API för kryptobetalningsgateway: fakturor, webhooks, utbetalningar och white label

Vad gör ett API för kryptobetalningsgateway?

API:et gömmer blockkedjan för din kod. I stället för att driva noder, härleda adresser och räkna bekräftelser anropar du en endpoint för att skapa en faktura, sparar gatewayens identifierare och väntar på notiser. Gatewayen anger växelkursen, bevakar nätverken, tillämpar AML-screening och avräknar till ditt saldo.

De flesta gateways erbjuder samma byggstenar under olika namn: fakturor eller ordrar för inkommande betalningar, IPN eller callbacks för notiser, växlings- och saldoendpoints samt utbetalningar eller uttag för utgående överföringar. Sandlådor finns hos de flesta leverantörer, till exempel en separat sandlådevärd hos CoinGate och ett sandlådekonto hos NOWPayments, och bör användas före varje test på mainnet.

• Faktura-API: skapa, läsa och avbryta betalningsförfrågningar med fiatpris, accepterade kryptovalutor, orderreferens och callback-URL
• Notiser: webhooks eller IPN vid varje statusändring, vanligtvis signerade
• Utbetalnings-API: skicka krypto eller fiat till kunder, partner eller din egen plånbok
• Kurser och valutor: lista kryptovalutor som stöds, nätverk, miniminivåer och aktuella kurser
• Plugins och SDK:er: färdiga moduler för e-handelsplattformar ovanpå samma API

Hur fungerar fakturans livscykel?

Varje gateway har sin egen statusmodell, så mappa dem till en liten intern uppsättning innan du skriver affärslogik. Bara en slutlig status för betald ska frigöra varor; mellanstatusar finns eftersom en transaktion kan synas på blockkedjan långt innan det är säkert att acceptera den.

Tabellen mappar två publicerade statusmodeller till de tillstånd som de flesta plattformar behöver. CoinGate låter till exempel en obetald faktura gå ut efter 20 minuter när köparen har valt en kryptovaluta, och markerar betalningar som flaggats av AML-kontroller som invalid.

Hur ska kryptowebhooks och IPN verifieras?

Behandla varje notis som ej betrodd tills den är verifierad. Gateways använder olika metoder: NOWPayments signerar den sorterade JSON-kroppen med HMAC-SHA512 och skickar signaturen i headern x-nowpayments-sig, CoinGate skickar en token som du anger på ordern, och BitPay rekommenderar att du hämtar fakturan från API:et efter varje notis i stället för att lita på dess innehåll.

Det säkraste mönstret kombinerar båda: verifiera signaturen, läs sedan fakturan från API:et och agera på det svaret. Det kostar en förfrågan per statusändring och skyddar mot förfalskade eller återuppspelade callbacks.

• Verifiera signaturer med en jämförelse i konstant tid och avvisa osignerade förfrågningar
• Hämta fakturan på nytt med dess gateway-ID innan du ändrar orderstatus
• Returnera HTTP 200 snabbt och bearbeta asynkront; gateways försöker igen vid fel
• Spara varje notis med sin händelse eller status så att dubbletter ignoreras
• Lita aldrig på belopp eller valutor som skickas i webbläsarens omdirigering

Hur hanteras underbetalningar, överbetalningar och sena betalningar?

Plånböcker och börser drar av uttagsavgifter, och kunder kopierar belopp ofullständigt, så exakt betalning kan inte förutsättas. Definiera en tolerans och en regel för varje fall före lansering, och gör utfallet synligt för supportpersonalen.

Hur fungerar idempotens och avstämning?

Skapa fakturor med din egen orderreferens och gör anropet säkert att upprepa: om förfrågan får timeout, slå upp fakturan på referensen innan du skapar en ny, eller använd en idempotensnyckel där gatewayen stöder det. Samma regel gäller utbetalningar, där en dubblerad förfrågan skickar riktiga pengar två gånger.

För avstämning sparar du gatewayens faktura-ID, transaktionshashen, fiatbeloppet, kryptobeloppet, kursen och avgiften. Avräkningsrapporter listar utbetalningar som batcher, så matchningen går från order till faktura till utbetalning snarare än från order till bankrad.

Vad kräver ett utbetalnings-API enligt Travel Rule?

Utbetalningsendpoints skickar krypto från ditt gatewaysaldo till en adress, ofta i batcher för affiliateprovisioner, säljare på marknadsplatser eller kunduttag. De flesta kräver vitlistade adresser, tvåfaktorsgodkännande eller en API-nyckel med separata utbetalningsbehörigheter.

I EU kräver förordning (EU) 2023/1113 att gatewayen skickar med uppgifter om avsändare och mottagare vid varje överföring och kontrollerar ägandet av egenhanterade plånböcker över 1 000 EUR. Räkna med att utbetalningsförfrågningar ska innehålla mottagarens namn och adresstyp, och planera för överföringar som väntar på dessa uppgifter.

Vilka white label-alternativ finns för kryptobetalningsgateways?

Plattformar som vidareförsäljer betalningar till egna handlare vill ofta ha betalningssidan under eget varumärke. Det finns tre nivåer, och priset stiger med kontrollen. Plisio anger till exempel 0,5 % för sitt API och 1,5 % för white label, och NOWPayments säljer en separat white label-produkt.

Full white label flyttar ansvar och inte bara varumärke. Om du introducerar handlare och håller deras saldon kan du behöva en egen MiCA-auktorisation; om du använder en auktoriserad gateways modell med underhandlare ligger den skyldigheten kvar hos gatewayen.

Så ansluter du API:er för kryptogateways via OrsunPay

OrsunPay normaliserar kryptogatewayers statusar, webhooks och återbetalningar till ett enda API vid sidan av dina kort- och bankleverantörer, med dina egna gatewaykonton. OrsunPay förvarar inte krypto och kör inga utbetalningar från ett eget saldo; det dirigerar förfrågningar till den gateway du väljer och skickar tillbaka signerade, deduplicerade händelser.

Så integrerar du ett API för betalningsgateway för kryptovalutor

1. Öppna sandlådekonton Skapa sandlådekonto och produktionskonto hos gatewayen, generera separata API-nycklar för fakturor och utbetalningar och ange IPN-hemligheten.
2. Mappa statusar Översätt gatewayens statusar till dina interna tillstånd och bestäm vilket som frigör varor.
3. Skapa fakturor idempotent Skicka fiatbelopp, valuta, orderreferens och callback-URL; slå upp på referensen innan du försöker igen efter ett anrop som fått timeout.
4. Verifiera notiser Kontrollera signaturen, hämta fakturan på nytt från API:et och bearbeta händelsen en gång.
5. Hantera specialfall Implementera flöden för tolerans, komplettering, återbetalning och utgång, och testa varje flöde i sandlådan.
6. Stäm av avräkningar Spara transaktionshash, kurs och avgift per faktura och matcha utbetalningsbatcher mot ordrar varje dag.