Integrazione API di pagamento in criptovaluta: cosa deve realmente costruire il tuo team

Una guida pre-lancio e una suddivisione video passo-passo

Domanda {{n}} di {{t}}

Pronto per andare live

Il tuo team ha risposte alle domande chiave. Sei vicino al lancio: esegui i tuoi test con pagamenti reali prima di andare live.

Quasi lì

Rimangono alcuni gap. Chiudili prima del lancio: ognuno è trattato in una sezione di questo articolo.

Non pronto ancora

Diverse decisioni chiave sono ancora aperte. Hosted Checkout toglie il maggior lavoro dal tuo team, e puoi richiedere una demo dal vivo dal team vendite di Volet.com per vedere prima il flusso di pagamento.

Checklist pre-lancio API

Nove domande a cui rispondere prima di andare live. Scegli la risposta che si adatta al tuo team: ogni risposta apre una nota breve e punta alla parte di questo articolo che la spiega.

Domanda 1 di 9

1. Il prodotto richiede un'interfaccia di pagamento personalizzata?

Sì, abbiamo bisogno della nostra UI

No, una pagina ospitata funziona

Non deciso ancora

Se sì, hai bisogno solo dell'API, e il tuo team costruisce e mantiene gli schermi di pagamento. Se no, Hosted Checkout è il percorso a minor sforzo, e accetta anche pagamenti dai saldi dell'account Volet.com.

→ Vedi: API o Hosted Checkout: un confronto pratico, qui sotto

2. Dobbiamo controllare ogni passaggio del funnel di pagamento, o un reindirizzamento è accettabile?

Dobbiamo controllare ogni passaggio

Un reindirizzamento va bene

Non deciso ancora

Con un reindirizzamento a Hosted Checkout, Volet.com invia notifiche di stato al tuo URL di stato. Con la tua UI di pagamento sull'API, il tuo backend deve controllare lo stato del pagamento da solo.

→ Vedi: API o Hosted Checkout: un confronto pratico, qui sotto

3. Abbiamo la capacità di costruire e mantenere l'interfaccia di pagamento, la gestione delle scadenze e i controlli di stato?

Sì, abbiamo la capacità

No, Hosted Checkout ci si adatta meglio

Non sicuro ancora

Solo API significa che il tuo team possiede gli schermi di pagamento, la scadenza della fattura (una tariffa di fattura è valida per 60 o 15 minuti) e controlli di stato regolari.

→ Vedi: Cosa deve realmente costruire il tuo team, qui sotto

4. Abbiamo definito come gli ordini interni si mappano ai tentativi di pagamento e come verrà prevenuta la duplicazione dell'adempimento?

Sì, è definito

Non ancora

Mantieni ogni ordine separato dai suoi tentativi di pagamento, usa un orderId unico per ogni tentativo e adempie ogni ordine solo una volta.

→ Vedi: Modello di ordine e pagamento backend, qui sotto

5. Abbiamo deciso come riconciliare le transazioni del fornitore, gli importi ricevuti, le commissioni e la valuta di regolamento?

Sì, abbiamo un processo

Non ancora

Memorizza l'ID della transazione Volet.com, l'importo ricevuto e la valuta di regolamento con ogni ordine, in modo che ogni pagamento corrisponda a una fattura.

→ Vedi: Modello di ordine e pagamento backend, qui sotto

6. Abbiamo previsto scenari di fallimento, QA end-to-end e monitoraggio della produzione?

Sì, è nel piano

Non ancora

Stima il percorso felice e i percorsi di fallimento separatamente: timeout, fatture scadute e tentativi ripetuti richiedono tempo reale di ingegneria.

→ Vedi: Stima il lavoro in modo realistico, qui sotto

7. Abbiamo deciso come gestire sotto pagamento, sovrapagamento, pagamenti in ritardo e pagamenti su reti sbagliate?

Sì, le nostre regole sono impostate

Non ancora

Le impostazioni del gateway decidono se i sotto pagamenti e i sovrapagamenti sono accettati. I pagamenti inviati attraverso la rete sbagliata possono andare persi. Scrivi le tue regole e la politica di rimborso nei tuoi termini di vendita.

