Torna alle guide INTEGRATIONS

Integrazione Gateway di Pagamento: Guida Completa per Sviluppatori e Aziende

Integrare un gateway di pagamento è una delle decisioni tecniche più importanti che un'azienda e-commerce o un team di sviluppo possa prendere. Il metodo scelto determina il perimetro PCI DSS, il tasso di conversione al checkout, la capacità di gestire l'autenticazione 3D Secure e la velocità con cui si possono supportare nuovi metodi di pagamento. Questa guida copre ogni percorso di integrazione disponibile, dalla hosted page senza codice fino all'API REST server-to-server, e illustra i passi esatti per andare live con RoxPay. Che tu sia uno sviluppatore che costruisce un nuovo checkout o un imprenditore che valuta le opzioni, questa guida ti fornisce il quadro completo.

Integrazione Gateway di Pagamento | RoxPay

Cosa Significa l'Integrazione del Gateway per il Tuo Business

L'integrazione del gateway di pagamento è la connessione tecnica tra il tuo sito web o applicazione e la rete di elaborazione dei pagamenti che autorizza, cattura e regola le transazioni con carta. Senza di essa, i tuoi clienti non possono pagare. Con un'integrazione scadente, perdi fatturato attraverso transazioni fallite, flussi di checkout farraginosi e una scarsa esperienza mobile.

L'integrazione riguarda più degli sviluppatori. I titolari di business devono comprendere che il metodo scelto determina la loro responsabilità ai sensi del PCI DSS, la capacità di supportare metodi di pagamento locali e la velocità con cui possono essere abilitati nuovi servizi come Apple Pay o i bonifici open banking. Un'integrazione con hosted page sposta tutta la gestione dei dati della carta fuori dai tuoi server e riduce al minimo gli oneri di conformità. Un'integrazione diretta via API offre il massimo controllo, ma richiede una certificazione PCI più elevata.

Perché la qualità dell'integrazione conta per la conversione: La frizione al checkout è una delle principali cause di abbandono del carrello. Un gateway che richiede più redirect e una visita a un portale bancario separato convertirà peggio rispetto a un'esperienza di checkout nativa e incorporata. Le moderne integrazioni REST API consentono di mostrare i campi di input della carta direttamente nella pagina di checkout senza che il cliente lasci mai il tuo sito, migliorando in modo misurabile i tassi di completamento.

Per i merchant nei settori ad alto rischio che necessitano anche di un gateway di pagamento high risk, il livello di integrazione è ancora più importante perché i controlli aggiuntivi, l'applicazione del 3D Secure e i filtri antifrode interagiscono tutti con il modo in cui il modulo di pagamento è costruito e con la gestione degli eventi downstream. Scegliere un gateway che gestisce sia l'elaborazione standard che quella high risk in un'unica integrazione evita la complessità di gestire due sistemi separati.

Metodi di Integrazione: Hosted Page, API e SDK

Esistono tre modi principali per integrare un gateway di pagamento, ciascuno con diversi compromessi tra velocità di implementazione, perimetro PCI DSS e flessibilità di personalizzazione.

Hosted Payment Page: L'opzione più semplice. Reindirizza il cliente dal tuo checkout a una pagina ospitata e gestita dal gateway. Il cliente inserisce i dati della carta sul dominio del gateway, non sul tuo. Questo elimina quasi tutti i requisiti PCI DSS sul tuo lato, poiché non gestisci mai i dati della carta. Il lato negativo è la personalizzazione limitata e l'esperienza di lasciare il tuo sito durante il checkout. Ideale per le aziende che vogliono iniziare ad accettare pagamenti rapidamente con il minimo sforzo di sviluppo.

Drop-in UI incorporata (iFrame o JS Elements): Una via di mezzo pratica. Il gateway fornisce uno snippet JavaScript che inietta campi di input sicuri per la carta direttamente nel tuo checkout. I campi vengono mostrati all'interno di iframe ospitati sul dominio del gateway, quindi i dati della carta non toccano mai il tuo server. Dal punto di vista del cliente, il checkout sembra nativo del tuo sito. Il perimetro PCI è minimo (SAQ A). Questo è l'approccio consigliato per la maggior parte degli e-commerce. RoxPay supporta questa modalità tramite la sua REST API e l'SDK frontend.

API Server-to-Server: Massimo controllo. Il tuo frontend raccoglie i dati della carta, il tuo server li invia direttamente all'API del gateway. Questo richiede la conformità PCI DSS SAQ D, con audit di sicurezza rigorosi e controlli continui. È appropriato per le piattaforme che costruiscono prodotti di infrastruttura di pagamento, non per la maggior parte dei merchant che elaborano le proprie transazioni.

