Integration Types
Altre funzionalità
Card Payments
Mobile Wallets
Alternative Payment Methods
Resources
Obbligatori:
Assicurarsi che il proprio profilo dell'esercente sia abilitato per il servizio Hosted Checkout. Se non abilitato, contattare il proprio provider di servizi. Per abilitare Hosted Checkout per il profilo dell'esercente, vedere il portale Merchant Manager e la Guida per l'utente di Merchant Manager.Facoltativo:
In caso di esito positivo del pagamento, è consigliabile scegliere il servizio di notifica per ricevere notifiche tramite email o Webhook. Optando per questo servizio, è possibile abilitare il gateway a inviare notifiche e-mail al pagante per proprio conto.Suggerimento:
Prima di iniziare con il processo di integrazione della funzionalità hosted checkout, è necessario consultare Procedure ottimali e suggerimenti.Seguire questi passaggi per richiedere un'interazione Hosted Checkout:
Initiate Checkout
. La richiesta deve includere dati relativi al pagamento e all'interazione, nonché istruzioni per il completamento. Di seguito è mostrato un frammento curl di esempio per l'operazione Initiate Checkout
.
curl https://eu-gateway.mastercard.com/api/nvp/version/72 \ -d "apiOperation=INITIATE_CHECKOUT" \ -d "apiPassword=$PWD" \ -d "apiUsername=merchant.<your_merchant_id>" \ -d "merchant=<your_merchant_id>" \ -d "interaction.operation=AUTHORIZE" \ -d "interaction.merchant.name=<your_merchant_name>" \ -d "order.id=<unique_order_id>" \ -d "order.amount=100.00" \ -d "order.currency=USD" \ -d "order.description=<description_of_order>"
Una risposta di esito positivo per questa operazione conterrà i parametri session.id
e successIndicator
. È possibile salvare il valore restituito nel parametro successIndicator
nel sistema del sito Web dell'esercente per verificare l'esito positivo o negativo del pagamento. Vedere Come ottenere il risultato del pagamento.
Checkout
nell'ambito globale.
<script src="https://eu-gateway.mastercard.com/static/checkout/checkout.min.js" data-error="errorCallback" data-cancel="cancelCallback"></script>
Riferimento checkout.js[JavaScript]
Checkout.configure()
, passando un oggetto JSON che include il session.id
restituito e altri parametri della richiesta.
Checkout.configure({ session: { id: '<your_initiate_checkout_ID>' }, interaction: { merchant: { name: 'Your merchant name', address: { line1: '200 Sample St', line2: '1234 Example Town' } } } });
Checkout.configure()
non sovrascriveranno mai i dati forniti nell'operazione Initiate Checkout
.Checkout.showEmbeddedPage('#embed-target')
Checkout.showPaymentPage()
<html> <head> <script src="https://eu-gateway.mastercard.com/static/checkout/checkout.min.js" data-error="errorCallback" data-cancel="cancelCallback"></script> <script type="text/javascript"> function errorCallback(error) { console.log(JSON.stringify(error)); } function cancelCallback() { console.log('Payment cancelled'); } Checkout.configure({ session: { id: '<your_initiate_checkout_session_ID>' } }); </script> </head> <body> ... <div id="embed-target"> </div> <input type="button" value="Pay with Embedded Page" onclick="Checkout.showEmbeddedPage('#embed-target');" /> <input type="button" value="Pay with Payment Page" onclick="Checkout.showPaymentPage();" /> ... </body> </html>
Checkout.configure()
come:quantity : 300
quantity : function() { return 100 + 200 }
. Le funzioni vengono eseguite quando il processo di pagamento viene attivato.
<html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/css/bootstrap.min.css" integrity="sha384-JcKb8q3iqJ61gNV9KGb8thSsNjpSL0n8PARn9HuZOnIxN0hoP+VmmDGMN5t9UJ0Z" crossorigin="anonymous"> <title>Hello, world!</title> </head> <body> <h1>Hello, world!</h1> <button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal"> Launch demo modal </button> <div class="modal fade" id="exampleModal" tabindex="-1" role="dialog" aria-labelledby="exampleModalLabel" aria-hidden="true"> <div class="modal-dialog" role="document"> <div class="modal-content"> <div class="modal-header"> <h5 class="modal-title" id="exampleModalLabel">Modal title</h5> <button type="button" class="close" data-dismiss="modal" aria-label="Close"> <span aria-hidden="true">×</span> </button> </div> <div class="modal-body" id="hco-embedded"> </div> <div class="modal-footer"> <button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button> <button type="button" class="btn btn-primary">Save changes</button> </div> </div> </div> </div> <script src="https://code.jquery.com/jquery-3.6.0.slim.min.js" integrity="sha256-u7e5khyithlIdTpu22PHhENmPcRdFiHRjhAuHcs05RI=" crossorigin="anonymous"></script> <script src="https://cdn.jsdelivr.net/npm/bootstrap@4.5.2/dist/js/bootstrap.min.js" crossorigin="anonymous"></script> <script src="https://eu-gateway.mastercard.com/static/checkout/checkout.min.js" ></script> <script> // Configure Checkout first Checkout.configure({ session: { id: "SESSION123123123" } }) // after the modal is shown, then call Checkout.showEmbeddedPage('#hco-embedded') $('#exampleModal').on('shown.bs.modal', function (e) { Checkout.showEmbeddedPage('#hco-embedded') }); </script> </body> </html>
I callback vengono forniti per gestire eventi che possono verificarsi durante l'interazione di pagamento.
L'uso dei callback è facoltativo, ma è necessario definire quelli necessari nel corpo dello stesso tag <script>
che fa riferimento a checkout.js.
Tutti i callback definiti devono includere un'implementazione. Verranno richiamati al momento dell'attivazione dell'evento rilevante.
<script src="https://eu-gateway.mastercard.com/static/checkout/checkout.min.js" data-cancel="cancelCallback" data-beforeRedirect="Checkout.saveFormFields" data-afterRedirect="Checkout.restoreFormFields"> </script> <script> function cancelCallback() { confirm('Are you sure you want to cancel?'); // code to manage payer interaction } // or if you want to provide a URL: // cancelCallback = "someURL" </script>
Esistono due tipi di metodi di callback:
I callback di base vengono forniti per gestire gli eventi seguenti:
cancel
: quando il pagante annulla l'interazione di pagamento.
error
: quando viene rilevato un errore. complete
: quando il pagante completa l'interazione di pagamento. timeout
: quando il pagamento non viene completato entro il periodo di tempo disponibile per il pagante. Possono essere funzioni o URL. Se si fornisce un URL anziché una funzione in un callback, il pagante verrà reindirizzato a questo URL quando l'evento viene attivato.
Poiché Hosted Checkout supporta interazioni di pagamento che richiedono che il pagante venga reindirizzato ad altri siti Web per procedere con il pagamento (ad es. PayPal), sono fornite funzioni di callback per gestire gli eventi che si verificano prima del reindirizzamento e dopo il ritorno a Hosted Checkout per finalizzare l'elaborazione della transazione.
beforeRedirect
: prima che l'interfaccia di pagamento venga visualizzata al pagante. Restituisce i dati necessari per ripristinare lo stato della pagina da utilizzare con afterRedirect
.afterRedirect
: quando il pagante ritorna dopo aver completato l'interazione di pagamento. Utilizza i dati salvati da beforeRedirect
per restituire lo stato dell'interfaccia di pagamento salvata.L'oggetto Checkout
fornisce anche due funzioni per consentire l'implementazione dei callback beforeRedirect
e afterRedirect
:
saveFormFields
: salva tutti i campi modulo correnti da utilizzare con restoreFormFields
. Utilizzare questa funzione nella propria implementazione beforeRedirect
o implementare beforeRedirect
come Checkout.saveFormFields
. restoreFormFields
: ripristina i campi modulo salvati da saveFormFields
. Utilizzare questa funzione nella propria implementazione afterRedirect
o implementare afterRedirect
come Checkout.restoreFormFields
. Riferimento checkout.js[JavaScript]
Al termine dell'interazione di pagamento, è possibile reindirizzare il pagante al sito Web dell'esercente e presentare la pagina della ricevuta al pagante: è possibile aggiornare il sistema del sito Web con i dettagli del pagamento.
Per reindirizzare il pagante al sito Web dell'esercente, è necessario:
interaction.returnUrl
nell'operazione Initiate Checkout
, OPPUREcomplete
nella richiesta di Hosted Checkout. Questo vale sia per i callback di base che per quelli di reindirizzamento. Vedere Callback.Il gateway invia il risultato del pagamento in un parametro resultIndicator
, che:
interaction.returnUrl
) utilizzato per reindirizzare il pagante al sito Web dell'esercente, OPPUREcomplete
oppure aggiunto all'URL fornito nel callback complete
.È possibile verificare se il pagamento ha avuto esito positivo confrontando i parametri resultIndicator
al parametro successIndicator
restituito nella risposta Initiate Checkout
. Una corrispondenza indica che il pagamento è riuscito.
resultIndicator
non deve essere mai utilizzato come numero di ricevuta.Se il pagamento è riuscito, presentare una ricevuta di pagamento al pagante nel sito Web dell'esercente e aggiornare il sistema del sito Web con i dettagli del pagamento. Per recuperare queste informazioni utilizzare l'operazione Retrieve Order
.
I dettagli del pagamento vengono registrati nella pagina Dettagli ordine e transazione di Merchant Administration. È possibile cercare il pagamento, nonché eseguire le operazioni successive.
Iscrivendosi a Reporting, è possibile scaricare i dati di pagamento del servizio Hosted Checkout in un report formattato dal Mastercard Gateway.
Iscrivendosi alle notifiche via email in Merchant Administration, si riceverà una notifica via email per ogni pagamento riuscito.
Hosted Checkout consente di controllare la visualizzazione delle informazioni relative alla propria azienda e all'interazione con il pagante mediante l'operazione Initiate Checkout
o il metodo Checkout.configure()
. Tenere presente che i dati forniti nella richiesta Initiate Checkout
avranno sempre la precedenza sui dati forniti nel metodo Checkout.configure()
. Per una maggiore sicurezza, si consiglia di fornire i dati in una sessione utilizzando l'operazione Initiate Checkout
.
URL | https://eu-gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/session |
Metodo HTTP | POST |
{ "apiOperation": "INITIATE_CHECKOUT", "interaction": { "operation": "AUTHORIZE" }, "order" : { "amount" : "122.0", "currency" : "USD", "description": "Ordered goods", "id": "232E32323ddd" } }
Checkout.configure({ session: { id: '<your_initiate_checkout_ID>' }, billing : { address: { street : '123 Customer Street', city : 'Metropolis', postcodeZip : '99999', stateProvince: 'NY', country : 'USA' } }, interaction: { merchant : { name : 'Your merchant name', address: { line1: '200 Sample St', line2: '1234 Example Town' }, email : 'order@yourMerchantEmailAddress.com', phone : '+1 123 456 789 012', logo : 'https://imageURL' }, locale : 'en_US', style: { theme: 'default' }, displayControl: { billingAddress : 'OPTIONAL', customerEmail : 'OPTIONAL', shipping : 'HIDE' } } });
interaction.merchant
verranno visualizzati nella pagina della ricevuta solo per l'integrazione della pagina di pagamento ospitato, non per la pagina incorporata. È possibile personalizzare l'esperienza di pagamento con le seguenti opzioni:
Include il logo nonché i dettagli del contatto.
Per ulteriori informazioni, vedere:
Dopo aver raccolto gli indirizzi di fatturazione ed email dal pagante, è possibile visualizzarli e controllarne la funzione di modifica impostando i campi interaction.displayControl.billingAddress
e interaction.displayControl.customerEmail
su uno dei seguenti valori:
HIDE
: se non si desidera che Hosted Checkout visualizzi i campi.MANDATORY
: se si desidera che Hosted Checkout visualizzi i campi e renda i dati obbligatori per il pagante. OPTIONAL
: se si desidera che Hosted Checkout visualizzi i campi ma consenta al pagante di scegliere di non immettervi i dati.READ_ONLY
: se si desidera che Hosted Checkout visualizzi i campi ma non consenta al pagante di modificarli.Dopo aver raccolto i dettagli di fatturazione dal pagante, è possibile controllarne la visualizzazione impostando il campo interaction.displayControl.shipping
su uno dei seguenti valori:
HIDE
: Se non si desidera che Hosted Checkout visualizzi i campi.READ_ONLY
: Se si desidera che Hosted Checkout visualizzi i campi ma non consenta al pagante di modificarli.Per impostazione predefinita, la lingua visualizzata con Hosted Checkout è determinata dal browser del pagante. È tuttavia possibile ignorare questo comportamento specificando un identificativo di lingua o il tag della lingua IETF nel campo locale
, ad es. en_US
, es
, fr_CA
. Se la lingua specificata non è supportata da Mastercard Gateway, Hosted Checkout viene visualizzato nella lingua con la corrispondenza migliore.
Per impostazione predefinita, il tema impostato come tema predefinito dal proprio provider di servizi di pagamento controlla l'aspetto del servizio Hosted Checkout. Se il provider di servizi di pagamento supporta più temi, è possibile scegliere di ignorare il tema predefinito specificando il campo interaction.style.theme
nella richiesta.
Il tema attualmente disponibile è default
.
È consigliabile includere order.id
nella richiesta per poter identificare facilmente un pagamento avviato da Hosted Checkout. È possibile utilizzare un identificativo generato dal carrello della spesa oppure specificare il proprio identificativo assicurandosi che sia univoco.
Quando un pagante sceglie di pagare utilizzando la sua carta, può inserire i dettagli della carta di credito o di debito durante l'interazione di checkout. Tuttavia, se almeno uno degli acquirer supporta le carte combinate, ovvero le carte che possono essere utilizzate come carte di debito o di credito, al pagante verrà richiesto di effettuare una selezione della modalità di pagamento nella pagina di pagamento —Carta di debito o carta di credito— per specificare la modalità in cui la carta deve operare per il pagamento.
Per utilizzare l'autenticazione 3-D Secure con la propria integrazione di hosted checkout contattare il proprio provider di servizi di pagamento per abilitare i privilegi necessari per il proprio account esercente.
Per testare il funzionamento dell'integrazione con l'autenticazione 3-D Secure, è possibile utilizzare il proprio profilo esercente di prova nell'ambiente di produzione.
Utilizzare le seguenti carte di prova per testare l'integrazione
Tipo di carta | Esito dell'autenticazione | Carta di prova |
---|---|---|
Mastercard | 3DS2 - Verifica | 5123450000000008 |
Mastercard | 3DS1 - Non registrato per 3DS2 con conseguente fallback a 3DS1 | 5506900140100305 |
Visa | 3DS2 - Verifica | 4440000009900010 |
Visa | 3DS1 - Non registrato per 3DS2 con conseguente fallback a 3DS1 | 4508750015741019 |
Per ulteriori informazioni sull'autenticazione, vedere Domande frequenti sull'autenticazione.
EMV 3-D Secure (EMV 3DS) è uno standard di settore globale progettato per aiutare gli esercenti e gli issuer ad autenticare le transazioni con carta non presente. L'ultima generazione di standard di settore EMVCo, denominata EMV 3-D Secure o EMV 3-D Secure 2.0, è un protocollo più robusto e un'autenticazione più forte rispetto alla versione attuale (3-D Secure 1). L'abilitazione di EMV 3DS migliora l'esperienza di pagamento digitale per l'esercente riducendo frodi, falsi rifiuti e attriti inutili.
Hosted Checkout può essere configurato in modo da fornire un'esperienza utente conforme a WCAG 2.0 Livello AA. Fare riferimento a Linee guida per WCAG 2.0 e verificare che il proprio sito Web sia conforme a questo standard tecnico.
Aggiungere l'attributo lang all'elemento html.
<html lang="en"> <head></head> <body></body> </html>
Se nel proprio profilo dell'esercente sono configurati piani di pagamento, per impostazione predefinita tutti i piani di pagamento nella propria configurazione esercente verranno visualizzati al pagante durante Hosted Checkout. Tuttavia, i piani di pagamento disponibili per il pagante saranno determinati dal numero della carta immesso dal pagante e dalla valuta dell'ordine.
È possibile limitare i piani di pagamento disponibili nell'offerta specificando vincoli sui piani di pagamento per ogni singola transazione. Questa operazione è utile se si desidera essere certi che le opzioni di pagamento offerte al pagante siano conformi ai criteri predefiniti in modo da evitare l'elaborazione di un pagamento se il pagante manomette i dati del piano di pagamento. Per specificare i vincoli, è possibile utilizzare i campi seguenti nella richiesta:
constraints.paymentPlans.supported[n]
: i piani di pagamento offerti per questa transazione.constraints.paymentPlans.numberOfPayments
: Il numero di rate consentite per il piano di pagamento.constraints.paymentPlan.numberOfDeferrals
: il numero di mesi di pagamento differito consentiti per il piano di pagamento.Per impostazione predefinita, i termini di pagamento per un piano di pagamento, se disponibili, vengono visualizzati in Hosted Checkout. È possibile nasconderli impostando interaction.displayControl.paymentTerms=HIDE
in Checkout.configure()
.
Per i pagamenti con carte prepagate e Automated Clearing House, Hosted Checkout supporta solo la verifica dei dettagli di pagamento.
A questo scopo è necessario impostare interaction.operation=VERIFY
nella richiesta Initiate Checkout.
Hosted Checkout utilizza i metodi di verifica supportati dall'acquirer configurato e i dati forniti nella richiesta.
È possibile verificare se l'operazione di verifica ha avuto esito positivo confrontando i parametri resultIndicator
e successIndicator
.
Se l'interazione non è riuscita, Hosted Checkout visualizza un messaggio per comunicare l'esito negativo della verifica e chiedere al pagante di riprovare l'operazione.
È possibile utilizzare Hosted Checkout con qualsiasi origine di transazione configurata nel profilo dell'esercente (Internet, call center, ordine telefonico e così via).
A questo scopo è necessario fornire transaction.source
nella richiesta Initiate Checkout.
Se un Hosted Checkout viene richiesto con un transaction.source
diverso da INTERNET
, le opzioni di pagamento che richiedono la presenza del pagante non saranno supportate.
Se non si specifica transaction.source
nella richiesta:
INTERNET
se questa origine è supportata nel collegamento all'acquirer dell'esercente.È possibile controllare se è necessario che i paganti forniscano il codice di sicurezza della carta per elaborare il pagamento impostando interaction.displayControl.cardSecurityCode
nella richiesta Initiate Checkout Session su uno dei valori seguenti:
OPTIONAL
: se si desidera che visualizzi il campo di immissione del codice di sicurezza della carta in Hosted Checkout, ma l'immissione di questo campo non è obbligatoria.MANDATORY
(valore predefinito): se si desidera che Hosted Checkout visualizzi il campo di immissione del codice di sicurezza della carta e lo renda obbligatorio.Se è stato configurato il servizio di autenticazione 3-D Secure o un servizio di gestione del rischio, è possibile scegliere di evitare l'esecuzione di questa funzionalità se lo si desidera.
interaction.action.3DSecure=BYPASS
nella richiesta Initiate Checkout. Il campo interaction.action.3DSecure
nella richiesta CREATE_CHECKOUT_SESSION
può assumere valori:
risk.bypassMerchantRiskRules=ALL
nella richiesta Initiate Checkout. Prima di effettuare il go live, è necessario eseguire il test dell'integrazione per garantirne il corretto funzionamento.
Hosted Checkout può restituire diversi errori di integrazione. Vedere Test dell'integrazione.
Viene visualizzata una pagina di errore quando si prova a inviare una richiesta di Hosted Checkout non corretta. Alcune delle cause più frequenti degli errori sono riportate di seguito:
Se si fa doppio clic sul pulsante "Paga", la transazione non verrà ripetuta con la propria banca o con quella del pagante.
Sì, Edge 18 è supportato.
Il modello di Hosted Checkout è sicuro in quanto richiede l'autenticazione al gateway e i dettagli di pagamento raccolti nella pagina di pagamento vengono inviati direttamente dal browser del pagante al gateway.
Non ci sono restrizioni sulla dimensione del file o sulla larghezza del logo. Per quanto riguarda l'altezza, la raccomandazione minima è di 144 px.
Sì, è possibile ospitare l'immagine del logo con qualsiasi provider, ma è obbligatorio che l'URL sia sicuro (HTTPS). Se il provider ospitato non supporta un URL sicuro, fare riferimento al seguente elenco di provider che offrono un hosting HTTPS gratuito: https://www.google.com.au/search?q=secure+image+hosting+providers
Questa casella di controllo è visibile solo se sono stati specificati tutti i campi obbligatori nell'indirizzo di spedizione. È necessario verificare che il pagante abbia compilato questi campi oppure specificare quelli mancanti, ad esempio shipping.country
se i beni non vengono spediti all'estero.
Se si desidera offrire ai clienti un'esperienza fluida con i dispositivi mobili ed ottimizzare la propria esperienza di Hosted Checkout con i dispositivi mobili, la procedura ottimale consiste nell'aggiungere un meta tag "viewport" alla pagina del proprio sito. Ad esempio:
<meta name="viewport" content="width=device-width, initial-scale=1">
Si tenga presente che è importante scegliere i valori corretti di viewport per le proprie pagine e testare il sito con queste modifiche.