Integrarea API pentru plăți cripto: Ce trebuie să construiască echipa ta

Un ghid pre-lansare și o prezentare video pas cu pas

Întrebare {{n}} din {{t}}

Pregătit să lansăm

Echipa ta are răspunsuri la întrebările cheie. Ești aproape de lansare: rulează testele cu plăți reale înainte de a merge live.

Aproape acolo

Mai rămân câteva lacune. Închide-le înainte de lansare: fiecare este acoperită într-o secțiune a acestui articol.

Încă nu ești pregătit

Mai multe decizii cheie sunt încă deschise. Hosted Checkout preia cea mai mare parte a muncii de pe echipa ta, iar tu poți solicita o demonstrație live de la echipa de vânzări Volet.com pentru a vedea fluxul de plată mai întâi.

Lista de verificare API înainte de lansare

Nouă întrebări de răspuns înainte de a merge live. Alege răspunsul care se potrivește echipei tale: fiecare răspuns deschide o notă scurtă și indică partea acestui articol care o explică.

Întrebare 1 din 9

1. Produsul necesită o interfață de plată personalizată?

Da, avem nevoie de UI-ul nostru

Nu, o pagină găzduită funcționează

Încă nu s-a decis

Dacă da, ai nevoie de API-only, iar echipa ta construiește și întreține ecranele de plată. Dacă nu, Hosted Checkout este calea cu efort mai mic, și acceptă de asemenea plăți din soldurile conturilor Volet.com.

→ Vezi: API sau Hosted Checkout: o comparație practică, mai jos

2. Trebuie să controlăm fiecare pas al tunelului de plată, sau este acceptabil un redirect?

Trebuie să controlăm fiecare pas

Un redirect este în regulă

Încă nu s-a decis

Cu un redirect către Hosted Checkout, Volet.com trimite notificări de stare către URL-ul tău de stare. Cu UI-ul tău de plată pe API, backend-ul tău trebuie să verifice singur starea plății.

→ Vezi: API sau Hosted Checkout: o comparație practică, mai jos

3. Avem capacitatea de a construi și întreține interfața de plată, gestionarea expirării și verificările de stare?

Da, avem capacitatea

Nu, Hosted Checkout ni se potrivește mai bine

Încă nu sunt sigur

API-only înseamnă că echipa ta deține ecranele de plată, expirarea facturii (o rată a facturii este valabilă timp de 60 sau 15 minute) și verificările regulate de stare.

→ Vezi: Ce trebuie să construiască echipa ta, mai jos

4. Am definit cum se corelează comenzile interne cu încercările de plată și cum va fi prevenită îndeplinirea duplicată?

Da, este definit

Încă nu

Păstrează fiecare comandă separată de încercările sale de plată, folosește un orderId unic pentru fiecare încercare și îndeplinește fiecare comandă o singură dată.

→ Vezi: Modelul de comandă și plată backend, mai jos

5. Am decis cum să reconciliem tranzacțiile furnizorului, sumele primite, comisioanele și moneda de decontare?

Da, avem un proces

Încă nu

Stochează ID-ul tranzacției Volet.com, suma primită și moneda de decontare cu fiecare comandă, astfel încât fiecare plată să se potrivească cu o factură.

→ Vezi: Modelul de comandă și plată backend, mai jos

6. Am bugetat pentru scenarii de eșec, QA end-to-end și monitorizarea producției?

Da, este în plan

Încă nu

Estimează calea fericită și căile de eșec separat: timeout-uri, facturi expirate și încercări repetate necesită timp real de inginerie.

→ Vezi: Estimează munca în mod realist, mai jos

7. Am decis cum să gestionăm subplățile, plățile excesive, plățile întârziate și plățile pe rețele greșite?

Da, regulile noastre sunt stabilite

Încă nu

Setările gateway-ului decid dacă subplățile și plățile excesive sunt acceptate. Plățile trimise prin rețeaua greșită pot fi pierdute. Scrie regulile tale și politica de returnare în termenii de vânzare.

