Configurare Cybersource per l'App E-Commerce

Introduzione

Cybersource è un gateway di pagamento autorizzato per l'app E-Commerce di Docebo.

Questo articolo spiega come configurare un profilo account per la piattaforma in Cybersource e come impostare l'integrazione di Cybersource nella piattaforma.

Prerequisiti

L'integrazione con Cybersource è disponibile sulla piattaforma esclusivamente con il pacchetto e-commerce. Si prega di contattare il proprio referente Docebo per informazioni relative all'acquisizione del pacchetto.

Per eseguire le configurazioni illustrate in questo articolo, è necessario essere già in possesso di un account Cybersource:

• è possibile utilizzare un account di test, creato tramite il Cybersource developer center (si apre in una nuova scheda), per accedere al portale di test Cybersource e configurare l'integrazione in un ambiente sandbox.
• Successivamente, sarà necessario contattare Cybersource (si apre in una nuova scheda) per configurare il proprio account commerciante. Questo account verrà utilizzato per accedere al portale di produzione Cybersource, dove si procederà con la configurazione dell'integrazione “live” per l'accettazione di pagamenti reali.

Inoltre, qualora si desideri utilizzare la funzionalità di calcolo automatico delle tasse di Cybersource, sarà necessario contattare Cybersource per l'attivazione del calcolo delle imposte sul proprio account.

Requisiti e limitazioni

• Alcune valute supportate da Docebo potrebbero non essere accettate da Cybersource. Si raccomanda, pertanto, di verificare preventivamente che la valuta di interesse sia supportata da entrambi i sistemi prima di procedere. Consulta l'elenco completo delle valute supportate da Docebo. 

Attenzione: attualmente, in modalità sandbox, il gateway di pagamento Cybersource accetta esclusivamente dollari statunitensi. In modalità live, invece, sono accettate tutte le valute supportate.

• Nel caso di utilizzo dell'Extended Enterprise, è necessario configurare le impostazioni di Cybersource all'interno del dominio principale. Qualora alcuni domini richiedano una configurazione differente, è possibile applicare la configurazione localmente, nella scheda E-Commerce dell'app Extended Enterprise.
• Cybersource richiede il nome e il cognome dell'acquirente per completare la transazione. Tali informazioni vengono prelevate dal profilo utente sulla piattaforma e non vengono inserite durante la fase di trasmissione dei dati di fatturazione. Pertanto, affinché sia possibile utilizzare Cybersource, è indispensabile che i campi nome e cognome siano compilati nel profilo utente.  
• Quando si utilizza il calcolo automatico delle tasse di Cybersource, si precisa che il carrello della piattaforma visualizzerà il totale al netto delle tasse. Tuttavia, al momento del reindirizzamento su Cybersource per il completamento del pagamento, verranno mostrate anche le tasse aggiuntive e il nuovo totale aggiornato.

Configurazione di un profilo in Cybersource

Il presente capitolo illustra le configurazioni da effettuare lato Cybersource. È indispensabile completare tali impostazioni prima di procedere con la configurazione dell'integrazione Cybersource sulla piattaforma.

Creazione di un profilo Secure Acceptance

Il primo passaggio consiste nella creazione di un profilo Secure Acceptance per la piattaforma su Cybersource.

Nota: è necessario creare un profilo Secure Acceptance distinto per ciascun ambiente, sia live che sandbox.

• Il profilo sandbox, utilizzato per le attività di test, deve essere creato nel portale https://ebc2test.cybersource.com/ebc2 (si apre in una nuova scheda).
• Il profilo di produzione, destinato alle transazioni reali, deve essere creato nel portale https://businesscenter.cybersource.com/ebc2/ (globale) oppure https://businesscenter.in.cybersource.com/ebc2/ (India) (entrambi si aprono in una nuova scheda).