Plugin e moduli per piattaforme: Per i merchant che usano piattaforme e-commerce come Magento, PrestaShop o WooCommerce, i moduli pre-costruiti gestiscono i dettagli dell'integrazione all'interno dell'architettura della piattaforma. Il metodo sottostante è in genere una hosted page o una drop-in UI, quindi il perimetro PCI rimane minimo e il tempo di implementazione si misura in ore anziché in giorni.

Passo dopo Passo: Come Integrare RoxPay via REST API

RoxPay offre una REST API con corpi di richiesta e risposta in JSON. La documentazione completa è disponibile su app.roxpay.eu/api/v4/docs. L'integrazione segue un pattern di payment intent standard, familiare a qualsiasi sviluppatore che abbia lavorato con moderne API gateway.

Step 1: Crea il tuo account sandbox. Per avviare la tua domanda RoxPay, accedi alla pagina di onboarding. Le credenziali sandbox vengono rilasciate automaticamente alla registrazione, senza necessità di fornire dati di pagamento per iniziare i test.

Step 2: Autenticati. Tutte le chiamate API utilizzano la tua API key nell'intestazione Authorization. Le chiavi sono legate al tuo account merchant e possono essere ruotate dalla dashboard. Non esporre mai la tua API key nel codice JavaScript lato client né inserirla nel controllo versione.

Step 3: Crea un payment intent. Effettua una POST all'endpoint del payment intent con l'importo, la valuta, i metodi di pagamento accettati e un riferimento d'ordine univoco dal tuo sistema. L'API restituisce un ID del payment intent e un client secret da usare sul frontend.

Step 4: Monta la drop-in UI. Passa il client secret alla libreria RoxPay.js, che mostra i campi di input della carta sulla tua pagina. La libreria gestisce la formattazione del numero di carta, la validazione, i redirect 3D Secure e i pulsanti Apple Pay o Google Pay in base al supporto del browser.

Step 5: Gestisci il risultato. Al completamento del pagamento, la libreria attiva un callback di successo. Il tuo frontend notifica il tuo backend, che verifica in modo indipendente lo stato del pagamento via webhook prima di evadere l'ordine. Non fare mai affidamento esclusivamente sulla conferma del frontend per l'evasione degli ordini.

Step 6: Riconcilia tramite la dashboard. Tutte le transazioni sono visibili nella tua dashboard merchant con dettagli completi su importo, commissioni, tipo di carta e stato di settlement. Esporta in CSV o usa l'API per l'integrazione con il sistema contabile.

Webhook, Gestione degli Errori e Test in Sandbox

I webhook sono la base di un'integrazione di pagamento affidabile. Consentono a RoxPay di notificare il tuo server degli eventi di pagamento in modo asincrono, senza dipendere dal fatto che il browser del cliente rimanga aperto o che la connessione di rete rimanga stabile per tutta la transazione.

Configurazione dei webhook: Registra un endpoint HTTPS sul tuo server dalla dashboard. RoxPay invierà un payload JSON firmato a questo endpoint per ogni evento significativo: payment.completed, payment.failed, payment.refunded, chargeback.created e altri. Verifica la firma su ogni webhook in arrivo usando la chiave segreta mostrata nella tua dashboard. Rifiuta qualsiasi richiesta che non superi la validazione della firma per prevenire attacchi di replay.

Idempotenza: I webhook possono essere consegnati più di una volta a causa delle condizioni di rete. Il tuo endpoint deve elaborare ogni evento in modo idempotente, ovvero elaborare lo stesso evento due volte produce lo stesso risultato. Memorizza l'ID dell'evento e salta l'elaborazione se lo hai già gestito.

Gestione degli errori nell'API: RoxPay restituisce codici di stato HTTP standard. 200 per il successo, 400 per richieste non valide, 401 per errori di autenticazione, 422 per errori di elaborazione come il rifiuto della carta o fondi insufficienti. Ispeziona sempre il codice di errore nel corpo della risposta, non solo lo stato HTTP, per distinguere tra un errore tecnico e un rifiuto di logica di business.

Test in sandbox: L'ambiente sandbox rispecchia esattamente la produzione. Usa i numeri di carta di test forniti per simulare transazioni approvate, rifiuti, sfide 3DS, fondi insufficienti, carte scadute e risposte per carte rubate. Testa la gestione dei webhook attivando ogni tipo di evento in sandbox prima di toccare la produzione. Verifica che la tua interfaccia utente per gli errori funzioni correttamente per ogni scenario di rifiuto che i tuoi clienti potrebbero incontrare, non solo il percorso felice.

Logica di retry: Implementa il backoff esponenziale sul tuo consumer di webhook. RoxPay riprova i webhook non consegnati per un periodo definito. Il tuo endpoint deve essere idempotente prima di fare affidamento sul comportamento di retry.

