API di un payment gateway crypto: fatture, webhook, payout e white label

Che cosa fa l'API di un payment gateway crypto?

L'API nasconde la blockchain al Suo codice. Invece di gestire nodi, derivare indirizzi e contare le conferme, chiama un endpoint per creare una fattura, salva l'identificativo del gateway e attende le notifiche. Il gateway quota il tasso di cambio, monitora le reti, applica lo screening AML e regola l'importo sul Suo saldo.

La maggior parte dei gateway espone gli stessi blocchi con nomi diversi: fatture o ordini per i pagamenti in entrata, IPN o callback per le notifiche, endpoint di conversione e saldo, payout o prelievi per i trasferimenti in uscita. Quasi tutti i provider offrono sandbox, ad esempio un host sandbox separato presso CoinGate e un account sandbox presso NOWPayments, da utilizzare prima di qualsiasi test su mainnet.

• API fatture: creare, leggere e annullare richieste di pagamento con prezzo in valuta tradizionale, coin accettate, riferimento d'ordine e URL di callback
• Notifiche: webhook o IPN a ogni cambio di stato, di solito firmati
• API payout: inviare crypto o valuta tradizionale a clienti, partner o al proprio wallet
• Tassi e valute: elencare coin supportate, reti, importi minimi e quotazioni in tempo reale
• Plugin e SDK: moduli pronti per le piattaforme e-commerce basati sulla stessa API

Come funziona il ciclo di vita di una fattura?

Ogni gateway ha un proprio modello di stati, quindi li riconduca a un piccolo insieme interno prima di scrivere la logica di business. Solo uno stato finale di pagamento completato dovrebbe rilasciare la merce; gli stati intermedi esistono perché una transazione può essere visibile on-chain molto prima di poter essere accettata in sicurezza.

La tabella associa due modelli di stato pubblicati agli stati di cui la maggior parte delle piattaforme ha bisogno. CoinGate, ad esempio, fa scadere una fattura non pagata dopo 20 minuti da quando il cliente ha scelto una coin e contrassegna come non valide le transazioni segnalate dai controlli AML.

Come si verificano webhook e IPN crypto?

Consideri ogni notifica non attendibile finché non è verificata. I gateway usano schemi diversi: NOWPayments firma il corpo JSON ordinato con HMAC-SHA512 e lo invia nell'header x-nowpayments-sig, CoinGate invia un token che Lei imposta sull'ordine, e BitPay consiglia di recuperare la fattura dall'API dopo ogni notifica invece di fidarsi del corpo.

Lo schema più sicuro combina le due cose: verificare la firma, poi leggere la fattura dall'API e agire su quella risposta. Costa una richiesta per cambio di stato e protegge da callback falsificati o ripetuti.

• Verificare le firme con un confronto a tempo costante e rifiutare le richieste non firmate
• Recuperare di nuovo la fattura tramite l'ID del gateway prima di cambiare lo stato dell'ordine
• Restituire rapidamente HTTP 200 ed elaborare in modo asincrono; i gateway ritentano in caso di errore
• Salvare ogni notifica con il suo evento o stato, così i duplicati vengono ignorati
• Non fidarsi mai di importi o valute inviati nel reindirizzamento del browser

Come gestire pagamenti insufficienti, eccedenti e tardivi?

Wallet ed exchange detraggono le commissioni di prelievo e i clienti copiano gli importi in modo imperfetto, quindi non si può dare per scontato il pagamento esatto. Definisca una tolleranza e una regola per ogni caso prima del lancio ed esponga l'esito al personale di assistenza.

Come funzionano idempotenza e riconciliazione?

Crei le fatture con un proprio riferimento d'ordine e renda la chiamata ripetibile in sicurezza: se la richiesta scade, cerchi la fattura per riferimento prima di crearne un'altra, oppure usi una chiave di idempotenza se il gateway la supporta. La stessa regola vale per i payout, dove una richiesta duplicata invia due volte denaro reale.

Per la riconciliazione conservi l'ID della fattura del gateway, l'hash della transazione, l'importo in valuta tradizionale, l'importo in crypto, il tasso e la commissione. I report di regolamento elencano i payout come lotti, perciò l'abbinamento procede da ordine a fattura a payout e non da ordine a riga bancaria.

Che cosa richiede un'API di payout con la Travel Rule?

Gli endpoint di payout inviano crypto dal saldo del gateway a un indirizzo, spesso in lotti per commissioni di affiliazione, venditori di marketplace o prelievi dei clienti. La maggior parte richiede whitelist degli indirizzi, approvazione a due fattori o una chiave API con permessi di payout separati.

Nell'UE il Regolamento (UE) 2023/1113 impone al gateway di trasmettere con ogni trasferimento le informazioni su ordinante e beneficiario e di verificare la titolarità dei wallet self-hosted oltre EUR 1.000. Si aspetti che le richieste di payout includano nome del beneficiario e tipo di indirizzo, e preveda trasferimenti che attendono questi dati.

Quali sono le opzioni white label per un gateway crypto?

Le piattaforme che rivendono pagamenti ai propri merchant spesso vogliono la pagina di pagamento con il proprio marchio. Esistono tre livelli e il prezzo cresce con il controllo. Plisio, ad esempio, indica lo 0,5 % per l'API e l'1,5 % per il white label, e NOWPayments vende un prodotto white label separato.

Il white label completo sposta responsabilità oltre che branding. Se registra merchant e detiene i loro saldi, potrebbe aver bisogno di una propria autorizzazione MiCA; il modello sub-merchant di un gateway autorizzato lascia tale obbligo al gateway.

Come collegare le API dei gateway crypto tramite OrsunPay

OrsunPay uniforma stati, webhook e rimborsi dei gateway crypto in un'unica API accanto ai Suoi provider di carte e bonifici, usando i Suoi account presso i gateway. Non custodisce crypto né esegue payout dal proprio saldo: instrada le richieste al gateway scelto e restituisce eventi firmati e deduplicati.

Come integrare l'API di un payment gateway crypto

1. Apra account sandbox Crei account sandbox e produzione presso il gateway, generi chiavi API separate per fatture e payout e imposti il secret IPN.
2. Mappi gli stati Traduca gli stati del gateway nei Suoi stati interni e decida quale rilascia la merce.
3. Crei fatture in modo idempotente Invii importo in valuta tradizionale, valuta, riferimento d'ordine e URL di callback; prima di ritentare una chiamata scaduta cerchi per riferimento.
4. Verifichi le notifiche Controlli la firma, recuperi di nuovo la fattura dall'API ed elabori l'evento una sola volta.
5. Gestisca i casi limite Implementi tolleranza, integrazione, rimborso e scadenza, e testi ogni caso nella sandbox.
6. Riconcili i regolamenti Conservi hash della transazione, tasso e commissione per ogni fattura e abbini ogni giorno i lotti di payout agli ordini.