→ Vedi: Come i pagamenti in crypto differiscono dai pagamenti con carta, qui sotto

8. La finanza sa in quale valuta si regolano i pagamenti e come viene valutata la conversione?

Sì, la finanza sa

Non ancora

Puoi tenere la crypto che ricevi o convertirla automaticamente. USD, USDT e USDC si convertono a un tasso fisso di 1:1; altre conversioni costano extra.

→ Vedi: Quanto costa con Volet.com, qui sotto

9. Abbiamo pianificato come testare con pagamenti reali, dato che non c'è sandbox?

Sì, abbiamo un piano di test

Non ancora

Volet.com non ha sandbox. Richiedi una demo dal vivo, crea il gateway in anticipo e testa con pagamenti reali prima del lancio.

→ Vedi: Testare senza sandbox, qui sotto

Il tuo risultato

Rispondi a tutte e nove le domande per vedere il tuo risultato.

Ancora aperto:

 

Come i pagamenti in criptovaluta differiscono dai pagamenti con carta

Se il tuo team ha già integrato i pagamenti con carta, alcune abitudini non si trasferiranno. Con le carte, il commerciante addebita il cliente. Con le criptovalute, il cliente invia fondi dal proprio portafoglio e il tuo sistema deve reagire a ciò che arriva effettivamente. Questo cambia ciò che l'integrazione deve gestire.

L'importo può differire dalla fattura. Un cliente può inviare leggermente meno o più di quanto richiesto, ad esempio a causa di commissioni di rete o differenze di cambio. Decidi in anticipo se accettare sotto pagamento e sovrapagamento.

Ad esempio, puoi accettare piccole differenze, contattare il cliente o emettere un rimborso. Qualunque cosa tu decida, dichiaralo nei tuoi termini di vendita, insieme alle tue regole di rimborso e a chi paga la commissione di rete su un rimborso.

La rete è importante. Lo stesso token esiste su più blockchain. I fondi inviati attraverso la rete sbagliata o all'indirizzo sbagliato possono andare persi.

La quotazione scade. Un tasso di fattura è valido per 60 minuti se si regola nella stessa valuta e per 15 minuti se è necessaria una conversione. Un cliente che paga in ritardo potrebbe aver bisogno di una nuova richiesta di pagamento.

La conferma richiede tempo. I fondi vengono accreditati solo dopo che la blockchain conferma il pagamento, quindi la tua interfaccia e la logica degli ordini devono gestire l'attesa.

Non ci sono chargeback e nessuna reversibilità automatica. Una transazione confermata on-chain non può essere annullata. Un rimborso è un pagamento separato secondo la tua politica e le normative sulla protezione dei consumatori applicabili.

Il regolamento è una decisione aziendale. I fondi vengono accreditati sul tuo account Volet.com una volta completato il pagamento. Puoi mantenere le criptovalute ricevute o convertirle automaticamente in stablecoin o fiat, in modo che la finanza possa riconciliare in un'unica valuta ed evitare la volatilità.


Ulteriori dettagli: Commissioni per il conto aziendale di Volet.com


Cosa gestisce Volet.com

Conferme di rete gestite per te. Volet.com monitora la blockchain, attende le conferme richieste e accredita i fondi, quindi il tuo backend non deve tenere traccia dei blocchi o dei conteggi delle conferme.

Un saldo di stablecoin su più reti. Una stablecoin ricevuta su una rete può essere prelevata attraverso un'altra rete supportata senza un servizio di ponte cross-chain separato.

Nessuna riserva rotativa. Volet.com non trattiene parte dei tuoi pagamenti completati come riserva rotativa.

Le tue regole per sotto pagamento e sovrapagamento. Nelle impostazioni del gateway decidi se accettare pagamenti che sono inferiori o superiori all'importo della fattura. Ad esempio, se i clienti ricaricano un saldo con te, puoi accreditare esattamente ciò che è arrivato e accettare sotto pagamenti. Con un sovrapagamento, solo l'importo dell'ordine viene accreditato sul tuo conto.