L’accesso al portale di test (sandbox) è consentito tramite un account di test Cybersource. Per il portale di produzione, è invece necessario disporre di un account merchant Cybersource. Per ulteriori dettagli, si rimanda ai Prerequisiti.

Per creare un profilo Secure Acceptance, accedere a Cybersource (sia al portale sandbox che a quello di produzione) e, nel menu laterale, selezionare Payment Configuration > Secure Acceptance Settings. Verrà visualizzata la pagina Secure Acceptance Settings che elenca tutti i profili esistenti.

Nota: per visualizzare o modificare le impostazioni di un profilo esistente, è possibile cliccare sul pulsante con i puntini di sospensione accanto al nome del profilo e selezionare l’azione desiderata.

Per creare un nuovo profilo, cliccare sul pulsante New profile e, nel pannello Create profile che si apre, inserire i dettagli richiesti per il profilo in fase di creazione:

• nella sezione Integration Methods selezionare Hosted Checkout.
• nella sezione Added value services, assicurarsi che le opzioni Payment tokenization e Decision manager siano disabilitate.

Al termine, cliccare su Submit.

Il nuovo profilo verrà creato e sarà automaticamente aperto nella relativa pagina delle impostazioni.

Generazione di una chiave di sicurezza per il profilo Secure Acceptance

È ora necessario generare una chiave di sicurezza per il profilo. Nella pagina delle impostazioni del profilo, selezionare la scheda Security e, nella sezione Active Keys, cliccare Create key. Nel pannello che si apre, specificare un nome per la chiave, quindi impostare Signature Version su 1 e Signature Method su HMAC_SHA256. Una volta completato, cliccare su Create e, nella finestra successiva, su Confirm.

Al termine della procedura, Cybersource mostrerà la Secret Key e la Access Key necessarie per la configurazione dell’integrazione tra Docebo e Cybersource. Le chiavi hanno una validità di due anni.

È possibile consultare nuovamente tali valori in qualsiasi momento cliccando su View key accanto al nome della chiave.

Suggerimento: sarà necessario inserire la Secret Key e l’Access Key, insieme al Cybersource Profile ID (visibile nella parte superiore della pagina del profilo), durante la configurazione di Cybersource sulla piattaforma.

Impostazioni di pagamento

Accedere ora alla scheda delle Impostazioni di pagamento. In questa sezione è necessario configurare i diversi tipi di carte accettate e, per ciascuna, specificare le valute supportate e il metodo di verifica della carta.

Risposte del cliente

Accedere alla scheda Customer Response, impostare sia l’opzione sia Custom Cancel Response Page come Hosted by You e configurarle come segue:

Transaction response page: [la tua URL completa della piattaforma]/ecommerce/v1/cybersource/validate
Custom cancel response page: [la tua URL completa della piattaforma]/ecommerce/v1/cybersource/decline