→ Vezi: Cum diferă plățile cripto de plățile cu cardul, mai jos

8. Știe finanțele în ce monedă se decontează plățile și cum este prețuită conversia?

Da, finanțele știu

Încă nu

Poți păstra cripto pe care îl primești sau îl poți converti automat. USD, USDT și USDC se convertesc la o rată fixă de 1:1; alte conversii costă suplimentar.

→ Vezi: Ce costă cu Volet.com, mai jos

9. Am planificat cum să testăm cu plăți reale, având în vedere că nu există sandbox?

Da, avem un plan de testare

Încă nu

Volet.com nu are sandbox. Solicită o demonstrație live, creează gateway-ul devreme și testează cu plăți reale înainte de lansare.

→ Vezi: Testare fără un sandbox, mai jos

Rezultatul tău

Răspunde la toate cele nouă întrebări pentru a vedea rezultatul tău.

Încă deschis:

 

Cum diferă plățile cripto de plățile cu cardul

Dacă echipa ta a integrat plăți cu cardul înainte, unele obiceiuri nu se vor transfera. Cu cardurile, comerciantul percepe o taxă clientului. Cu cripto, clientul trimite fonduri din propriul portofel, iar sistemul tău trebuie să reacționeze la ceea ce ajunge efectiv. Aceasta schimbă ceea ce trebuie să gestioneze integrarea.

Suma poate diferi de factură. Un client poate trimite puțin mai puțin sau mai mult decât s-a solicitat, de exemplu din cauza taxelor de rețea sau a diferențelor de curs valutar. Decide dinainte dacă să accepți subplata și supraplata.

De exemplu, poți accepta diferențe mici, contacta clientul sau emite o rambursare. Indiferent de ceea ce decizi, menționează-l în termenii tăi de vânzare, împreună cu regulile tale de rambursare și cine plătește taxa de rețea pentru o rambursare.

Rețeaua contează. Același token există pe mai multe blockchain-uri. Fondurile trimise prin rețeaua greșită sau la adresa greșită pot fi pierdute.

Cotația expiră. O rată a facturii este valabilă timp de 60 de minute dacă te stabilești în aceeași monedă și timp de 15 minute dacă este necesară conversia. Un client care plătește târziu poate avea nevoie de o nouă solicitare de plată.

Confirmarea durează. Fondurile sunt creditate doar după ce blockchain-ul confirmă plata, așa că interfața și logica comenzii tale trebuie să gestioneze așteptarea.

Nu există returnări și nu există reversări automate. O tranzacție confirmată pe blockchain nu poate fi anulată. O rambursare este o plată separată conform politicii tale și regulilor de protecție a consumatorilor aplicabile.

Reglarea este o decizie de afaceri. Fondurile sunt creditate în contul tău Volet.com odată ce plata este finalizată. Poți păstra cripto pe care l-ai primit sau îl poți converti automat în stablecoins sau fiat, astfel încât finanțele să poată reconcilia într-o singură monedă și să evite volatilitatea.


Mai multe detalii: Taxele pentru contul de afaceri Volet.com


Ce se ocupă Volet.com

Confirmările rețelei gestionate pentru tine. Volet.com monitorizează blockchain-ul, așteaptă confirmările necesare și creditează fondurile, astfel încât backend-ul tău să nu trebuiască să urmărească blocurile sau numărul de confirmări.

Un sold de stablecoin pe rețele. Un stablecoin primit pe o rețea poate fi retras printr-o altă rețea suportată fără un serviciu separat de pod între lanțuri.

Fără rezervă rulantă. Volet.com nu reține o parte din plățile tale finalizate ca rezervă rulantă.

Regulile tale pentru subplată și supraplata. În setările gateway-ului decizi dacă să accepți plăți care sunt sub sau peste suma facturii. De exemplu, dacă clienții își completează un sold la tine, poți credita exact ceea ce a sosit și accepta subplățile. Cu o supraplata, doar suma comenzii este creditată în contul tău.