Gestione dei pagamenti in ritardo. Se un pagamento arriva dopo la scadenza della fattura, Volet.com lo restituisce al cliente o, in alcuni casi, lo accredita sul tuo conto.

Denaro in, denaro fuori. Lo stesso saldo di Volet.com può finanziare i tuoi pagamenti in uscita: pagamenti di massa a appaltatori, creatori o partner, o prelievi per i tuoi utenti. Ad esempio, un exchange può accettare i depositi in crypto degli utenti e elaborare i loro prelievi in crypto dallo stesso saldo di Volet.com tramite l'API.

Volet.com ti aiuta a costruire i pagamenti globali
In fiat, crypto e stablecoin. Tramite API, hosted checkout o plugin facili da installare. Accetta, invia e gestisci i fondi – tutto dal codice.

API o Checkout Ospitato: un confronto pratico

La decisione chiave è quanto della esperienza di pagamento il tuo prodotto deve possedere — e quanto sforzo ingegneristico sei disposto a investire in esso.

Scegli API-only quando hai bisogno della tua interfaccia di pagamento e controllo su tutto il funnel di pagamento. La tua applicazione possiede ogni passaggio rivolto al cliente, dall'indicazione delle istruzioni di pagamento fino a mantenere il cliente informato fino a quando il pagamento non è confermato o scade. Il tuo team costruisce e mantiene tutto questo.


Guide di Volet.com: integrazione API


Scegli Hosted Checkout quando un'interfaccia di pagamento personalizzata e il controllo completo su ogni passaggio non sono requisiti. Volet.com ospita la pagina di pagamento, rendendo questo generalmente il percorso più semplice e con meno sforzo. Funziona anche all'interno di bot Telegram e mini app, dove la pagina di pagamento si apre in una finestra del browser in-app (webview).


Leggi di più: Pagamenti in Crypto nelle Mini App di Telegram — Guida all'Impostazione, Regole delle Stelle & Tariffe Reali


Puoi anche combinare il Checkout Ospitato con l'API per la ricerca degli ordini e la riconciliazione. In ogni caso, il Checkout Ospitato richiede comunque lavoro di backend. La tua applicazione mantiene i propri registri degli ordini e li abbina allo stato del pagamento sul lato di Volet.com. Il tuo backend firma anche le richieste che invia al Checkout Ospitato, il che aiuta a proteggere contro richieste manomesse che potrebbero reindirizzare il pagamento di un cliente lontano dal tuo negozio.

Fattore decisionaleSolo APICheckout Ospitato
Interfaccia di pagamento a contatto con il clienteCostruita e mantenuta dal tuo teamOspitata da Volet.com
Controllo sul funnel di pagamentoAlto: la tua applicazione possiede l'esperienzaPiù limitato: il cliente segue il flusso ospitato
Sforzo ingegneristicoMaggiore: UI, controlli di stato, scadenza e casi limiteMinore per l'interfaccia di pagamento; il backend firma comunque le richieste di pagamento, gestisce le notifiche e aggiorna gli ordini
Migliore adattamentoCheckout personalizzato su un sito web o in un'app, bot o piattaformaUn flusso di pagamento standard in cui è accettabile reindirizzare a una pagina ospitata, inclusi bot di Telegram e mini app
Gestione dello statoIl backend controlla lo stato del pagamento tramite l'APINotifiche dell'URL di stato più ricerca API per riconciliazione secondo necessità
Pagamento da un saldo dell'account Volet.comNon disponibile: solo API accetta crypto da portafogli esterniDisponibile: i clienti possono pagare dal loro saldo dell'account Volet.com, commissione 0,25%

Guide di Volet.com: Integrazione di Hosted Checkout


Volet.com ti aiuta a costruire i pagamenti globali
In fiat, crypto e stablecoin. Tramite API, hosted checkout o plugin facili da installare. Accetta, invia e gestisci i fondi – tutto dal codice.

Cosa deve realmente costruire il tuo team

Gli endpoint delle fatture sono solo una parte di un'implementazione solo API. Prima di impegnarti, considera le responsabilità di prodotto e operative qui sotto.

