API for krypto-betalingsgateway: fakturaer, webhooks, utbetalinger og white label

Hva gjør et API for en krypto-betalingsgateway?

API-et skjuler blokkjeden for koden din. I stedet for å drive noder, utlede adresser og telle bekreftelser kaller du et endepunkt for å opprette en faktura, lagrer gatewayens identifikator og venter på varsler. Gatewayen oppgir vekslingskursen, overvåker nettverkene, utfører AML-screening og gjør opp til saldoen din.

De fleste gatewayer tilbyr de samme byggeklossene under ulike navn: fakturaer eller ordrer for innkommende betalinger, IPN eller callbacks for varsler, endepunkter for veksling og saldo samt utbetalinger eller uttak for utgående overføringer. Sandboxer finnes hos de fleste leverandører, for eksempel en egen sandbox-vert hos CoinGate og en sandbox-konto hos NOWPayments, og bør brukes før enhver test på mainnet.

• Faktura-API: opprett, les og kanseller betalingsforespørsler med fiatpris, godtatte coins, ordrereferanse og callback-URL
• Varsler: webhooks eller IPN ved hver statusendring, vanligvis signerte
• Utbetalings-API: send krypto eller fiat til kunder, partnere eller din egen wallet
• Kurser og valutaer: oversikt over støttede coins, nettverk, minstebeløp og live-kurser
• Plugins og SDK-er: ferdige moduler for netthandelsplattformer oppå samme API

Hvordan fungerer fakturaens livssyklus?

Hver gateway har sin egen statusmodell, så avbild dem til et lite internt sett før du skriver forretningslogikk. Bare en endelig betalt status bør frigi varer; mellomstatusene finnes fordi en transaksjon kan sees on-chain lenge før den er trygg å godta.

Tabellen avbilder to publiserte statusmodeller til tilstandene de fleste plattformer trenger. CoinGate lar for eksempel en ubetalt faktura utløpe etter 20 minutter når kunden har valgt en coin, og markerer betalinger som AML-kontrollen flagger, som ugyldige.

Hvordan verifiserer man krypto-webhooks og IPN?

Behandle ethvert varsel som upålitelig til det er verifisert. Gatewayer bruker ulike metoder: NOWPayments signerer den sorterte JSON-innholdet med HMAC-SHA512 og sender signaturen i headeren x-nowpayments-sig, CoinGate sender et token du selv har satt på ordren, og BitPay anbefaler å hente fakturaen fra API-et etter hvert varsel i stedet for å stole på innholdet i det.

Det tryggeste mønsteret kombinerer begge deler: verifiser signaturen, les deretter fakturaen fra API-et og handle ut fra det svaret. Det koster én forespørsel per statusendring og beskytter deg mot forfalskede eller gjenspilte callbacks.

• Verifiser signaturer med en sammenligning i konstant tid, og avvis usignerte forespørsler
• Hent fakturaen på nytt med gateway-ID-en før du endrer ordretilstand
• Svar raskt med HTTP 200 og behandl asynkront; gatewayer prøver på nytt ved feil
• Lagre hvert varsel med hendelse eller status, slik at duplikater ignoreres
• Stol aldri på beløp eller valutaer som sendes i nettleserens videresending

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

Wallets og børser trekker uttaksgebyrer, og kunder kopierer beløp unøyaktig, så man kan ikke anta at det betales nøyaktig. Fastsett en toleranse og en regel for hvert tilfelle før lansering, og gjør utfallet synlig for supportmedarbeidere.

Hvordan fungerer idempotens og avstemming?

Opprett fakturaer med din egen ordrereferanse, og gjør kallet trygt å gjenta: hvis en forespørsel går ut på tid, slå opp fakturaen på referansen før du oppretter en ny, eller bruk en idempotensnøkkel der gatewayen støtter det. Samme regel gjelder for utbetalinger, der en duplisert forespørsel sender ekte penger to ganger.

Til avstemming lagrer du gatewayens faktura-ID, transaksjonshashen, fiatbeløpet, kryptobeløpet, kursen og gebyret. Oppgjørsrapporter viser utbetalinger som batcher, så avstemmingen går fra ordre til faktura til utbetaling og ikke fra ordre til banklinje.

Hva krever et utbetalings-API under Travel Rule?

Utbetalingsendepunkter sender krypto fra gatewaysaldoen din til en adresse, ofte i batcher for affiliate-provisjoner, selgere på markedsplasser eller kunders uttak. De fleste krever hvitlisting av adresser, tofaktorgodkjenning eller en API-nøkkel med egne utbetalingsrettigheter.

I EU krever forordning (EU) 2023/1113 at gatewayen sender opplysninger om avsender og mottaker med hver overføring og verifiserer eierskap til self-hosted wallets over 1 000 EUR. Regn med at utbetalingsforespørsler må inneholde mottakerens navn og adressetype, og planlegg for overføringer som venter på disse dataene.

Hvilke white label-alternativer finnes for krypto-betalingsgatewayer?

Plattformer som videreselger betalinger til egne forhandlere vil ofte ha betalingssiden under eget merke. Det finnes tre nivåer, og prisen stiger med kontrollen. Plisio oppgir for eksempel 0,5 % for API-et sitt og 1,5 % for white label, og NOWPayments selger et eget white label-produkt.

Full white label flytter ansvar og ikke bare merkevare. Hvis du onboarder forhandlere og oppbevarer saldoene deres, kan du trenge din egen MiCA-godkjenning; sub-merchant-modellen til en godkjent gateway lar forpliktelsen bli hos gatewayen.

Slik kobler du API-er for kryptogatewayer via OrsunPay

OrsunPay samler kryptogatewayers statuser, webhooks og refusjoner i ett API ved siden av kort- og bankleverandørene dine og bruker dine egne gatewaykontoer. OrsunPay oppbevarer ikke krypto og kjører ikke utbetalinger fra egen saldo; det ruter forespørsler til gatewayen du velger og returnerer signerte, deduplikerte hendelser.

Slik integrerer du et API for en kryptovaluta-betalingsgateway

1. Opprett sandbox-kontoer Opprett sandbox- og produksjonskontoer hos gatewayen, generer separate API-nøkler for fakturaer og utbetalinger, og angi IPN-hemmeligheten.
2. Avbild statuser Oversett gatewayens statuser til dine interne tilstander, og bestem hvilken som frigir varer.
3. Opprett fakturaer idempotent Send fiatbeløp, valuta, ordrereferanse og callback-URL; slå opp på referansen før du gjentar et kall som gikk ut på tid.
4. Verifiser varsler Kontroller signaturen, hent fakturaen på nytt fra API-et og behandle hendelsen én gang.
5. Håndter grensetilfeller Implementer toleranse, tilleggsbetaling, refusjon og utløp, og test hvert forløp i sandboxen.
6. Avstem oppgjør Lagre transaksjonshash, kurs og gebyr for hver faktura, og match utbetalingsbatcher med ordrer daglig.