API pentru gateway de plăți cripto: facturi, webhook-uri, plăți către terți și white label

Ce face API-ul unui gateway de plăți cripto?

API-ul ascunde blockchain-ul de codul dumneavoastră. În loc să rulați noduri, să derivați adrese și să numărați confirmări, apelați un endpoint pentru a crea o factură, salvați identificatorul gateway-ului și așteptați notificările. Gateway-ul cotează cursul de schimb, urmărește rețelele, aplică verificările AML și face decontarea în soldul dumneavoastră.

Majoritatea gateway-urilor expun aceleași componente sub nume diferite: facturi sau comenzi pentru plățile primite, IPN sau callback-uri pentru notificări, endpoint-uri de conversie și sold, precum și payouts sau retrageri pentru transferurile de ieșire. La majoritatea furnizorilor există sandbox-uri, de exemplu un host sandbox separat la CoinGate și un cont sandbox la NOWPayments, care trebuie folosite înainte de orice test pe mainnet.

• API de facturi: creați, citiți și anulați cereri de plată cu preț în monedă fiduciară, monede acceptate, referință de comandă și URL de callback
• Notificări: webhook-uri sau IPN la fiecare schimbare de status, de regulă semnate
• API de payouts: trimiteți cripto sau monedă fiduciară către clienți, parteneri sau propriul portofel
• Cursuri și monede: listați monedele și rețelele acceptate, sumele minime și cotații în timp real
• Pluginuri și SDK-uri: module gata făcute pentru platforme de e-commerce, construite pe același API

Cum funcționează ciclul de viață al facturii?

Fiecare gateway are propriul model de statusuri, așa că mapați-le la un set mic intern înainte de a scrie logica de business. Doar un status final de plată ar trebui să elibereze bunurile; statusurile intermediare există pentru că o tranzacție poate fi văzută pe blockchain cu mult înainte de a fi sigură pentru acceptare.

Tabelul mapează două modele de statusuri publicate la stările de care au nevoie majoritatea platformelor. CoinGate, de exemplu, expiră o factură neplătită după 20 de minute de la alegerea monedei de către client și marchează drept invalide plățile semnalate de verificările AML.

Cum se verifică webhook-urile și IPN-urile cripto?

Tratați orice notificare ca nesigură până la verificare. Gateway-urile folosesc scheme diferite: NOWPayments semnează corpul JSON sortat cu HMAC-SHA512 și îl trimite în antetul x-nowpayments-sig, CoinGate trimite un token pe care îl setați pe comandă, iar BitPay recomandă preluarea facturii din API după fiecare notificare, în loc să vă bazați pe corpul acesteia.

Cel mai sigur tipar le combină pe ambele: verificați semnătura, apoi citiți factura din API și acționați pe baza acelui răspuns. Costă o cerere pentru fiecare schimbare de status și vă protejează împotriva callback-urilor falsificate sau reluate.

• Verificați semnăturile cu o comparație în timp constant și respingeți cererile nesemnate
• Preluați din nou factura după ID-ul din gateway înainte de a schimba starea comenzii
• Returnați rapid HTTP 200 și procesați asincron; gateway-urile reîncearcă la erori
• Stocați fiecare notificare cu evenimentul sau statusul ei, astfel încât dublurile să fie ignorate
• Nu vă bazați niciodată pe sumele sau monedele trimise în redirecționarea din browser

Cum se tratează plățile insuficiente, cele în exces și cele întârziate?

Portofelele și bursele rețin taxe de retragere, iar clienții copiază sumele imperfect, așa că nu se poate presupune o plată exactă. Definiți o toleranță și o regulă pentru fiecare caz înainte de lansare și afișați rezultatul personalului de suport.

Cum funcționează idempotența și reconcilierea?

Creați facturile cu propria referință de comandă și faceți apelul sigur la reîncercare: dacă cererea expiră, căutați factura după referință înainte de a crea alta sau folosiți o cheie de idempotență acolo unde gateway-ul o acceptă. Aceeași regulă se aplică plăților către terți, unde o cerere duplicată trimite bani reali de două ori.

Pentru reconciliere, stocați ID-ul facturii din gateway, hash-ul tranzacției, suma în monedă fiduciară, suma în cripto, cursul și comisionul. Rapoartele de decontare listează payouts în loturi, așa că potrivirea se face de la comandă la factură și la plată, nu de la comandă direct la linia din extrasul bancar.

Ce are nevoie un API de payouts în cadrul Travel Rule?

Endpoint-urile de payouts trimit cripto din soldul gateway-ului către o adresă, adesea în loturi pentru comisioane de afiliere, vânzători din marketplace sau retrageri ale clienților. Majoritatea cer includerea adreselor pe lista albă, aprobare cu doi factori sau o cheie API cu permisiuni separate pentru payouts.

În UE, Regulamentul (UE) 2023/1113 cere gateway-ului să transmită informațiile despre inițiator și beneficiar cu fiecare transfer și să verifice deținerea portofelelor self-hosted peste 1.000 EUR. Vă puteți aștepta ca cererile de payout să includă numele beneficiarului și tipul adresei, și planificați transferuri care așteaptă aceste date.

Care sunt opțiunile de gateway de plăți cripto white label?

Platformele care revând plăți propriilor comercianți vor adesea pagina de plată sub brandul lor. Există trei niveluri, iar prețul crește odată cu controlul. Plisio, de exemplu, listează 0,5% pentru API și 1,5% pentru white label, iar NOWPayments vinde un produs white label separat.

White label complet mută atât responsabilitatea, cât și brandingul. Dacă onboardați comercianți și le țineți soldurile, este posibil să aveți nevoie de propria autorizare MiCA; folosirea modelului de sub-comerciant al unui gateway autorizat păstrează această obligație la gateway.

Cum conectați API-urile gateway-urilor cripto prin OrsunPay?

OrsunPay normalizează statusurile, webhook-urile și rambursările gateway-urilor cripto într-un singur API, alături de furnizorii dumneavoastră de carduri și plăți bancare, folosind conturile dumneavoastră proprii de gateway. Nu păstrează cripto în custodie și nu face payouts din propriul sold; rutează cererile către gateway-ul ales de dumneavoastră și returnează evenimente semnate și deduplicate.

Cum integrați API-ul unui gateway de plăți în criptomonede

1. Deschideți conturi sandbox Creați conturi sandbox și de producție la gateway, generați chei API separate pentru facturi și payouts și setați secretul IPN.
2. Mapați statusurile Traduceți statusurile gateway-ului în stările dumneavoastră interne și stabiliți care dintre ele eliberează bunurile.
3. Creați facturi idempotent Trimiteți suma în monedă fiduciară, moneda, referința comenzii și URL-ul de callback; căutați după referință înainte de a reîncerca un apel expirat.
4. Verificați notificările Verificați semnătura, preluați din nou factura din API și procesați evenimentul o singură dată.
5. Tratați cazurile limită Implementați fluxurile de toleranță, completare, rambursare și expirare și testați-le pe fiecare în sandbox.
6. Reconciliați decontările Stocați hash-ul tranzacției, cursul și comisionul pentru fiecare factură și potriviți zilnic loturile de plăți cu comenzile.