Come funziona il flusso con solo API:

  1. Crea l'ordine nel tuo sistema.
  2. Crea una fattura crypto tramite l'API.
  3. Mostra al cliente l'indirizzo, l'importo, la valuta, la rete e il tempo di scadenza restituiti dall'API.
  4. Il cliente invia il pagamento dal proprio wallet.
  5. Il tuo backend controlla lo stato del pagamento tramite l'API.
  6. Una volta confermato il pagamento, segna l'ordine come pagato e completalo.

Come funziona il flusso con Hosted Checkout e l'API:

  1. Crea l'ordine nel tuo sistema e reindirizza il cliente a Hosted Checkout con il tuo orderId.
  2. Il cliente paga sulla pagina di Hosted Checkout.
  3. Volet.com invia una notifica al tuo Status URL, l'endpoint sul tuo server che riceve gli aggiornamenti di pagamento.
  4. Il tuo backend verifica la firma e, se necessario, conferma l'ordine tramite l'API.
  5. Segna l'ordine come pagato e completalo.

Interfaccia di pagamento e ciclo di vita della fattura. La tua applicazione deve visualizzare accuratamente i dettagli del pagamento restituiti dall'API: importo da inviare, valuta, rete blockchain, indirizzo, eventuale tag di destinazione o memo e tempo di scadenza. Dovrebbe avvisare i clienti di inviare fondi solo attraverso la rete specificata. Istruzioni di pagamento errate possono comportare la perdita di fondi, quindi questo è un requisito funzionale, non un dettaglio visivo.

Non dire al cliente che un pagamento è fallito o completato prima che lo stato del pagamento lo confermi.

Modello di ordine e pagamento backend. Mantieni il tuo ordine interno separato da un tentativo di pagamento o fattura. Questo rende più facile gestire i checkout abbandonati, le fatture scadute, un cliente che riprova e gli aggiornamenti di stato che arrivano dopo che l'utente ha lasciato la pagina.

Usa un orderId unico per ogni tentativo di pagamento, come descritto nella documentazione API. Definisci nel tuo database come ogni tentativo si mappa all'ordine. Memorizza l'ID della transazione Volet.com, l'importo ricevuto e la valuta di regolamento con ogni ordine, in modo che la finanza possa abbinare ogni pagamento a una fattura senza fogli di calcolo manuali. Il trattamento fiscale delle ricevute crypto dipende dalla tua giurisdizione, quindi concordalo con il tuo commercialista.

Scegli il modello di importo della fattura. Decidi se l'ordine è prezzato nella valuta che ti aspetti di ricevere o se il cliente deve inviare un importo fisso di una specifica criptovaluta. Questa scelta influisce sulla visualizzazione del prezzo, sulla riconciliazione e su come spieghi l'importo dovuto. Allinealo con il tuo modello di prezzo e contabilità e valida i valori calcolati prima di creare fatture live. La documentazione API spiega come impostare ciascuna opzione.


Guide di Volet.com: integrazione API


