API til krypto-betalingsgateway: fakturaer, webhooks, udbetalinger og white label

Hvad gør et API til en krypto-betalingsgateway?

API'et skjuler blockchainen for din kode. I stedet for at drive noder, udlede adresser og tælle bekræftelser kalder du et endpoint for at oprette en faktura, gemmer gatewayens identifikator og venter på notifikationer. Gatewayen angiver vekselkursen, overvåger netværkene, udfører AML-screening og afvikler til din saldo.

De fleste gateways tilbyder de samme byggeklodser under forskellige navne: fakturaer eller ordrer til indgående betalinger, IPN eller callbacks til notifikationer, endpoints til omveksling og saldo samt udbetalinger eller hævninger til udgående overførsler. Sandboxes findes hos de fleste udbydere, for eksempel en separat sandbox-host hos CoinGate og en sandbox-konto hos NOWPayments, og bør bruges før enhver test på mainnet.

• Faktura-API: opret, læs og annullér betalingsanmodninger med fiatpris, accepterede coins, ordrereference og callback-URL
• Notifikationer: webhooks eller IPN ved hver statusændring, normalt signerede
• Udbetalings-API: send krypto eller fiat til kunder, partnere eller din egen wallet
• Kurser og valutaer: oversigt over understøttede coins, netværk, minimumsbeløb og live-kurser
• Plugins og SDK'er: færdige moduler til e-handelsplatforme oven på det samme API

Hvordan fungerer fakturaens livscyklus?

Hver gateway har sin egen statusmodel, så afbild dem til et lille internt sæt, før du skriver forretningslogik. Kun en endelig betalt status bør frigive varer; de mellemliggende statusser findes, fordi en transaktion kan ses on-chain længe, før det er sikkert at acceptere den.

Tabellen afbilder to offentliggjorte statusmodeller til de tilstande, de fleste platforme har brug for. CoinGate lader for eksempel en ubetalt faktura udløbe efter 20 minutter, når kunden har valgt en coin, og markerer betalinger, som AML-kontrollen flagger, som ugyldige.

Hvordan verificerer man krypto-webhooks og IPN?

Behandl enhver notifikation som upålidelig, indtil den er verificeret. Gateways bruger forskellige metoder: NOWPayments signerer den sorterede JSON-body med HMAC-SHA512 og sender signaturen i headeren x-nowpayments-sig, CoinGate sender et token, du selv har sat på ordren, og BitPay anbefaler at hente fakturaen fra API'et efter hver notifikation i stedet for at stole på dens body.

Det sikreste mønster kombinerer begge dele: verificér signaturen, læs derefter fakturaen fra API'et og handl ud fra det svar. Det koster én forespørgsel pr. statusændring og beskytter dig mod forfalskede eller genafspillede callbacks.

• Verificér signaturer med en sammenligning i konstant tid, og afvis usignerede forespørgsler
• Hent fakturaen igen med dens gateway-ID, før du ændrer ordrens tilstand
• Svar hurtigt med HTTP 200, og behandl asynkront; gateways forsøger igen ved fejl
• Gem hver notifikation med dens hændelse eller status, så dubletter ignoreres
• Stol aldrig på beløb eller valutaer, der sendes i browserens omdirigering

Hvordan håndterer man underbetalinger, overbetalinger og sene betalinger?

Wallets og børser trækker hævegebyrer, og kunder kopierer beløb upræcist, så man kan ikke gå ud fra, at der betales det nøjagtige beløb. Fastlæg en tolerance og en regel for hvert tilfælde før lancering, og gør udfaldet synligt for supportmedarbejdere.

Hvordan fungerer idempotens og afstemning?

Opret fakturaer med din egen ordrereference, og gør kaldet sikkert at gentage: hvis en forespørgsel løber ud i timeout, så slå fakturaen op på referencen, før du opretter en ny, eller brug en idempotensnøgle, hvor gatewayen understøtter det. Samme regel gælder for udbetalinger, hvor en dubleret forespørgsel sender rigtige penge to gange.

Til afstemning gemmer du gatewayens faktura-ID, transaktionshashen, fiatbeløbet, kryptobeløbet, kursen og gebyret. Afviklingsrapporter viser udbetalinger som batches, så afstemningen går fra ordre til faktura til udbetaling og ikke fra ordre til bankpostering.

Hvad kræver et udbetalings-API under Travel Rule?

Udbetalingsendpoints sender krypto fra din gatewaysaldo til en adresse, ofte i batches til affiliate-provisioner, marketplace-sælgere eller kundehævninger. De fleste kræver whitelisting af adresser, totrinsgodkendelse eller en API-nøgle med separate udbetalingsrettigheder.

I EU kræver forordning (EU) 2023/1113, at gatewayen sender oplysninger om afsender og modtager med hver overførsel og verificerer ejerskab af self-hosted wallets over 1.000 EUR. Forvent, at udbetalingsanmodninger skal indeholde modtagerens navn og adressetype, og planlæg for overførsler, der venter på disse data.

Hvilke white label-muligheder findes der for krypto-betalingsgateways?

Platforme, der videresælger betalinger til egne forhandlere, vil ofte have betalingssiden under eget brand. Der er tre niveauer, og prisen stiger med kontrollen. Plisio angiver for eksempel 0,5 % for sit API og 1,5 % for white label, og NOWPayments sælger et separat white label-produkt.

Fuld white label flytter ansvar og ikke kun branding. Hvis du onboarder forhandlere og opbevarer deres saldi, kan du have brug for din egen MiCA-godkendelse; en godkendt gateways sub-merchant-model lader forpligtelsen blive hos gatewayen.

Sådan forbinder du API'er til kryptogateways via OrsunPay

OrsunPay samler kryptogateways' statusser, webhooks og refunderinger i ét API ved siden af dine kort- og bankudbydere og bruger dine egne gatewaykonti. OrsunPay opbevarer ikke krypto og kører ikke udbetalinger fra egen saldo; det router forespørgsler til den gateway, du vælger, og returnerer signerede, deduplikerede hændelser.

Sådan integrerer du et API til en kryptovaluta-betalingsgateway

1. Opret sandbox-konti Opret sandbox- og produktionskonti hos gatewayen, generér separate API-nøgler til fakturaer og udbetalinger, og angiv IPN-hemmeligheden.
2. Afbild statusser Oversæt gatewayens statusser til dine interne tilstande, og beslut, hvilken der frigiver varer.
3. Opret fakturaer idempotent Send fiatbeløb, valuta, ordrereference og callback-URL; slå op på referencen, før du gentager et kald, der løb ud i timeout.
4. Verificér notifikationer Kontrollér signaturen, hent fakturaen igen fra API'et, og behandl hændelsen én gang.
5. Håndtér grænsetilfælde Implementér tolerance, supplerende betaling, refundering og udløb, og test hvert forløb i sandboxen.
6. Afstem afviklinger Gem transaktionshash, kurs og gebyr for hver faktura, og match udbetalingsbatches med ordrer dagligt.