← Blog
10 min di lettura
|
Pubblicato
|
Aggiornato

API blockchain per i pagamenti e-commerce

Come un negozio online accetta e paga in crypto tramite un'API blockchain: un indirizzo per ordine, webhook, conferme, rimborsi e test su testnet.

Capitoli
C
Chaingateway Team
Esperti di blockchain

Verificato da Maurice Sobiera

Un’API blockchain per l’e-commerce è un’interfaccia REST che permette a un negozio online di creare indirizzi di pagamento, rilevare pagamenti crypto in entrata e inviare rimborsi o payout, senza gestire nodi blockchain propri. Il negozio comunica con l’API tramite HTTPS e riceve webhook quando arriva un pagamento. Le chiavi e le regole di conferma restano sotto il controllo del negozio.

Come accetta un negozio online pagamenti crypto tramite un’API?

Si assegna a ogni ordine un proprio indirizzo di deposito, lo si monitora con un webhook e si segna l’ordine come pagato quando l’importo confermato corrisponde. Il flusso prevede cinque passaggi:

  1. Creare un indirizzo per l’ordine con POST /api/v2/{blockchain}/addresses.
  2. Registrare un webhook per quell’indirizzo con POST /api/v2/{blockchain}/webhooks, inserendo l’ID dell’ordine nel campo reference.
  3. Mostrare al cliente l’indirizzo, l’importo e una scadenza.
  4. Quando arriva il webhook, verificare l’header X-Signature e controllare importo e token sulla chain.
  5. Rilasciare la merce dopo il numero di conferme stabilito.

Un indirizzo per ordine elimina le incertezze: ogni pagamento su quell’indirizzo appartiene a quell’ordine. La guida ai webhook per i pagamenti mostra il codice del ricevitore, e il tutorial Laravel mostra lo stesso flusso in un framework PHP.

Che cosa deve memorizzare il record dell’ordine?

Il record deve contenere dati sufficienti per stabilire da soli se un pagamento è completo. Il webhook segnala che è successo qualcosa. Il record dell’ordine indica che cosa sarebbe dovuto succedere.

CampoScopo
ID ordineInviato anche come reference del webhook, così l’evento si può associare
Rete e tokenLa chain e il contratto che il cliente deve usare
Indirizzo di depositoL’indirizzo creato per questo ordine
Importo attesoConvertito dal prezzo del negozio al momento dell’emissione della fattura
Scadenza della fatturaIl momento dopo il quale il prezzo non è più valido
Conferme richiesteLa regola scelta per questa rete e per la dimensione dell’ordine
StatoIn attesa, parzialmente pagato, pagato, scaduto o rimborsato

Con questi campi il gestore del webhook è un breve confronto. Si cerca l’ordine tramite reference, si verifica che rete e token corrispondano, si somma l’importo a quanto ricevuto finora e si aggiorna lo stato. Un pagamento con il token sbagliato verso l’indirizzo giusto è un caso normale che il gestore deve intercettare, perché un indirizzo può ricevere qualsiasi token della sua rete.

Quante conferme deve attendere un negozio?

Dipende dalla rete e dal valore dell’ordine. La documentazione per sviluppatori di Bitcoin sull’elaborazione dei pagamenti afferma che una transazione con zero conferme non va considerata affidabile senza un’analisi del rischio. Il software che gestisce transazioni di valore elevato dovrebbe attenderne almeno sei, il che richiede circa un’ora. Su TRON un blocco è solidificato quando almeno 19 dei 27 Super Representative vi hanno costruito sopra, e la documentazione sul consenso TRON lo colloca in circa un minuto in condizioni normali.

Si sceglie una regola per rete e per dimensione dell’ordine, la si scrive e la si applica nel codice. Un articolo digitale di basso valore può essere spedito dopo una conferma. Un articolo fisico di valore elevato deve attendere di più.

Che cosa fare con le variazioni di prezzo?

Si fissa il prezzo nella propria valuta, lo si converte al momento dell’emissione della fattura e si lascia scadere la fattura. La documentazione Bitcoin osserva che i tassi di cambio variano, che le fatture agganciate a una valuta fiat devono scadere, e che la maggior parte dei sistemi di pagamento le fa scadere dopo 10-20 minuti. Una finestra più breve riduce il rischio di cambio, ma aumenta la probabilità che il cliente paghi in ritardo.

Si decide in anticipo che cosa succede a un pagamento tardivo o parziale. La maggior parte dei negozi lo rimborsa, oppure chiede al cliente di pagare la differenza allo stesso indirizzo.

Come funzionano i rimborsi e i payout?

Si inviano come normali transazioni da un indirizzo sotto il proprio controllo. Per la moneta nativa si usa POST /api/v2/{blockchain}/transactions, mentre per i token si usano gli endpoint come transactions/erc20, transactions/bep20 o transactions/trc20. Un rimborso richiede l’indirizzo di restituzione del cliente, che va chiesto separatamente, perché il mittente di un pagamento non è sempre il wallet che dovrebbe ricevere il rimborso, per esempio quando il pagamento arriva da un exchange.

I fondi su un indirizzo d’ordine devono restare per poco tempo. I pagamenti in entrata vanno spostati su un wallet tenuto offline, e gli indirizzi d’ordine servono solo per incassare. I nostri consigli di sicurezza spiegano come conservare le chiavi.

Come si controllano le commissioni di rete?

Le commissioni vanno previste sul lato del mittente. Spostare token da un indirizzo d’ordine costa gas sulle reti EVM e Energy o Bandwidth su TRON, e l’indirizzo d’ordine deve avere abbastanza moneta nativa per coprirle. Su TRON, sponsorizzare o affittare energy abbassa il costo dei trasferimenti TRC-20. La nostra documentazione su TronFuel e il Paymaster deprecato descrive l’opzione attuale. TronFuel è un servizio separato con una propria documentazione.

Come si prova l’integrazione prima del lancio?

Si usano le testnet. Si aggiunge l’header X-Network: testnet a qualsiasi richiesta, e la stessa chiamata viene eseguita su una rete di test senza fondi reali. Si provano un ordine completo, un pagamento insufficiente, uno eccedente, un pagamento tardivo e un webhook che non raggiunge il vostro server. I webhook falliti non vengono ritentati automaticamente. Compaiono in GET /webhooks/notifications/failed e si possono inviare di nuovo, quindi il negozio deve controllare questo elenco.

Bisogna verificare i clienti?

Dipende dalla giurisdizione e dal modello di business, e l’API non lo decide al vostro posto. Chaingateway è non-custodial. Leggete il nostro articolo sul KYC per i pagamenti crypto prima di decidere quali controlli si applicano al vostro negozio.

Come scriviamo questi articoli

Pronto a costruirlo da solo? Ottieni la tua API key — prova di 7 giorni, senza carta — oppure consulta Blockchain API per il riferimento completo degli endpoint.

C
Chaingateway Team
Esperti di blockchain

Il team di Chaingateway si impegna a semplificare l'integrazione blockchain per sviluppatori di tutto il mondo.