Supponiamo che il tuo cliente effettui un ordine di €120 e paghi in criptovaluta. Il tuo backend dovrebbe conservare sufficienti informazioni per abbinare il pagamento completato all'ordine originale. Per questo pagamento, dovrebbe memorizzare:

  • Il tuo ID ordine (ORD-10482) identifica l'acquisto nel tuo sistema.
  • L'ID transazione di Volet.com (VLT-839201) collega il pagamento alla transazione sul lato di Volet.com.
  • L'importo ricevuto (circa 139 USDT) mostra ciò che il cliente ha effettivamente inviato.
  • La valuta di regolamento (EUR) registra la valuta in cui il tuo team finanziario contabilizza.
  • Lo stato del pagamento (finale, confermato dall'API) ti dice se il pagamento può essere considerato completo.

Per riconciliare, abbina la transazione di Volet.com al tuo tentativo di pagamento e all'ordine, quindi confronta l'ID transazione, gli importi attesi e ricevuti, la valuta e lo stato finale del pagamento. Se un pagamento è mancante, in ritardo o non corrisponde all'importo atteso, segnalalo per un'indagine invece di contrassegnare automaticamente l'ordine come pagato.

Un cliente crea un ordine, apre la pagina di pagamento e invia la criptovaluta richiesta. Prima che la blockchain confermi la transazione, chiude la scheda del browser e lascia il tuo sito web.

Il tuo backend continua a monitorare il pagamento:

  1. L'ordine del cliente rimane in attesa nel tuo sistema.
  2. Il tentativo di pagamento continua in modo indipendente. Con solo API, il tuo backend controlla il suo stato tramite l'API. Con Hosted Checkout, Volet.com invia una notifica al tuo URL di stato.
  3. Il tuo backend verifica lo stato del pagamento tramite l'API.
  4. Una volta che il pagamento è confermato come completato, il tuo sistema segna l'ordine come pagato e attiva l'evasione.
  5. Se il cliente torna al tuo sito web, vede lo stato dell'ordine aggiornato.

Il punto importante: chiudere la pagina di checkout non annulla il pagamento né lo conferma. Il tuo backend, non il reindirizzamento del browser, determina quando l'ordine può essere evaso.

Gestione dello stato e recupero. Con solo API, il tuo team deve scegliere una strategia di polling (con quale frequenza il backend controlla lo stato), evitare richieste non necessarie e gestire i fallimenti temporanei delle ricerche senza cambiare erroneamente lo stato dell'ordine.

Tratta una notifica come un segnale, non come prova di pagamento: verifica la sua firma e cerca l'ordine tramite l'API prima di evaderlo. Elabora ogni ordine una sola volta, utilizzando il tuo orderId, in modo che una notifica ripetuta o un secondo controllo dello stato non possano evaderlo due volte.

Evadi un ordine solo dopo che l'API conferma che il pagamento è completo, non quando la creazione della fattura ha successo o il browser reindirizza. I valori esatti dello stato e come gestire ciascuno di essi sono descritti nella documentazione dell'API.


Guide di Volet.com: integrazione API


Una richiesta può scadere anche quando il sistema remoto l'ha elaborata. Non riprovare automaticamente a creare la fattura dopo un errore ambiguo. Prima di decidere cosa fare dopo, registra l'errorId dell'API, controlla lo stato dell'ordine e del pagamento esistente e segui la gestione degli errori documentata. Non creare mai automaticamente un ordine duplicato e ripeti una richiesta solo quando è sicuro farlo.

Sicurezza e prontezza operativa. Mantieni i segreti API e le credenziali di autenticazione sul server. Non esporli mai nel codice frontend, nelle app mobili, nei bot o negli script lato client. Configura solo le autorizzazioni richieste dall'integrazione e limita l'accesso API agli indirizzi IP dei tuoi server: consentire tutti gli IP non è consigliato in produzione.

Progettare un flusso di pagamento affidabile

Un flusso di pagamento deve gestire più del caso di successo.

Decidi cosa dovrebbe fare il prodotto quando:

  • la creazione della fattura scade e il risultato è sconosciuto;
  • un controllo dello stato fallisce temporaneamente;
  • una fattura scade prima che il cliente paghi;
  • il cliente abbandona il checkout e torna in seguito;
  • il cliente inizia un altro tentativo di pagamento;
  • una notifica di stato è in ritardo o ricevuta più di una volta.

Lo scopo è evitare l'evasione duplicata, mantenere lo stato interno dell'ordine coerente e fornire al cliente un chiaro passo successivo.


Guide di Volet.com: guida API con definizioni esatte dello stato e campi di risposta


Testare senza un sandbox

Volet.com non ha un sandbox o un ambiente di test. Pianifica questo in anticipo invece di scoprirlo al lancio:

  • Richiedi una demo dal vivo dal team vendite di Volet.com per vedere il flusso di pagamento, l'API e il Checkout Ospitato prima di costruire.
  • Crea il gateway in anticipo. Un nuovo gateway custodiale (quello in cui Volet.com detiene i fondi ricevuti sul tuo account) passa attraverso una revisione di conformità che di solito richiede alcune ore, e puoi completare l'integrazione nel frattempo.
  • Testa con pagamenti reali in produzione: successo, fallimento, scadenza, sotto pagamento e sovrapagamento. Ogni pagamento di test in crypto è una vera transazione on-chain con una commissione di rete.
  • Per il Checkout Ospitato, controlla anche la consegna dell'URL di stato, la validazione della firma e i reindirizzamenti di successo e fallimento.
  • Contrassegna gli ordini di test nel tuo database in modo che non si mescolino con le entrate reali durante la riconciliazione.

Stimare il lavoro in modo realistico

Lo sforzo reale dipende dalla tua architettura di checkout esistente, dall'esperienza utente richiesta, dall'esperienza dei tuoi ingegneri con le API di pagamento e dall'ambito dei test (QA).

Flusso di lavoroSolo APICheckout Ospitato
Impostazione dell'account e del gatewayVerifica dell'account, configurazione API, autorizzazioni e approvazioneVerifica dell'account, configurazione del Checkout Ospitato e qualsiasi approvazione richiesta
Implementazione principaleCreazione della fattura, UI di pagamento, controlli di stato e aggiornamenti degli ordiniFlusso di reindirizzamento, gestione dell'URL di stato e aggiornamenti degli ordini backend
Casi limiteScadenza, timeout ambigui, ripetizioni, tentativi duplicati e istruzioni di reteValidazione delle notifiche, casi limite di reindirizzamento e riconciliazione
QAVisualizzazione dei dettagli di pagamento, controlli di stato, scadenza, errori e recuperoReindirizzamenti, consegna delle notifiche, validazione delle firme e riconciliazione
Proprietà continuaManutenzione dell'interfaccia utente, monitoraggio, diagnostica del supporto e gestione dello statoMonitoraggio del backend, riconciliazione degli ordini e operazioni di callback

Stima il percorso di successo e i percorsi di errore separatamente, e includi il tempo per il testing end-to-end e il monitoraggio della produzione.

Cosa costa con Volet.com

A partire dallo 0,25% per pagamenti in stablecoin e criptovalute. Le conversioni tra USD, USDT e USDC avvengono a un tasso fisso di 1:1; altre conversioni sono tariffate separatamente. Il cliente paga la commissione della rete blockchain. Nessuna tassa di attivazione e nessuna tassa mensile. Scegli tu chi paga la commissione di elaborazione. I volumi elevati possono qualificarsi per prezzi personalizzati tramite le vendite.

Accetta USDT, USDC e i principali token crypto in tutto il mondo
Inizia con il gateway di pagamento crypto – accrediti istantanei e commissioni da 0,25%

Domande Frequenti

No. Volet.com non ha un ambiente di test. Puoi richiedere una demo dal vivo al team di vendita. Testa il successo, il fallimento, la scadenza, il pagamento insufficiente e il pagamento eccessivo da parte tua prima del lancio.

I nuovi gateway di custodia devono prima passare attraverso una revisione di conformità. Di solito richiede alcune ore. Il tuo account deve essere verificato prima di creare il gateway. Usa il tempo di attesa per completare l'integrazione.

No. Con solo API, il tuo backend controlla autonomamente lo stato del pagamento. Se hai bisogno di notifiche, utilizza Hosted Checkout insieme all'API.

Le impostazioni del tuo gateway decidono se i pagamenti insufficienti eccessivi sono accettati. Se un pagamento arriva dopo che la fattura è scaduta, Volet.com lo restituisce al cliente o, in alcuni casi, lo accredita sul tuo account. Un cliente che desidera ancora pagare potrebbe aver bisogno di una nuova richiesta di pagamento.

Cerca l'ordine tramite l'API con il tuo orderId prima di rispondere.

Un trasferimento può essere visibile sulla blockchain e non corrispondere ancora alla fattura: potrebbe essere insufficiente, in ritardo o inviato tramite un'altra rete.

Dai al tuo team di supporto accesso ai dettagli del pagamento e concorda in anticipo quando devono escalare un caso al supporto di Volet.com.

No. Una transazione confermata sulla blockchain non può essere annullata e non ci sono chargeback della rete delle carte. Un rimborso è un pagamento separato secondo la tua politica e le normative sulla protezione dei consumatori applicabili.

No. Volet.com non fornisce acquisizione di carte. Mantieni il tuo acquirente di carte per i pagamenti diretti con carta.