Go-Live: Checklist Prima di Elaborare Transazioni Reali

Il passaggio dalla sandbox alla produzione richiede il completamento di una serie di passaggi tecnici, di sicurezza e commerciali. Saltarne uno crea rischi per la tua attività e per i tuoi clienti.

Checklist tecnica:
Sostituisci le API key sandbox con quelle di produzione e memorizzale in variabili d'ambiente, mai nel codice sorgente o nel controllo versione. Verifica che il tuo endpoint webhook sia live, accessibile via HTTPS con un certificato valido e che restituisca risposte 200 in modo costante. Testa la gestione dell'idempotenza con le credenziali di produzione prima di indirizzare il traffico dei clienti. Verifica che il 3D Secure sia configurato in base ai requisiti del tuo acquirente per la tua categoria merceologica. Controlla che la tua UI di checkout venga visualizzata correttamente sui dispositivi mobili, in particolare per i pulsanti Apple Pay e Google Pay.

Checklist PCI DSS:
Se utilizzi la drop-in UI, completa e archivia un questionario di auto-valutazione SAQ A. Verifica di non registrare né memorizzare dati della carta grezzi in nessun punto del tuo sistema, inclusi log delle richieste, log degli errori o pipeline di analytics. Assicurati che la tua configurazione TLS soddisfi gli standard attuali (TLS 1.2 minimo, TLS 1.3 preferito). Rimuovi eventuali integrazioni di pagamento obsolete che potrebbero essere ancora attive nel tuo codebase.

Checklist commerciale:
Imposta il tuo billing descriptor nella dashboard. Questo è il testo che appare sull'estratto conto del titolare della carta. Un descriptor chiaro e riconoscibile riduce significativamente i chargeback per frode amichevole perché i clienti possono identificare l'addebito. Configura il tuo IBAN di settlement. RoxPay salda su qualsiasi conto bancario SEPA in 24-48 ore. Abilita le notifiche email per le transazioni fallite e i chargeback in modo da poter rispondere entro le scadenze delle contestazioni. Verifica la tua politica di rimborso e cancellazione e assicurati che sia chiaramente visibile durante il checkout. Assicurati che il contatto del tuo servizio clienti sia facile da trovare, poiché i clienti che possono contattarti direttamente hanno molte meno probabilità di avviare una contestazione bancaria.

Domande Frequenti

Quanto tempo richiede l'integrazione di un gateway di pagamento?

Utilizzando l'approccio drop-in UI con la REST API di RoxPay, uno sviluppatore esperto può completare un'integrazione pronta per la produzione in uno o due giorni. Una hosted page redirect richiede meno di un giorno. L'integrazione API server-to-server completa con una UI di checkout personalizzata richiede in genere da una a due settimane, più il lavoro sulla conformità PCI DSS.

Ho bisogno della certificazione PCI DSS per integrare un gateway di pagamento?

Non certificato in senso formale, ma devi essere conforme. Se utilizzi una hosted page o una drop-in UI (basata su iFrame), il tuo onere di conformità è minimo e completi un semplice questionario di auto-valutazione (SAQ A). Se gestisci dati grezzi della carta sui tuoi server tramite un'API server-to-server, hai bisogno di SAQ D, che prevede un audit rigoroso. La maggior parte dei merchant sceglie la drop-in UI proprio per evitare questo requisito.

Cos'è un payment intent e perché viene utilizzato?

Un payment intent è un oggetto lato server che rappresenta l'intenzione di un cliente di pagare un importo specifico. Traccia lo stato del pagamento attraverso autorizzazione, sfida 3D Secure, cattura e settlement. Utilizzare un modello di payment intent previene i doppi addebiti, consente un tracciamento affidabile tramite webhook e permette al pagamento di sopravvivere agli aggiornamenti del browser o alle connessioni interrotte durante il checkout.

Posso testare l'integrazione senza un account merchant live?

Sì. RoxPay fornisce un ambiente sandbox gratuito accessibile immediatamente alla registrazione. Il sandbox rispecchia esattamente il comportamento della produzione e include carte di test per ogni scenario: approvazioni, rifiuti, sfide 3DS, carte scadute e fondi insufficienti. Non sono richiesti dati di pagamento né l'approvazione di un account live per iniziare i test.

Approfondimenti

Ottimizza i tuoi pagamenti oggi

RoxPay offre una REST API con accesso sandbox gratuito, documentazione completa e settlement in 24-48 ore su qualsiasi banca SEPA. Certificazione PCI DSS Level 1, prezzi IC++ da 0,45%.

Attiva gratuitamente → Parla con un esperto

✓ Nessun costo fisso mensile · ✓ Attivazione in 24 ore · ✓ Supporto tecnico dedicato