Plățile întârziate gestionate. Dacă o plată sosește după ce factura a expirat, Volet.com fie o returnează clientului, fie, în unele cazuri, o creditează în contul tău.

Bani în, bani afară. Același sold Volet.com poate finanța plățile tale de ieșire: plăți în masă către contractori, creatori sau parteneri, sau retrageri pentru utilizatorii tăi. De exemplu, un schimb poate accepta depozitele cripto ale utilizatorilor și procesa retragerile lor cripto din același sold Volet.com prin API.

Volet.com te ajută să construiești plăți globale
În fiat, cripto și stablecoin. Prin API, Hosted Checkout sau pluginuri ușor de instalat. Acceptă, trimite și gestionează fonduri – totul din cod.

API sau Checkout Gazduit: o comparație practică

Decizia cheie este cât de mult din experiența de plată trebuie să dețină produsul tău — și cât de mult efort de inginerie ești pregătit să investești în el.

Alege doar API când ai nevoie de propria interfață de plată și control asupra întregului funnel de plată. Aplicația ta deține fiecare pas orientat către client, de la afișarea instrucțiunilor de plată până la menținerea clientului informat până când plata este confirmată sau expiră. Echipa ta construiește și întreține totul.


Ghidurile Volet.com: Integrarea API


Alegeți Hosted Checkout atunci când o interfață de plată personalizată și controlul total asupra fiecărui pas nu sunt cerințe. Volet.com găzduiește pagina de plată, făcând aceasta, în general, calea mai simplă și cu un efort mai mic. De asemenea, funcționează în interiorul boturilor Telegram și al mini-aplicațiilor, unde pagina de plată se deschide într-o fereastră de browser în aplicație (webview).


Citeste mai mult: Paiementele cripto în aplicațiile mini Telegram — Ghid de configurare, reguli pentru stele și taxe reale


De asemenea, poți combina Checkout-ul găzduit cu API-ul pentru căutarea comenzilor și reconciliere. În orice caz, Checkout-ul găzduit necesită totuși muncă de backend. Aplicația ta păstrează propriile înregistrări ale comenzilor și le potrivește cu starea plății de pe partea Volet.com. Backend-ul tău semnează de asemenea cererile pe care le trimite către Checkout-ul găzduit, ceea ce ajută la protejarea împotriva cererilor manipulate care ar putea redirecționa plata unui client de la magazinul tău.

Factor de decizieNumai APICheckout găzduit
Interfața de plată pentru cliențiConstruită și întreținută de echipa taGăzduită de Volet.com
Control asupra canalului de platăRidicat: aplicația ta deține experiențaMai limitat: clientul urmează fluxul găzduit
Efort de inginerieMai mare: UI, verificări de stare, expirare și cazuri limităMai mic pentru UI de plată; backend-ul semnează în continuare cererile de plată, gestionează notificările și actualizează comenzile
Cel mai potrivitCheckout personalizat pe un site web sau într-o aplicație, bot sau platformăUn flux standard de plată în care redirecționarea către o pagină găzduită este acceptabilă, inclusiv boturi Telegram și aplicații mini
Gestionarea stăriiBackend-ul verifică starea plății prin APINotificări URL de stare plus căutare API pentru reconciliere după cum este necesar
Plata dintr-un sold de cont Volet.comNu este disponibil: Numai API acceptă cripto din portofele externeDisponibil: clienții pot plăti din soldul contului lor Volet.com, taxă 0.25%

Ghidurile Volet.com: Integrarea Hosted Checkout


Volet.com te ajută să construiești plăți globale
În fiat, cripto și stablecoin. Prin API, Hosted Checkout sau pluginuri ușor de instalat. Acceptă, trimite și gestionează fonduri – totul din cod.

Ce trebuie să construiască echipa ta

Punctele finale ale facturii sunt doar o parte a unei implementări API-only. Înainte de a te angaja, ia în considerare responsabilitățile de produs și operaționale de mai jos.

