Vai al contenuto

Come utilizzare l'ambiente Sandbox di 4Geeks Payments per i test

🤖 Spiega con l'intelligenza artificiale

L’implementazione della logica di pagamento direttamente in un ambiente live comporta rischi significativi, come addebiti accidentali su carte di credito reali e report finanziari confusi. La Sandbox di 4Geeks Payments fornisce una replica sicura e isolata del tuo ambiente di produzione. Consente agli sviluppatori e ai responsabili finanziari di simulare transazioni, testare le integrazioni API e convalidare flussi di lavoro di fatturazione complessi utilizzando 4Geeks Payments senza spostare denaro reale.

Questa articolo ti guida attraverso l’accesso alla sandbox, l’ottenimento delle credenziali di test e l’esecuzione di transazioni simulate per garantire che il tuo sistema sia pronto per il lancio.

Prerequisiti

Prima di iniziare i test, assicurati di avere quanto segue:

  • Accesso alla 4Geeks Console: Devi disporre di un account attivo con accesso alla 4Geeks Console.
  • Autorizzazioni: Hai bisogno di autorizzazioni di livello “Developer” o “Admin” per visualizzare le chiavi API e attivare/disattivare le modalità ambiente.
  • Integrazione dei pagamenti: Idealmente, dovresti avere una comprensione di base di come la tua applicazione si connette a 4Geeks Payments o essere pronto a testare le transazioni manuali tramite la dashboard.

Istruzioni passo-passo

Segui questi passaggi per configurare e utilizzare l’ambiente sandbox in modo efficace.

Passaggio 1: Passa alla modalità Test

La piattaforma 4Geeks separa i dati “Live” dai dati “Test” per prevenire incidenti.

  1. Accedi alla 4Geeks Console.
  2. Vai al modulo Payments nella barra laterale sinistra.
  3. Individua l’Interruttore ambiente nella barra di navigazione in alto (di solito visualizza “Live”).
  4. Clicca sull’interruttore per spostarlo su “Test” o “Sandbox”.
  5. Il banner della dashboard dovrebbe cambiare colore (in genere in arancione o blu) per indicare che ora stai lavorando con dati fittizi.

Passaggio 2: Ottieni credenziali API di test

Le tue chiavi API live non funzioneranno nella sandbox. Devi generare credenziali specifiche per i test.

  1. Mentre sei in Test Mode, vai a Settings > API & Webhooks.
  2. Individua le sezioni Public Key e Secret Key.
  3. Clicca su Reveal Keys per visualizzare le tue credenziali di test. Queste chiavi di solito iniziano con un prefisso come pk_test_ o sk_test_.
  4. Copia queste chiavi e aggiorna il tuo ambiente di sviluppo locale o la configurazione del server di staging.

Nota: Non utilizzare mai le tue chiavi Live (pk_live_...) nel tuo codice di test, in quanto ciò comporterà un’autenticazione fallita o transazioni reali indesiderate.

Passaggio 3: Simula una transazione

Puoi verificare la tua integrazione elaborando un pagamento utilizzando numeri di carta di test.

  1. Avvia un flusso di pagamento tramite la tua applicazione (ad es. una pagina di checkout o un link di pagamento fattura).
  2. Quando ti vengono richiesti i dettagli del pagamento, utilizza uno dei Numeri di carta di test 4Geeks. (Vedi la documentazione di 4Geeks Payments per un elenco completo).
    • Visa (Riuscito): 4242 4242 4242 4242
    • Mastercard (Rifiutato): 5100 0000 0000 0051
    • Data di scadenza: Qualsiasi data futura.
    • CVC: Qualsiasi 3 cifre (ad es. 123).
  3. Completa il processo di checkout.

Passaggio 4: Verifica i risultati

  1. Torna alla 4Geeks Console (assicurati di essere ancora in Test Mode).
  2. Clicca sulla scheda Transactions.
  3. Dovresti vedere elencato il tuo pagamento simulato più recente.
  4. Clicca sull’ID transazione per visualizzare i dettagli, incluso lo stato (Riuscito/Fallito), i log di risposta API grezzi e i metadati associati.

Casi d’uso comuni

Scenario 1: Test del dunning automatico per gli abbonamenti

Se utilizzi 4Geeks Payments per gestire la fatturazione ricorrente, puoi simulare un pagamento fallito per testare la tua logica di dunning (nuovo tentativo).

  • Azione: Crea un abbonamento nella sandbox utilizzando uno specifico numero di carta di test “Rifiuto”.
  • Convalida: Verifica che il sistema tenti di ritentare il pagamento secondo il tuo programma e che venga attivata la corretta notifica email “Pagamento fallito” all’email del cliente fittizio.

Scenario 2: Convalida delle erogazioni buste paga

Per le aziende che utilizzano 4Geeks Payroll, la sandbox è essenziale per testare i pagamenti ai collaboratori.

  • Azione: Imposta un profilo collaboratore di test e avvia un pagamento in blocco utilizzando fondi di test nel tuo portafoglio virtuale.
  • Convalida: Controlla che lo stato della transazione si aggiorni a “Pagato” nella console e che il webhook corrispondente venga attivato sul tuo sistema backend, confermando che l’integrazione gestisce correttamente i pagamenti.

Risoluzione dei problemi

Problema 1: Errore “Chiave API non valida”

  • Causa: Probabilmente stai utilizzando le tue chiavi API Live mentre la tua applicazione punta all’endpoint Sandbox, o viceversa.
  • Soluzione: Controlla il tuo file .env o le impostazioni di configurazione. Assicurati che le tue chiavi corrispondano all’ambiente (chiavi Test per Sandbox, chiavi Live per Produzione).

Problema 2: Le transazioni non appaiono nella Dashboard

  • Causa: La visualizzazione della console potrebbe essere impostata sulla modalità sbagliata.
  • Soluzione: Guarda l’interruttore nell’intestazione della 4Geeks Console. Se hai elaborato una transazione di test, assicurati che l’interruttore sia impostato su Test. Le transazioni Live non appariranno mai nella vista Test.

Problema 3: I webhook non si attivano

  • Causa: Gli endpoint webhook devono essere configurati separatamente per gli ambienti Live e Test.
  • Soluzione: Vai a Settings > API & Webhooks mentre sei in Test Mode. Assicurati che l’URL del tuo server di staging sia aggiunto come endpoint webhook e che gli eventi “subscription_created” o “payment_succeeded” siano abilitati.

Conclusione

L’utilizzo della Sandbox di 4Geeks Payments è un passaggio fondamentale nel ciclo di vita dello sviluppo. Garantisce che la tua logica di fatturazione, dalla fatturazione dei pazienti in 4Geeks Health alla gestione degli abbonamenti in 4Geeks Assets, funzioni perfettamente prima di interagire con clienti reali. Isolando i test in questo ambiente, proteggi i tuoi flussi di entrate e mantieni dati puliti per report accurati.

Per scenari di test più avanzati, come la simulazione 3D Secure o la gestione delle controversie, fai riferimento alle Risorse aggiuntive di seguito.

Risorse aggiuntive