Dove [la tua URLstrong può essere:
- una URL docebosaas, ad esempio https://myplatform.docebosaas.com
- un dominio personalizzato o un dominio secondario, ad esempio https://learn.mycompany.net
- un client extended enterprise di tipo cartella, ad esempio https://myplatform.docebosaas.com/[folder_name]

Di seguito sono riportati alcuni esempi.

URL piattaforma Docebosaas

• Transaction Response Page = https://[platform_name].docebosaas.com/ecommerce/v1/cybersource/validate
• Custom Cancel Response Page = https://[platform_name].docebosaas.com/ecommerce/v1/cybersource/decline

Dominio personalizzato (o dominio secondario)

• Transaction Response Page =
• Custom Cancel Response Page = https://[custom_domain]/ecommerce/v1/cybersource/decline

Client extended enterprise di tipo cartella

• https://[platform_name].docebosaas.com/[folder_name]/ecommerce/v1/cybersource/validate
• Custom Cancel Response Page = https://[platform_name].docebosaas.com/[folder_name]/ecommerce/v1/cybersource/decline

Notifiche del commerciante

Per garantire l’affidabilità dell’integrazione, si raccomanda vivamente di configurare l’impostazione Merchant Notifications nella scheda Notifications.

Inserire il seguente URL nel campo Merchant notifications: https://[platform_name].docebosaas.com/ecommerce/v1/cybersource/notify

L’abilitazione di questa impostazione assicura che gli aggiornamenti sullo stato degli ordini e i risultati delle transazioni vengano trasmessi costantemente, contribuendo a prevenire che le transazioni rimangano nello stato Pending a causa di ritardi di rete, timeout o altre problematiche di comunicazione.

Configurazione di Cybersource per il calcolo automatico delle tasse

Completare i seguenti passaggi qualora si desideri utilizzare la funzionalità di calcolo automatico delle tasse al checkout.
→ Si ricorda che, per usufruire di tale funzionalità, è necessario richiedere a Cybersource l’abilitazione del calcolo delle tasse per il proprio account. Consultare i Prerequisiti.

Accedere alla scheda Payment form all’interno della sezione Purchase information:

• Selezionare la casella Display the total tax amount in each step of the checkout process.

Successivamente, per il calcolo automatico delle tasse, è necessario generare una chiave REST API. Si noti che questa operazione non viene eseguita dalla pagina del profilo Secure Acceptance, ma dalla pagina generale di gestione delle chiavi.

Importante: non è possibile utilizzare la stessa chiave REST API per gli ambienti sandbox e produzione.

• Dal menu laterale, selezionare Payment configuration > Key management e, nella pagina Key management, cliccare su Generate key.
• Nella pagina Create key che si apre, nella sezione Key types, selezionare REST - Shared secret.
• Scorrere quindi fino in fondo alla pagina e cliccare su Generate key.

Una volta generata la chiave, sarà possibile accedere alla Key e alla Shared secret. Tali valori dovranno essere inseriti nella piattaforma per le credenziali REST API durante la configurazione delle impostazioni delle tasse.

Suggerimento: si raccomanda di scaricare o copiare la Shared secret in modo sicuro immediatamente, poiché non sarà possibile recuperarla successivamente.

Nota: è possibile visualizzare le chiavi generate dalla pagina principale di Key management. Modificare i filtri su “Tutte le date” per visualizzare tutte le chiavi. Tuttavia, la Shared secret delle chiavi precedentemente generate non può essere recuperata e viene mostrata solo al momento della generazione.

Attivazione del profilo Secure Acceptance

Prima di poter utilizzare il profilo per transazioni di test o live, è necessario che abbia lo Status = Active. Tale stato è verificabile sia dall’elenco dei profili sia direttamente dalla pagina del profilo.

• Per attivare il profilo, cliccare sul pulsante Promote profile.

Configurazione di Cybersource sulla piattaforma

→ Prima di procedere con la configurazione di Cybersource sulla piattaforma, assicurarsi di aver completato i passaggi relativi alla configurazione di un profilo in Cybersource.

Per configurare l’integrazione Cybersource, accedere alla piattaforma come Superadmin. Successivamente, selezionare Menu amministrazione > Metodo di pagamento - Cybersource > Gestione. Verrà visualizzata la pagina di configurazione di Cybersource.

• Se Cybersource è già stato configurato, verrà visualizzata impostazioni esistenti: Dettagli account Cybersource, Impostazioni tasse, Modalità di deploy.
• In alternativa, cliccare su Configura Cybersource per avviare la configurazione.

Dettagli account Cybersource

All di Cybersource, nel pannello laterale che si apre, viene richiesto di inserire le credenziali del profilo Secure Acceptance (sandbox o produzione) precedentemente creato su Cybersource.

Tali valori possono essere copiati dalla pagina Secure Acceptance Setting del profilo:

• Il Profile ID è visibile nella parte superiore della pagina
• La Secret key e Access key sono disponibili e copiabili dalla scheda Security, utilizzando l’azione View key.

Una volta completato l’inserimento, cliccare su Conferma. Si verrà indirizzati alla pagina Cybersource settings. Si noti che, da questo momento, i dettagli dell’account inseriti saranno disponibili in sola lettura e le Secret key e Access key saranno oscurate per motivi di sicurezza.
→ Per modificare i dettagli dell’account sarà necessario reimpostare la configurazione Cybersource e ripetere la procedura da capo.

Suggerimento: si ricorda che, se le credenziali inserite appartengono a un profilo sandbox, è necessario selezionare la modalità di deploy Sandbox deployment mode. Se invece si utilizzano le credenziali di un profilo di produzione, selezionare la modalità di deploy Produzione.

Modalità di distribuzione

In questa sezione, è necessario specificare se si desidera operare nell’ambiente sandbox (test) o live.

La scelta effettuata deve essere coerente con i dettagli account Cybersource precedentemente inseriti.
- Se le credenziali sono relative a un profilo Secure Acceptance sandbox, selezionare Modalità sandbox di Cybersource.
- Se le credenziali sono relative a un profilo Secure Acceptance di produzione, selezionare Cybersource production mode.

Impostazioni fiscali

Se si desidera che Cybersource calcoli e applichi automaticamente le tasse durante il checkout, è necessario procedere come segue:

• verificare, nel profilo Secure Acceptance Cybersource (sandbox o produzione), di aver completato i passaggi relativi alla configurazione del calcolo delle tasse: occorre aver abilitato “Display total tax amount” nella scheda Payment form e aver creato una chiave REST API. Per ulteriori dettagli, si rimanda al capitolo: Impostazioni per il calcolo automatico delle tasse
• assicurarsi inoltre che Cybersource abbia abilitato il calcolo delle tasse per il proprio account (contattare Cybersource a tal fine).

Sulla piattaforma, selezionare la casella Abilita il calcolo automatico delle tasse e inserire il proprio numero di Partita IVA da commerciante.

Abilitando il calcolo automatico delle tasse, comparirà il campo REST API credentials nella sezione Deployment mode.

Procedere come segue:

• verificare innanzitutto di aver selezionato la modalità di distribuzione corretta (sandbox o produzione), in linea con il profilo Secure Acceptance utilizzato;
• cliccare quindi sul pulsante Configura l'API REST;
• nel pannello che si apre, inserire l’ID organizzativo utilizzato per accedere al portale Cybersource (attenzione, questo non coincide con il Profile ID);
• inserire quindi la Chiave API e la Shared secret della chiave REST API creata su Cybersource. Fare riferimento al capitolo Configurazione di Cybersource per il calcolo automatico delle tasse.

Al termine, cliccare su Conferma.

Reimpostare la configurazione Cybersource

Una volta che Cybersource è stato configurato sulla piattaforma, non è possibile modificare le credenziali del profilo Secure Acceptance. Pertanto, qualora sia necessario modificare uno di tali valori – ad esempio, per passare da un profilo sandbox a uno di produzione, operazione che richiede la modifica dei dettagli dell’account – sarà necessario reimpostare la configurazione Cybersource e ripetere la procedura dall’inizio.

Per procedere, in questa sezione cliccare sul pulsante Ripristina Cybersource. Nella finestra che si apre, selezionare la casella di conferma e cliccare nuovamente su Ripristina Cybersource.

Migliori pratiche

Nel carrello, qualora venga selezionato Cybersource come metodo di pagamento, le Informazioni di fatturazione devono essere compilate come segue:

• Se lo stato è Canada o Stati Uniti, il campo Stato/Provincia/Regione diventa obbligatorio e l’utente deve selezionare un’opzione dall’elenco a discesa.
• Stato/Provincia/Regione non è obbligatorio. Tuttavia, se l’utente decide di compilarlo, deve inserire un codice di due lettere.
• Il nome dell’utente che effettua il pagamento non deve contenere virgolette doppie (“ ”).