Cum funcționează fluxul cu API-only:

  1. Crează comanda în propriul tău sistem.
  2. Crează o factură crypto prin API.
  3. Arată clientului adresa, suma, moneda, rețeaua și timpul de expirare returnate de API.
  4. Clientul trimite plata din portofelul său.
  5. Backend-ul tău verifică starea plății prin API.
  6. Odată ce plata este confirmată, marchează comanda ca plătită și îndeplinește-o.

Cum funcționează fluxul cu Hosted Checkout și API:

  1. Crează comanda în sistemul tău și redirecționează clientul către Hosted Checkout cu orderId.
  2. Clientul plătește pe pagina Hosted Checkout.
  3. Volet.com trimite o notificare către URL-ul tău de Status, endpoint-ul de pe serverul tău care primește actualizări de plată.
  4. Backend-ul tău verifică semnătura și, dacă este necesar, confirmă comanda prin API.
  5. Marchează comanda ca plătită și îndeplinește-o.

UI-ul de plată și ciclul de viață al facturii. Aplicația ta trebuie să afișeze cu exactitate detaliile plății returnate de API: suma de trimis, moneda, rețeaua blockchain, adresa, orice etichetă de destinație sau memo și timpul de expirare. Ar trebui să avertizeze clienții să trimită fonduri doar prin rețeaua specificată. Instrucțiunile de plată incorecte pot duce la pierderea fondurilor, așa că aceasta este o cerință funcțională, nu un detaliu vizual.

Nu spune clientului că o plată a eșuat sau s-a finalizat înainte ca starea plății să o confirme.

Modelul de comandă și plată backend. Păstrează comanda ta internă separată de o încercare de plată sau factură. Acest lucru face mai ușor să gestionezi abandonările de checkout, facturile expirate, un client care încearcă din nou și actualizările de stare care sosesc după ce utilizatorul a părăsit pagina.

Utilizați un orderId unic pentru fiecare încercare de plată, așa cum descrie documentația API. Definiți în propria bază de date cum se mapează fiecare încercare la comandă. Stocați ID-ul tranzacției Volet.com, suma primită și moneda de decontare cu fiecare comandă, astfel încât finanțele să poată asocia fiecare plată cu o factură fără foi de calcul manuale. Tratamentul fiscal al chitanțelor crypto depinde de jurisdicția dumneavoastră, așa că conveniți asupra acestuia cu contabilul dumneavoastră.

Alege modelul sumei facturii. Decide dacă comanda este prețuită în moneda pe care te aștepți să o primești sau dacă clientul ar trebui să trimită o sumă fixă de criptomonedă specifică. Această alegere afectează afișarea prețului, reconcilierea și modul în care explici suma datorată. Aliniază-l cu modelul tău de prețuri și contabilitate și validează valorile calculate înainte de a crea facturi live. Documentația API explică cum să configurezi fiecare opțiune.


Ghidurile Volet.com: integrarea API


Să presupunem că clientul dumneavoastră plasează o comandă de 120 € și plătește în crypto. Backend-ul dumneavoastră ar trebui să păstreze suficiente informații pentru a asocia plata finalizată cu comanda originală. Pentru această plată, ar stoca:

  • ID-ul comenzii dumneavoastră (ORD-10482) identifică achiziția în sistemul dumneavoastră.
  • ID-ul tranzacției Volet.com (VLT-839201) leagă plata de tranzacția de pe partea Volet.com.
  • Suma primită (aproximativ 139 USDT) arată ce a trimis efectiv clientul.
  • Moneda de decontare (EUR) înregistrează moneda în care echipa dumneavoastră financiară contabilizează.
  • Starea plății (finalizată, confirmată de API) vă spune dacă plata poate fi considerată completă.

Pentru a reconcilia, asociați tranzacția Volet.com cu încercarea dumneavoastră de plată și comanda, apoi comparați ID-ul tranzacției, sumele așteptate și primite, moneda și starea finală a plății. Dacă o plată lipsește, este întârziată sau nu se potrivește cu suma așteptată, marcați-o pentru investigație în loc să marcați automat comanda ca plătită.

