Integration Types
Altre funzionalità
Card Payments
Mobile Wallets
Alternative Payment Methods
Resources
La libreria Javascript lato client di Hosted Session consente di raccogliere dettagli di pagamento riservati del pagante nei campi del modulo di pagamento, ospitati da Mastercard Gateway. Il gateway raccoglie i dettagli di pagamento riservati in una sessione di pagamento e li archivia temporaneamente per un uso successivo. È quindi possibile includere una sessione di pagamento al posto dei dettagli di pagamento nella richiesta di transazione per elaborare un pagamento. Per ulteriori informazioni, vedere sessione di pagamento.
Hosted Session è un metodo di integrazione conforme agli standard PCI v3 che favorisce la conformità SAQ-A, consentendo nel contempo il controllo del layout e dello stile della pagina di pagamento. In questo modello tutti i campi di pagamento sensibili sono incorporati in iFrame originati e controllati da Mastercard Gateway. I meccanismi standard di protezione della sicurezza del browser isolano i campi sensibili dall'utente, preservando l'integrità del canale di pagamento fornito dal gateway.
In questa sezione viene descritta un'integrazione semplice per Hosted Session per raccogliere dettagli della carta di credito del pagante.
<html> <head> <!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY --> <script src="https://eu-gateway.mastercard.com/form/version/72/merchant/<MERCHANTID>/session.js"></script> <!-- APPLY CLICK-JACKING STYLING AND HIDE CONTENTS OF THE PAGE --> <style id="antiClickjack">body{display:none !important;}</style> </head> <body> <!-- CREATE THE HTML FOR THE PAYMENT PAGE --> <div>Please enter your payment details:</div> <h3>Credit Card</h3> <div>Card Number: <input type="text" id="card-number" class="input-field" title="card number" aria-label="enter your card number" value="" tabindex="1" readonly></div> <div>Expiry Month:<input type="text" id="expiry-month" class="input-field" title="expiry month" aria-label="two digit expiry month" value="" tabindex="2" readonly></div> <div>Expiry Year:<input type="text" id="expiry-year" class="input-field" title="expiry year" aria-label="two digit expiry year" value="" tabindex="3" readonly></div> <div>Security Code:<input type="text" id="security-code" class="input-field" title="security code" aria-label="three digit CCV security code" value="" tabindex="4" readonly></div> <div>Cardholder Name:<input type="text" id="cardholder-name" class="input-field" title="cardholder name" aria-label="enter name on card" value="" tabindex="5" readonly></div> <div><button id="payButton" onclick="pay('card');">Pay Now</button></div> <!-- JAVASCRIPT FRAME-BREAKER CODE TO PROVIDE PROTECTION AGAINST IFRAME CLICK-JACKING --> <script type="text/javascript"> if (self === top) { var antiClickjack = document.getElementById("antiClickjack"); antiClickjack.parentNode.removeChild(antiClickjack); } else { top.location = self.location; } PaymentSession.configure({ session: "<your_session_ID>", fields: { // ATTACH HOSTED FIELDS TO YOUR PAYMENT PAGE FOR A CREDIT CARD card: { number: "#card-number", securityCode: "#security-code", expiryMonth: "#expiry-month", expiryYear: "#expiry-year", nameOnCard: "#cardholder-name" } }, //SPECIFY YOUR MITIGATION OPTION HERE frameEmbeddingMitigation: ["javascript"], callbacks: { initialized: function(response) { // HANDLE INITIALIZATION RESPONSE }, formSessionUpdate: function(response) { // HANDLE RESPONSE FOR UPDATE SESSION if (response.status) { if ("ok" == response.status) { console.log("Session updated with data: " + response.session.id); //check if the security code was provided by the user if (response.sourceOfFunds.provided.card.securityCode) { console.log("Security code was provided."); } //check if the user entered a Mastercard credit card if (response.sourceOfFunds.provided.card.scheme == 'MASTERCARD') { console.log("The user entered a Mastercard credit card.") } } else if ("fields_in_error" == response.status) { console.log("Session update failed with field errors."); if (response.errors.cardNumber) { console.log("Card number invalid or missing."); } if (response.errors.expiryYear) { console.log("Expiry year invalid or missing."); } if (response.errors.expiryMonth) { console.log("Expiry month invalid or missing."); } if (response.errors.securityCode) { console.log("Security code invalid."); } } else if ("request_timeout" == response.status) { console.log("Session update failed with request timeout: " + response.errors.message); } else if ("system_error" == response.status) { console.log("Session update failed with system error: " + response.errors.message); } } else { console.log("Session update failed: " + response); } } }, interaction: { displayControl: { formatCard: "EMBOSSED", invalidFieldCharacters: "REJECT" } } }); function pay() { // UPDATE THE SESSION WITH THE INPUT FROM HOSTED FIELDS PaymentSession.updateSessionFromForm('card'); } </script> </body> </html>
Creazione di una sessione inviando una richiesta Create Session
dall'applicazione lato server. Specificare un limite di autenticazione della sessione di 25. La risposta restituisce un ID di sessione che è necessario utilizzare nei passaggi successivi per fare riferimento a questa sessione.
URL | https://eu-gateway.mastercard.com/api/rest/version/72/merchant/<your_gateway_merchant_ID>/session |
Metodo HTTP | POST |
{ "session":{ "authenticationLimit":25 } }
Aggiornare la sessione con almeno la valuta e l'importo dell'ordine inviando una richiesta Update Session
dall'applicazione lato server. Questo passaggio è necessario per verificare successivamente se la carta è supportata e se è richiesto il codice di sicurezza della carta.
URL | https://eu-gateway.mastercard.com/api/rest/version/72/merchant/<your_gateway_merchant_ID>/session/<your_session_ID> |
Metodo HTTP | PUT |
{ "order":{ "amount":100.00, "currency":"USD" } }
Includere la libreria session.js
JavaScript client ospitata dal gateway nella pagina di pagamento aggiungendo un elemento script
all'interno dell'elemento head
. Il percorso di questo file include sia la versione api sia l'identificativo esercente per la sessione. Questo posizionerà un oggetto PaymentSession
nello spazio dei nomi della finestra.
<script type="text/javascript" src="https://eu-gateway.mastercard.com/form/version/72/merchant/<your_gateway_merchant_ID>/session.js"></script>
readonly
e che NON presentino l'attributo name
.PaymentSession.configure(configuration)
L'oggetto configuration
consente di allegare campi ospitati alla pagina di pagamento e/o di configurare l'interazione del pagamento. È necessario specificare le seguenti informazioni:
Il clickjacking, noto anche come "rapimento del clic", si verifica quando l'autore dell'attacco usa più livelli trasparenti o opachi per indurre un utente a fare clic su un pulsante o su un collegamento di una pagina credendo di fare clic sulla pagina del livello principale. Per utilizzare Hosted Session, è necessario implementare una o più difese contro gli attacchi di clickjacking tra quelle indicate di seguito.
Opzione di mitigazione dei frame | Implementazione |
javascript |
Includere il JavaScript "frame-breaker" nella pagina di pagamento. |
x-frame-options |
Il server deve restituire un'intestazione della risposta HTTP X-Frame Options. |
csp |
Il server deve restituire l'intestazione della risposta HTTP Content-Security-Policy contenente una direttiva frame-ancestors. |
È necessario specificare le difese implementate mediante il parametro frameEmbeddingMitigation
nella chiamata PaymentSession.configure(configuration)
. Per informazioni su come difendersi dagli attacchi di clickjacking, vedere Clickjacking Defense Cheat Sheet nel sito Web OWASP esterno.
initialized( )
: richiamata quando vengono allegati i campi ospitati alla pagina di pagamento.formSessionUpdate( )
: richiamata in risposta alla funzione PaymentSession.updateSessionFromForm(paymentType)
(vedere il passaggio successivo)Richiamare PaymentSession.updateSessionFromForm('card')
per archiviare i dettagli di pagamento acquisiti per il tipo di pagamento 'card'
in una sessione di pagamento. Una volta completata l'operazione, viene richiamato il callback formSessionUpdate()
con un parametro dei risultati. È necessario verificare il valore result.status
per stabilire se l'operazione è riuscita. Vedere Gestione delle risposte di callback.
È possibile utilizzare la sessione di pagamento restituita (session.id) per eseguire una tokenizzazione o una transazione di pagamento quando richiesto. Per ulteriori informazioni, vedere Eseguire un'operazione usando la sessione
Hosted Session consente di configurare una o più modalità di pagamento tra quelle riportate di seguito per acquisire dettagli di pagamento dal pagante. I dettagli di pagamento vengono acquisiti mediante i campi ospitati allegati al modulo di pagamento, con l'eccezione dei wallet digitali per i quali i dettagli di pagamento vengono acquisiti da un'interazione del wallet.
Mediante i campi ospitati è possibile acquisire i seguenti dettagli della carta:
card.number
card.expiryMonth
card.expiryYear
card.securityCode
card.nameOnCard
card.expiryMonth
è configurato, card.expiryYear
è obbligatorio e viceversa.Mediante i campi ospitati è possibile acquisire i seguenti dettagli della carta prepagata:
giftCard.number
giftCard.pin
Vedere Integrazione della carta prepagata mediante Hosted Session.
Hosted Session consente di acquisire i dettagli di pagamento per i pagamenti diretti (pagamenti) e i depositi diretti (rimborsi) mediante Automated Clearing House. Mediante i campi ospitati, è possibile acquisire i seguenti dettagli Automated Clearing House:
ach.routingNumber
ach.bankAccountNumber
ach.bankAccountNumberConfirmation
ach.bankAccountHolder
ach.accountType
Vedere Integrazione Automated Clearing House mediante Hosted Session.
Hosted Session consente di acquisire i dettagli di pagamento da un'interazione del wallet. Attualmente, sono supportate le interazioni del portafoglio di Secure Remote Commerce. Per iniziare questa interazione, è necessario essere abilitati per Secure Remote Commerce mediante il Mastercard Gateway. Vedere Secure Remote Commerce
Hosted Session consente di fornire un feedback di validazione al pagante durante le varie fasi di interazione del pagamento sull'interfaccia utente:
onValidityChange
:PaymentSession.onValidityChange(["card.number", "card.nameOnCard"], function (selector, result) { if (result.isValid) { console.log("The field value is valid"); document.querySelector(selector).style.borderColor = "green"; } else if (result.isIncomplete) { console.log("The field value is not yet valid"); document.querySelector(selector).style.borderColor = "grey"; } else { console.log("The field value is invalid"); document.querySelector(selector).style.borderColor = "red"; } });
onBlur()
validate()
validate()
PaymentSession.onBlur( ["card.number", "card.nameOnCard", "card.securityCode", "card.expiryYear", "card.expiryMonth"], function (selector, role) { PaymentSession.validate('card', function (allresult) { if (allresult.card[role].isValid) { console.log("The field is valid"); document.querySelector(selector).style.borderColor = "green"; } else { console.log("The field is invalid"); document.querySelector(selector).style.borderColor = "red"; } }); });
updateSessionFromForm()
formSessionUpdate
Indipendentemente dall'approccio, si devono prevedere e gestire errori dal callback formSessionUpdate
. Mentre il metodo validate()
può indicare la validità, la validazione formSessionUpdate
è più completa e può rilevare ulteriori errori.
initialized(result)
result.status=="ok"
I campi ospitati vengono allegati correttamente alla pagina di pagamento.
// An ok response { "status":"ok", }
result.status=="system_error"
o result.status=="request_timeout"
Si è verificato un errore nell'allegare i campi ospitati. Riprovare dopo un breve periodo.
// An error response (system_error) { "status": "system_error", "message": "System error message." } // An error response (request_timeout) { "status" : "request_timeout", "message": "Request timeout error message." }
formSessionUpdate(result)
result.status=="ok"
La sessione ora contiene i dettagli delle carte raccolti.
// An ok response { "status":"ok", "merchant": "TESTMERCHANT", "session": { "id": "SESSION000218450948092491657986" "updateStatus":"SUCCESS", "version":"e3f144ce02" }, "sourceOfFunds": { "provided": { "card": { "brand": "MASTERCARD", "expiry": { "month": "1", "year": "39" }, "fundingMethod": "DEBIT", "nameOnCard": "John Smith", "number": "512345xxxxxx8769", "scheme": "MASTERCARD" } }, "type": "CARD" }, "version": "43" }
result.status=="fields_in_error"
L'input del pagante non è valido ed è necessario richiedere al pagante di aggiornarlo. La struttura di risposte errors
contiene informazioni sui campi non validi.
// An error response (fields_in_error) { "status": "fields_in_error", "session": { "id": "SESSION000218450948092491657986" }, "errors": { "cardNumber": "invalid", "securityCode": "invalid" }, version: "43" }
result.status=="system_error"
o result.status=="request_timeout"
Si è verificato un errore durante l'elaborazione dell'aggiornamento. Riprovare a eseguire l'aggiornamento della sessione dopo un breve periodo.
// An error response (system_error) { "status": "system_error", "session": { "id": "SESSION000218450948092491657986" }, "errors": { "message": "System error message." }, "version": "43" } // An error response (request_timeout) { "status" : "request_timeout", "session": { "id": "SESSION000218450948092491657986" }, "errors": { "message": "Request timeout error message." }, "version": "43" }
Hosted Session consente di registrare le funzioni di callback per gestire eventi che possono verificarsi sui campi ospitati durante l'interazione del pagante.
onChange( )
: richiamato quando il valore di immissione nel campo ospitato nell'iFrame è stato modificato.onFocus( )
: richiamato quando il campo ospitato nell'iFrame è diventato attivo.onBlur( )
: richiamato quando il campo ospitato nell'iFrame non è più attivo.onMouseOver( )
: richiamato quando nel campo ospitato si verifica un evento di passaggio del mouse.onMouseOut( )
: richiamato quando nel campo ospitato si verifica un evento di allontanamento del mouse./** * Provide an array of field roles for proxy fields as the first parameter * Each callback function is invoked with the selector for the field whose proxy triggered the event. */ PaymentSession.onBlur(['card.number'], function(selector) { //handle blur event }); PaymentSession.onFocus(['card.number', 'card.securityCode'], function(selector) { //handle focus event }); PaymentSession.onChange(['card.securityCode'], function(selector) { //handle change event }); PaymentSession.onMouseOver(['card.number'], function(selector) { //handle mouse over event }); PaymentSession.onMouseOut(['card.number'], function(selector) { //handle mouse out event });
Hosted Session consente di applicare uno stile ai campi ospitati in modo che assumano lo stesso aspetto dei campi sostituiti nella pagina di pagamento.
setFocus( )
: imposta lo stato attivo sul campo ospitato specificato.setFocusStyle( )
: imposta gli attributi degli stili per i campi ospitati specificati quando viene impostato lo stato attivo.setHoverStyle( )
: imposta gli attributi degli stili per i campi ospitati specificati quando si verifica il passaggio del mouse.setPlaceholderStyle( )
: imposta gli attributi degli stili per il testo segnaposto per i campi ospitati specificati.setPlaceholderShownStyle( )
: imposta gli attributi degli stili per i campi ospitati specificati se il testo segnaposto è visibile.PaymentSession.setFocus('card.number'); PaymentSession.setFocusStyle(["card.number","card.securityCode"], { borderColor: 'red', borderWidth: '3px' }); PaymentSession.setHoverStyle(["card.number","card.securityCode"], { borderColor: 'red', borderWidth: '3px' }); PaymentSession.setPlaceholderStyle(["card.number", "card.nameOnCard"], { color: 'blue', fontWeight: 'bold', textDecoration: 'underline' }); PaymentSession.setPlaceholderShownStyle(["card.number", "card.nameOnCard"], { color: 'green', fontWeight: 'bold', textDecoration: 'underline' });
Hosted Session consente di utilizzare i valori in elenchi a discesa per il mese di scadenza e l'anno di scadenza. Vedere il codice di esempio qui sotto per maggiori informazioni.
<html> <head> <!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY --> <script src="https://eu-gateway.mastercard.com/form/version/72/merchant/<MERCHANTID>/session.js"></script> <!-- APPLY CLICK-JACKING STYLING AND HIDE CONTENTS OF THE PAGE --> <style id="antiClickjack">body{display:none !important;}</style> </head> <body> <!-- CREATE THE HTML FOR THE PAYMENT PAGE --> <div>Please enter your payment details:</div> <div>Card Number: <input type="text" id="card-number" class="input-field" title="card number" aria-label="enter your card number" value="" tabindex="1" readonly></div> <div>Expiry Month: <select id="expiry-month" class="form-control input-md" required="" readonly> <option value="">Select Month</option> <option value="01">January</option> <option value="02">February</option> <option value="03">March</option> <option value="04">April</option> <option value="05">May</option> <option value="06">June</option> <option value="07">July</option> <option value="08">August</option> <option value="09">September</option> <option value="10">October</option> <option value="11">November</option> <option value="12">December</option> </select> </div> <div>Expiry Year: <select id="expiry-year" class="form-control input-md" required="" readonly> <option value="">Select Year</option> <option>21</option> <option>22</option> <option>23</option> <option>24</option> <option>25</option> <option>26</option> <option>27</option> <option>28</option> <option>29</option> <option>30</option> <option>31</option> <option>32</option> <option>33</option> <option>34</option> <option>35</option> <option>36</option> <option>37</option> <option>38</option> <option>39</option> </select> </div> <div>Security Code:<input type="text" id="security-code" class="input-field" title="security code" aria-label="three digit CCV security code" value="" tabindex="4" readonly></div> <div>Cardholder Name:<input type="text" id="cardholder-name" class="input-field" title="cardholder name" aria-label="enter name on card" value="" tabindex="3" readonly></div> <div><button id="payButton" onclick="pay();">Pay Now</button></div> <!-- JAVASCRIPT FRAME-BREAKER CODE TO PROVIDE PROTECTION AGAINST IFRAME CLICK-JACKING --> <script type="text/javascript"> if (self === top) { var antiClickjack = document.getElementById("antiClickjack"); antiClickjack.parentNode.removeChild(antiClickjack); } else { top.location = self.location; } var sessions = []; PaymentSession.configure({ fields: { // ATTACH HOSTED FIELDS TO YOUR PAYMENT PAGE FOR A CREDIT CARD card: { number: "#card-number", securityCode: "#security-code", expiryMonth: "#expiry-month", expiryYear: "#expiry-year", nameOnCard: "#cardholder-name" } }, //SPECIFY YOUR MITIGATION OPTION HERE frameEmbeddingMitigation: ["javascript"], callbacks: { initialized: function(response) { // HANDLE INITIALIZATION RESPONSE }, formSessionUpdate: function(response) { // HANDLE RESPONSE FOR UPDATE SESSION if (response.status) { if ("ok" == response.status) { console.log("Session updated with data: " + response.session.id); //check if the security code was provided by the user if (response.sourceOfFunds.provided.card.securityCode) { console.log("Security code was provided."); } //check if the user entered a Mastercard credit card if (response.sourceOfFunds.provided.card.scheme == 'MASTERCARD') { console.log("The user entered a Mastercard credit card.") } } else if ("fields_in_error" == response.status) { console.log("Session update failed with field errors."); if (response.errors.cardNumber) { console.log("Card number invalid or missing."); } if (response.errors.expiryYear) { console.log("Expiry year invalid or missing."); } if (response.errors.expiryMonth) { console.log("Expiry month invalid or missing."); } if (response.errors.securityCode) { console.log("Security code invalid."); } } else if ("request_timeout" == response.status) { console.log("Session update failed with request timeout: " + response.errors.message); } else if ("system_error" == response.status) { console.log("Session update failed with system error: " + response.errors.message); } } else { console.log("Session update failed: " + response); } } }, interaction: { displayControl: { formatCard: "EMBOSSED", invalidFieldCharacters: "REJECT" } } }); function pay() { // UPDATE THE SESSION WITH THE INPUT FROM HOSTED FIELDS PaymentSession.updateSessionFromForm('card'); } </script> </body> </html>
Hosted Session offre funzionalità che possono migliorare l'accessibilità del sito Web.
<!-- CREATE THE HTML FOR THE PAYMENT PAGE --> <div>Please enter your payment details:</div> <div>Cardholder Name: <input type="text" id="cardholder-name" class="input-field" title="cardholder name" aria-label="enter name on card" value="" tabindex="1" readonly></div> <div>Card Number: <input type="text" id="card-number" class="input-field" title="card number" aria-label="enter your card number" value="" tabindex="2" readonly></div> <div>Expiry Month:<input type="text" id="expiry-month" class="input-field" title="expiry month" aria-label="two digit expiry month" value="" tabindex="3" readonly></div> <div>Expiry Year:<input type="text" id="expiry-year" class="input-field" title="expiry year" aria-label="two digit expiry year" value="" tabindex="4" readonly></div> <div>Security Code:<input type="text" id="security-code" class="input-field" title="security code" aria-label="card security code" value="" tabindex="5" readonly></div> <div><button id="payButton" onclick="pay();">Pay Now</button></div>
Le opzioni riportate di seguito consentono un migliore controllo dell'esperienza utente dei paganti con esigenze di accessibilità:
L'attributo title dell'iframe del campo ospitato può essere controllato utilizzando un attributo title sul campo.
Hosted Session supporta attributi aria che è possibile utilizzare per migliorare l'esperienza dei paganti che utilizzano tecnologie assistive
Si può prendere in considerazione di accettare tutti i caratteri nei campi ospitati per una migliore esperienza dei paganti utilizzando la tecnologia assistiva. A tal fine, impostare i parametri di visualizzazione interaction.displayControl.invalidFieldCharacters=ALLOW
nel metodo PaymentSession.configure()
.
lang
Aggiungere l'attributo lang all'elemento html.
<html lang="en"> <head></head> <body></body> </html>
Tutti i campi ospitati contengono una etichetta nascosta e i campi ospitati obbligatori contengono un messaggio di errore nascosto. Eventuali errori derivanti dal richiamare PaymentSession.updateSessionFromForm()
genereranno le etichette dei messaggi di errore. È inoltre possibile generare i propri errori utilizzando il metodo PaymentSession.setMessage()
.
Ad esempio, l'etichetta nascosta per il campo del numero della carta è "Numero della carta". Il messaggio di errore nascosto per il numero della carta mancante è "Numero della carta non presente, inserire il valore". Il messaggio di errore nascosto per il numero della carta non valido è "Il numero della carta non è valido, inserire il valore corretto". Durante la tabulazione tra i campi ospitati solo l'etichetta nascosta e il messaggio di errore nascosto vengono letti dallo screen reader ma non l'etichetta o il messaggio di errore effettivi visualizzati sull'interfaccia utente.
La proprietà locale fornisce traduzioni per tutti i campi ospitati, comprese le etichette nascoste e i messaggi di errore. Se questa non è impostata, verrà impostata automaticamente su inglese. I valori supportati per questa proprietà sono de_DE, el_GR, en_US, es_MX, es_ES, fr_CA, fr_FR, it_IT, ja_JA, pl_PL, pt_BR, ro_RO, zh_CN.
Per evitare di confondere i paganti, è consigliabile che l'attributo della lingua corrisponda alla proprietà locale.
PaymentSession.configure({ fields: { card: { nameOnCard: cardHolderNameField ? "#card-holder-name" : null, number: "#card-number", securityCode: "#security-code", expiryMonth: "#expiry-month", expiryYear: "#expiry-year" } }, frameEmbeddingMitigation: ["javascript"], locale:"fr", callbacks: { } });
Una delle funzionalità HTML5 predefinite non funziona con i campi ospitati, ad esempio quando il pagante fa clic sull'etichetta, questa non si focalizza automaticamente sull'elemento input/select corrispondente. A questo scopo, utilizzare setFocus
.
Hosted Session consente di accettare più carte dal pagante sulla stessa pagina. In questo caso, ogni carta diventa una sessione di pagamento separata e un ordine separato (quando si utilizza la sessione di pagamento in una transazione di pagamento). Questa opzione può essere utile, ad esempio, quando un cliente desidera poter pagare utilizzando più carte per la stessa prenotazione. Il sito Web deve quindi essere in grado di combinare tali ordini generati da sessioni di pagamento separate in un'unica prenotazione per il cliente.
Per accettare più carte, è necessario richiamare la funzione PaymentSession.configure()
utilizzando il parametro scope
. Questo parametro può essere qualsiasi stringa univoca utilizzata per identificare un blocco di dati di pagamento di una carta e non deve necessariamente fare riferimento a uno specifico html sulla pagina. I dati archiviati sul server dell'esercente per ogni carta dovrebbero essere conservati in un ambito separato.
PaymentSession.configure('configuration', scope)
Il parametro scope
è obbligatorio per le chiamate Hosted Session indicate di seguito se la chiamata iniziale PaymentSession.configure()
viene richiamata con scope
.
PaymentSession.updateSessionFromForm('card', 'card-type', scope)
PaymentSession.setFocus('cardNumber', scope)
Il parametro scope
è opzionale per le chiamate indicate di seguito se un'interazione viene configurata con un ambito. Se l'ambito non viene specificato sulle chiamate, la funzione/il callback sarà applicata/o a tutti i set di dati all'interno dell'iFrame ospitato.
PaymentSession.setFocusStyle([<HostedFieldsRole>], styles, scope)
PaymentSession.setHoverStyle([<HostedFieldsRole>], styles, scope)
PaymentSession.onFocus([<HostedFieldsRole>],function(selector), scope)
PaymentSession.onBlur([<HostedFieldsRole>], function(selector), scope)
PaymentSession.onChange([<HostedFieldsRole>], function(selector), scope)
PaymentSession.onMouseOver([<HostedFieldsRole>], function(selector), scope)
PaymentSession.onMouseOut([<HostedFieldsRole>], function(selector), scope)
<html> <head> <!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY --> <script src="https://eu-gateway.mastercard.com/form/version/72/merchant/<MERCHANTID>/session.js"></script> <!-- APPLY CLICK-JACKING STYLING AND HIDE CONTENTS OF THE PAGE --> <style id="antiClickjack">body{display:none !important;}</style> </head> <body> <!-- CREATE THE HTML FOR THE PAYMENT PAGE --> <div>Please enter your payment details:</div> <div>Cardholder Name: <input type="text" id="cardholder-name" class="input-field" title="cardholder name" aria-label="enter name on card" value="" tabindex="1" readonly></div> <div>Card Number: <input type="text" id="card-number" class="input-field" title="card number" aria-label="enter your card number" value="" tabindex="2" readonly></div> <div>Expiry Month:<input type="text" id="expiry-month" class="input-field" title="expiry month" aria-label="two digit expiry month" value="" tabindex="3" readonly></div> <div>Expiry Year:<input type="text" id="expiry-year" class="input-field" title="expiry year" aria-label="two digit expiry year" value="" tabindex="4" readonly></div> <div>Security Code:<input type="text" id="security-code" class="input-field" title="security code" aria-label="three digit CCV security code" value="" tabindex="5" readonly></div> <div><button id="payButton" onclick="pay();">Pay Now</button></div> <!-- JAVASCRIPT FRAME-BREAKER CODE TO PROVIDE PROTECTION AGAINST IFRAME CLICK-JACKING --> <script type="text/javascript"> if (self === top) { var antiClickjack = document.getElementById("antiClickjack"); antiClickjack.parentNode.removeChild(antiClickjack); } else { top.location = self.location; } var sessions = []; PaymentSession.configure({ fields: { // ATTACH HOSTED FIELDS TO YOUR PAYMENT PAGE FOR A CREDIT CARD card: { number: "#card-number", securityCode: "#security-code", expiryMonth: "#expiry-month", expiryYear: "#expiry-year", nameOnCard: "#cardholder-name" } }, //SPECIFY YOUR MITIGATION OPTION HERE frameEmbeddingMitigation: ["javascript"], callbacks: { initialized: function(response) { // HANDLE INITIALIZATION RESPONSE }, formSessionUpdate: function(response) { // HANDLE RESPONSE FOR UPDATE SESSION AS PER USUAL MANNER. if (response.status) { if ("ok" == response.status) { // RECORD THE SESSIONID RETURNED AND ASSOCIATE IT WITH THE SCOPE CONFIGURED. sessions.push(JSON.parse('{ "scopeId": "' + response.scopeId + '", "sessionId": "' + response.session.id + '"}')); } } else { console.log("Session update failed: " + response); } } }, interaction: { displayControl: { formatCard: "EMBOSSED", invalidFieldCharacters: "REJECT" } } }, 'card-payment-details-#1'); // ADD ANY UNIQUE STRING IDENTIFIER VALUE TO THE CONFIGURE CALL function pay() { sessions.forEach(function (e) { // UPDATE THE SESSION WITH THE FIELD VALUES. THE SCOPE MUST BE THE THIRD PARAMETER. PaymentSession.updateSessionFromForm('card', undefined, e.scopeId); }); } </script> </body> </html>
Prima di effettuare il go live, è necessario eseguire il test dell'integrazione per verificare il corretto funzionamento.
Per supportare più accessi durante il test dell'integrazione Hosted Session (eseguiti con un ID esercente di PROVA), aggiungere ?debug=true
all'URL.
https://eu-gateway.mastercard.com/form/version/72/merchant/<TESTMERCHANTID>/session.js?debug=true
Per gestire questo evento, analizzare le informazioni sul tipo di carta (sourceOfFunds.provided.card.brand
e sourceOfFunds.provided.card.scheme
) nella risposta PaymentSession.updateSessionFromForm('card')
, eseguire la convalida in base all'elenco di tipi di carta supportati e visualizzare un messaggio di errore se il tipo di carta non è accettato.
Se il pagante non fornisce il valore CSC/CVV, il campo securityCode
NON viene restituito nella risposta PaymentSession.updateSessionFromForm('card')
. Se è richiesto un valore CSC/CVV e tale valore non è presente, è necessario visualizzare un errore al pagante.
Esistono problemi noti con i callback eventi sui seguenti sistemi operativi e browser:
interaction.displayControl.formatCard=EMBOSSED
, l'evento onChange
non viene attivato quando si modifica il valore di un campo ospitato.onChange( )
e onBlur( )
non vengono attivati quando il pagante immette i dati in un campo ospitato e tocca un altro campo nella pagina di pagamento. Inoltre il pagante non può navigare dai campi ospitati ad altri campi della pagina di pagamento e viceversa.A partire dalla versione 51 dell'API, è possibile acquisire i dettagli di pagamento da una o più carte in un'interazione Hosted Session. Ciò consente al pagante di utilizzare più carte di credito per un'unica prenotazione; tuttavia poiché i dettagli di pagamento per ogni carta generano un ordine separato, è responsabilità dell'esercente riunire questi ordini separati in un'unica prenotazione per il pagante.
Viene creato un identificativo di sessione univoco per ogni carta che deve essere salvato sul server Web dell'esercente. Il pagante può scegliere di eliminare una carta durante un'interazione e tale azione elimina i dati della sessione associati alla carta dal server Web dell'esercente.
Il modello POST Hosted Payment Session è stato reso obsoleto dall'integrazione JavaScript (session.js) di Hosted Session.
Per le integrazioni POS Hosted Payment Session esistenti, vedere linee guida per l'integrazione e Riferimento API.
Il modello JavaScript HPF.js Hosted Payment Session è stato reso obsoleto dall'integrazione JavaScript (session.js) di Hosted Session.
Per le integrazioni HPF.js Hosted Payment Session esistenti, vedere linee guida per l'integrazione e Riferimento API.