Un client creează o comandă, deschide pagina de plată și trimite criptomoneda necesară. Înainte ca blockchain-ul să confirme tranzacția, închide tab-ul browser-ului și părăsește site-ul tău.

Backend-ul tău continuă să urmărească plata:

  1. Comanda clientului rămâne în așteptare în sistemul tău.
  2. Încercarea de plată continuă independent. Cu API-only, backend-ul tău verifică statusul prin API. Cu Hosted Checkout, Volet.com trimite o notificare către URL-ul tău de Status.
  3. Backend-ul tău verifică statusul plății prin API.
  4. Odată ce plata este confirmată ca fiind completă, sistemul tău marchează comanda ca plătită și declanșează îndeplinirea.
  5. Dacă clientul se întoarce pe site-ul tău, va vedea statusul actualizat al comenzii.

Punctul important: închiderea paginii de checkout nu anulează plata sau o confirmă. Backend-ul tău, nu redirecționarea browser-ului, determină când comanda poate fi îndeplinită.

Gestionarea stării și recuperarea. Cu API-only, echipa ta trebuie să aleagă o strategie de polling (cât de des backend-ul verifică starea), să evite cererile inutile și să gestioneze eșecurile temporare de căutare fără a schimba incorect starea comenzii.

Tratează o notificare ca pe un semnal, nu ca pe o dovadă de plată: verifică semnătura acesteia și caută comanda prin API înainte de a o îndeplini. Procesează fiecare comandă o singură dată, folosind propriul orderId, astfel încât o notificare repetată sau o a doua verificare a stării să nu o poată îndeplini de două ori.

Îndeplinește o comandă doar după ce API-ul confirmă că plata este completă, nu când crearea facturii reușește sau browserul redirecționează. Valorile exacte ale stării și modul de gestionare a fiecărei valori sunt descrise în documentația API.


Ghidurile Volet.com: integrarea API


A request can time out even when the remote system has processed it. Do not blindly retry invoice creation after an ambiguous failure. Before deciding what to do next, log the API's errorId, check the existing order and payment state, and follow the documented error handling. Never create a duplicate order automatically, and retry a request only when it is safe to do so.

Securitate și pregătire operațională. Păstrează secretele API și acreditivele de autentificare pe server. Nu le expune niciodată în codul frontend, aplicații mobile, boți sau scripturi de client. Configurează doar permisiunile necesare integrării și restricționează accesul API la adresele IP ale serverelor tale: permiterea tuturor IP-urilor nu este recomandată în producție.

Proiectarea unui flux de plată fiabil

Un flux de plată trebuie să gestioneze mai mult decât cazul de succes.

Decide ce ar trebui să facă produsul atunci când:

  • crearea facturii expiră și rezultatul este necunoscut;
  • o căutare a stării eșuează temporar;
  • o factură expiră înainte ca clientul să plătească;
  • clientul abandonează checkout-ul și revine mai târziu;
  • clientul începe o altă încercare de plată;
  • o notificare de stare este întârziată sau primită de mai multe ori.

Scopul este de a evita îndeplinirea duplicată, de a menține starea internă a comenzii consistentă și de a oferi clientului un pas clar următor.


Ghidurile Volet.com: ghid API cu definiții exacte ale stării și câmpuri de răspuns


Testare fără un sandbox

Volet.com nu are un sandbox sau un mediu de testare. Planifică acest lucru din timp în loc să-l descoperi la lansare:

  • Solicită o demonstrație live de la echipa de vânzări Volet.com pentru a vedea fluxul de plată, API-ul și Hosted Checkout înainte de a construi.
  • Crează gateway-ul devreme. Un nou gateway custodial (unul în care Volet.com deține fondurile primite pe contul tău) trece printr-o revizuire de conformitate care durează de obicei câteva ore, iar tu poți finaliza integrarea între timp.
  • Testează cu plăți reale în producție: succes, eșec, expirare, subplată și supraplata. Fiecare plată de testare crypto este o tranzacție reală pe blockchain cu o taxă de rețea.
  • Pentru Hosted Checkout, verifică de asemenea livrarea Status URL, validarea semnăturii și redirecționările de succes și eșec.
  • Marchează comenzile de testare în baza ta de date astfel încât să nu se amestece cu veniturile reale în timpul reconciliării.

Estimarea muncii în mod realist

Efortul real depinde de arhitectura ta existentă de checkout, experiența utilizatorului necesară, experiența inginerilor tăi cu API-urile de plată și domeniul de testare (QA).

Flux de lucruAPI-onlyHosted Checkout
Configurarea contului și a gateway-uluiVerificarea contului, configurarea API-ului, permisiuni și aprobatVerificarea contului, configurarea Hosted Checkout și orice aprobat necesar
Implementare de bazăCrearea facturii, UI de plată, verificări de stare și actualizări ale comenziiFlux de redirecționare, gestionarea Status URL și actualizări ale comenzii în backend
Cazuri limităExpirare, timeouturi ambigue, reîncercări, încercări duplicate și instrucțiuni de rețeaValidarea notificărilor, cazuri limită de redirecționare și reconciliere
Asigurarea calitățiiAfișarea detaliilor plății, verificări de stare, expirare, eșecuri și recuperareRedirecționări, livrarea notificărilor, validarea semnăturilor și reconcilierea
Proprietate continuăÎntreținerea UI, monitorizarea, diagnosticele de suport și gestionarea stăriiMonitorizarea backend, reconcilierea comenzilor și operațiunile de apel înapoi

Estimează calea de succes și căile de eșec separat și include timp pentru testarea end-to-end și monitorizarea producției.

Ce costă cu Volet.com

De la 0,25% pentru plățile în stablecoin și criptomonede. Conversiile între USD, USDT și USDC se efectuează la o rată fixă de 1:1; alte conversii sunt prețuite separat. Clientul plătește taxa de rețea blockchain. Fără taxă de configurare și fără taxă lunară. Tu alegi cine plătește taxa de procesare. Volumele mari pot beneficia de prețuri personalizate prin vânzări.

Acceptă USDT, USDC și principalele monede cripto din toată lumea
Începe cu gateway-ul de plăți cripto – decontări instant și comisioane de la 0,25%

Întrebări frecvente

Nu. Volet.com nu are un mediu de testare. Poți solicita o demonstrație live de la echipa de vânzări. Testează succesul, eșecul, expirarea, subplata și supraplata de partea ta înainte de lansare.

Noile gateway-uri de custodie trec mai întâi printr-o revizuire de conformitate. De obicei, durează câteva ore. Contul tău trebuie să fie verificat înainte de a crea gateway-ul. Folosește timpul de așteptare pentru a finaliza integrarea.

Nu. Cu API doar, backend-ul tău verifică singur starea plății. Dacă ai nevoie de notificări, folosește Hosted Checkout împreună cu API-ul.

Setările gateway-ului tău decid dacă subplățile și supraplățile sunt acceptate. Dacă o plată ajunge după ce factura a expirat, Volet.com fie o returnează clientului, fie, în unele cazuri, o creditează în contul tău. Un client care dorește încă să plătească poate avea nevoie de o nouă solicitare de plată.

Caută comanda prin API folosind orderId-ul tău înainte de a răspunde.

O transferare poate fi vizibilă pe blockchain și totuși să nu se potrivească cu factura: poate fi scurtă, întârziată sau trimisă printr-o altă rețea.

Oferă echipei tale de suport acces la detaliile plății și conveniți dinainte când să escaladeze un caz la suportul Volet.com.

Nu. O tranzacție confirmată pe blockchain nu poate fi anulată și nu există returnări de fonduri prin rețeaua de carduri. O returnare este o plată separată conform politicii tale și regulilor de protecție a consumatorilor aplicabile.

Nu. Volet.com nu oferă achiziționarea de carduri. Păstrează-ți achizitorul de carduri pentru plăți directe cu cardul.