Implementarea unei integrări Hosted Session

Biblioteca de clienți JavaScript Hosted Session permite colectarea de informații sensibile de plată de la plătitor în câmpurile formularului de plată găzduit de eGenius Platform. Gateway-ul colectează detaliile sensibile de plată din cadrul unei sesiuni de plată și le stochează temporar pentru utilizarea ulterioară. Apoi, puteți include o sesiune de plată în locul detaliilor de plată în solicitarea de tranzacție pentru procesarea unei plăți. Pentru mai multe informații, consultați sesiunea de plată.

Hosted Session este o metodă de integrare compatibilă cu PCI v3 care facilitează conformitatea cu SAQ-A, oferind, în același timp, controlul asupra dispunerii și stilului paginii de plată. În acest model, toate câmpurile de plată cu informații sensibile sunt încorporate în cadrele iFrame obținute și controlate din eGenius Platform. Mecanismele standard de securitate din browsere izolează câmpurile sensibile față de dvs., păstrând integritatea canalului de plată creat de gateway.

Cerințe preliminare

  • Asigurați-vă că profilul dvs. comerciant este activat pentru serviciul de Hosted Session.
  • Hosted Session este acceptat în API începând cu versiunea 18.

Solicitare a unei interacțiuni Hosted Session

Această secțiune descrie o integrare simplă prin care Hosted Session poate colecta detaliile cardului de credit al plătitorului.

<html>
<head>
<!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY -->
<script src="https://egenius.unicredit.ro/form/version/61/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({
    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>

Pasul 1: Creați o sesiune

Creați o sesiune trimițând o solicitare Create Session din aplicația de pe serverul dvs. Specificați o limită de autentificare pentru sesiune de 25. Răspunsul returnează un ID de sesiune pe care trebuie să îl folosiți în cadrul pașilor ulteriori pentru a referenția această sesiune.

URL https://egenius.unicredit.ro/api/rest/version/61/merchant/<your_gateway_merchant_ID>/session
Metoda HTTP POST
 {
   "session":{
      "authenticationLimit":25
   }
}

Pasul 2: Actualizați sesiunea cu valoarea comenzii și moneda

Actualizați sesiunea cel puțin cu moneda și valoarea comenzii, trimițând o solicitare Update Session din aplicația de pe serverul dvs. Acest pas este obligatoriu pentru a interoga ulterior dacă cardul este acceptat și dacă codul de securitate a cardului este obligatoriu.

Includeți parametrul sector de activitate în solicitarea Update Session dacă acest lucru este posibil pentru această comandă.
URL https://egenius.unicredit.ro/api/rest/version/61/merchant/<your_gateway_merchant_ID>/session/<your_session_ID>
Metoda HTTP PUT
 {
    "order":{
       "amount":100.00,
       "currency":"USD"
    }
 }

Pasul 3: Includeți session.js Client JavaScript Library pe pagina dvs. de plată

Includeți biblioteca JavaScript client session.js găzduită de gateway în pagina dvs. de plată, adăugând un element script în elementul head. Calea către acest fișier include atât versiunea API, cât și identificatorul comerciantului pentru sesiune. Această acțiune plasează un obiect PaymentSession în spațiul de nume al ferestrei.

<script type="text/javascript" src="https://egenius.unicredit.ro/form/version/61/merchant/<your_gateway_merchant_ID>/session.js"></script>

Pasul 4: Creați codul HTML pentru pagina de plată care conține câmpurile cardului de credit

Pentru a preveni trimiterea datelor sensibile către server, asigurați-vă că toate câmpurile cu date sensibile sunt readonly și NU au atributul name .

Pasul 5: Invocați funcția PaymentSession.configure(configuration)

Obiectul configuration permite atașarea câmpurilor găzduite la pagina dvs. de plăți și/sau configurarea interacțiunii de plată. Este necesar să furnizați următoarele:

  • Includeți session.id creat la Pasul 1: Creați o sesiune.
  • Selectoarele de câmpuri pentru câmpurile cardului de credit; odată furnizate, acestea sunt înlocuite cu câmpurile proxy corespunzătoare încorporate în cadrele iFrame găzduite de eGenius Platform. Câmpurile proxy vor avea același aspect și stil cu cele ale câmpurilor înlocuite. Puteți captura detaliile de plată pentru alte tipuri de plăți, a se vedea Metodele de plată acceptate în Hosted Session.
  • opțiuni de neutralizare a fraudării prin clickjacking

    Clickjackingul, cunoscut și sub numele de „atac prin mascarea IU” este o metodă prin care atacatorul utilizează mai multe straturi transparente sau opace pentru a determina utilizatorul să facă clic pe un buton sau un link către o altă pagină atunci când acesta intenționează să facă clic pe pagina de nivel superior. Pentru a utiliza Hosted Session, trebuie să implementați unul sau mai multe dintre următoarele mijloace de protecție împotriva atacurilor prin clickjacking.

    Opțiunea de neutralizare a cadrelor Implementare
    javascript includeți codul JavaScript „frame-breaker” pe pagina dvs. de plată.
    x-frame-options serverul dvs. trebuie să returneze un antet de răspuns HTTP cu opțiuni X-Frame.
    csp serverul dvs. trebuie să returneze un antet de răspuns HTTP cu politica de securitate a conținutului, care să includă o directivă de tip frame-ancestors.

    Trebuie să specificați mijloacele de protecție implementate prin parametrul frameEmbeddingMitigation din apelul PaymentSession.configure(configuration). Pentru informații privind protecția împotriva atacurilor prin clickjacking, consultați Ghidul de protecție împotriva atacurilor prin clickjacking de pe site-ul web extern OWASP.

  • funcțiile callback pentru gestionarea diferitelor evenimente din timpul interacțiunii cu Hosted Session
    • initialized( ): invocate când câmpurile găzduite sunt atașate paginii dvs. de plată.
    • formSessionUpdate( ): invocate ca reacție la funcția PaymentSession.updateSessionFromForm(paymentType) (a se vedea pasul următor)

Pasul 6: Invocați updateSessionFromForm

Invocați PaymentSession.updateSessionFromForm('card') pentru a stoca detaliile de plată capturate pentru tipul de plată 'card' într-o sesiune de plată. După finalizarea operațiunii, funcția callback formSessionUpdate() este invocată cu un parametru de rezultat. Trebuie să verificați valoarea result.status pentru a determina dacă operațiunea a avut succes. Consultați secțiunea Gestionarea răspunsurilor callback

Pasul 7: Utilizați datele sesiunii de plată

Puteți utiliza sesiunea de plată returnată (session.id) pentru a efectua o creare de simbol sau o tranzacție de plată atunci când este necesar. Pentru mai multe informații, consultați secțiunea Realizarea unei operațiuni prin utilizarea sesiunii.

Metodele de plată acceptate în Hosted Session

Hosted Session vă permite să configurați una sau mai multe dintre metodele de plată de mai jos pentru a captura detaliile de plată de la plătitor. Detaliile de plată sunt capturate prin câmpuri găzduite atașate formularului dvs. de plată, cu excepția portofelelor electronice, pentru care detaliile de plată sunt capturate printr-o interacțiune cu portofelul electronic.

Pentru fiecare metodă de plată acceptată, Hosted Session vă permite să colectați și să trimiteți detalii de plată complete, parțiale sau individuale (exceptând luna de expirare a cardului și anul de expirare a cardului) în cadrul unei sesiuni de plată. Puteți utiliza sesiunea de plată returnată în combinație cu mai multe surse pentru a procesa o plată. De exemplu, dacă ați creat deja un simbol pentru numărul și data de expirare a cardului plătitorului, atunci puteți utiliza Hosted Session pentru a colecta numai codul CSC/CVV, utilizând împreună detaliile cardului din ambele surse pentru a efectua o plată. Ca alternativă, puteți utiliza Hosted Session pentru a colecta numai data expirării cardului în sesiunea de plată, actualizând apoi un card expirat stocat împreună cu un simbol.
Cardurile de credit/debit

Prin câmpurile găzduite, puteți captura următoarele detalii ale cardurilor:

  • card.number
  • card.expiryMonth
  • card.expiryYear
  • card.securityCode
  • card.nameOnCard
Toate câmpurile sunt opționale, însă, dacă card.expiryMonth este configurat, card.expiryYear va fi obligatoriu și vice-versa.

Prin câmpurile găzduite, puteți captura următoarele detalii ale cardurilor cadou:

  • giftCard.number
  • giftCard.pin

Consultați Integrarea cardurilor cadou prin Hosted Session.

Hosted Session vă permite să capturați detaliile plăților pentru plățile directe (plăți) și depunerile directe (rambursări) prin Automated Clearing House. Prin câmpurile găzduite, puteți captura următoarele detalii Automated Clearing House:

  • ach.routingNumber
  • ach.bankAccountNumber
  • ach.bankAccountHolder
  • ach.accountType

Consultați Integrarea Automated Clearing House prin Hosted Session.

Portofelele electronice

Hosted Session vă permite să capturați detaliile de plată din interacțiunea cu portofelele electronice. În prezent, interacțiunile cu portofelul Secure Remote Commerce sunt acceptate. Trebuie să aveți activată opțiunea Secure Remote Commerce prin eGenius Platform pentru a iniția această interacțiune. Consultați Secure Remote Commerce.

Feedback de validare a datelor din câmp

Hosted Session vă permite să furnizați feedback de validare plătitorului pe durata diferitelor etape ale interacțiunii de plată, pe interfața cu utilizatorul:

  • La fiecare apăsare de taste prin ascultarea funcției de callback 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";
    
          }
    
        });
    
  • După ce plătitorul a terminat de tastat și părăsește câmpul:
    1. Ascultarea evenimentului onBlur()
    2. Invocarea validate()
    3. Afișarea erorilor asociate cu câmpul respectiv din funcția callback 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";
    
    }
    
    });
    
    });
    
  • Atunci când plătitorul face clic pe butonul pentru acțiunea următoare de pe pagină:
    1. Invocarea updateSessionFromForm()
    2. Afișarea tuturor erorilor din funcția callback formSessionUpdate

Indiferent de abordare, trebuie să așteptați și să gestionați erorile din funcția callback formSessionUpdate. Chiar dacă metoda validate() poate indica validitatea, validarea formSessionUpdate este mai amplă și poate detecta erori suplimentare.

Gestionarea răspunsurilor callback

Rezultatele pentru câmpurile găzduite prin initialized(result)
Dacă result.status=="ok"

Câmpurile găzduite sunt atașate cu succes paginii dvs. de plată.

       // An ok response
{
    "status":"ok",
}
       
Dacă result.status=="system_error" sau result.status=="request_timeout"

A apărut o eroare în decursul atașării câmpurilor găzduite. Reîncercați după o scurtă perioadă de timp.

// 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."
}
       
Rezultatele pentru Update Session prin formSessionUpdate(result)
Dacă result.status=="ok"

Sesiunea conține acum detaliile colectate ale cardului.

// An ok response
{
    "status":"ok",
    "merchant": "TESTMERCHANT",
    "session": {
        "id": "SESSION000218450948092491657986"
        "updateStatus":"SUCCESS",
        "version":"e3f144ce02"
    },
    "sourceOfFunds": {
        "provided": {
            "card": {
                "brand": "MASTERCARD",
                "expiry": {
                    "month": "5",
                    "year": "21"
                },
                "fundingMethod": "DEBIT",
                "nameOnCard": "John Smith",
                "number": "512345xxxxxx8769",
                "scheme": "MASTERCARD"
            }
        },
        "type": "CARD"
    },   
    "version": "43"
}
       
Dacă result.status=="fields_in_error"

Datele introduse de plătitor sunt nevalide și trebuie să îi solicitați să le actualizeze. Structura răspunsului errors conține informații despre câmpurile nevalide.

       // An error response (fields_in_error)
{
    "status": "fields_in_error",  
    "session": {
        "id": "SESSION000218450948092491657986"
    },
    "errors": {
        "cardNumber": "invalid",
        "securityCode": "invalid"  
    },
    version: "43"
}
       
Dacă result.status=="system_error" sau result.status=="request_timeout"

A apărut o eroare la procesarea actualizării. Reîncercați actualizarea sesiunii după o scurtă perioadă de timp.

       // 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"
}
       

Ascultați evenimentele din câmpuri găzduite

Hosted Session permite înregistrarea funcțiilor callback pentru gestionarea evenimentelor care pot apărea în câmpurile găzduite în timpul interacțiunii cu plătitorul.

Puteți înregistra funcții callback pentru următoarele evenimente:
  • onChange( ): Invocate când valoarea introdusă în câmpul găzduit din iFrame s-a modificat.
  • onFocus( ): Invocate când câmpul găzduit din iFrame este selectat.
  • onBlur( ): Invocate când câmpul găzduit din iFrame nu mai este selectat.
  • onMouseOver( ): Invocate când cursorul mouse-ului trece peste câmpul găzduit.
  • onMouseOut( ): Invocate când cursorul mouse-ului trece de câmpul găzduit.
 /**
 * 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
});
    

Stilul avansat pentru câmpurile găzduite

Hosted Session permite setarea stilului câmpurilor găzduite în funcție de aspectul și stilul câmpurilor înlocuite de pe pagina dvs. de plată.

Puteți invoca următoarele funcții de stil:
  • setFocus( ): Setează evidențierea pentru câmpul găzduit specificat.
  • setFocusStyle( ): Setează atributele de stil pentru câmpurile găzduite specificate când acestea sunt evidențiate.
  • setHoverStyle( ): Setează atributele de stil pentru câmpurile găzduite specificate când cursorul mouse-ului trece peste acestea.
  • setPlaceholderStyle( ): Setează atributele de stil pentru textul substituent asociat cu câmpurile găzduite specificate.
  • setPlaceholderShownStyle( ): Setează atributele de stil pentru câmpurile găzduite specificate atunci când textul substituent este vizibil.
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'
});

Câmpuri derulante pentru luna și anul expirării

Hosted Session vă permite să utilizați valori derulante pentru luna și anul expirării. Consultați exemplul de cod de mai jos pentru detalii.

Detalii
<html>
<head>
<!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY -->
<script src="https://egenius.unicredit.ro/form/version/61/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>
</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>
	

Configurare accesibilitate câmpuri găzduite

Hosted Session include funcții care pot îmbunătăți accesibilitatea site-ului dvs. web.

Detalii
<!-- 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> 

Următoarele opțiuni oferă un control mai bun al experienței utilizatorului pentru plătitorii cu nevoi speciale de accesibilitate:

Setarea titlului cardului iFrame

Atributul title al cadrului iFrame al câmpului găzduit poate fi controlat cu ajutorul unui atribut title al câmpului.

Setarea atributelor de accesibilitate îmbogățită ale aplicației de internet

Hosted Session acceptă atributele aria, pe care le puteți utiliza pentru a optimiza experiența plătitorilor care utilizează tehnologii de asistare.

Setarea parametrului de afișare a caracterelor nevalide

Luați în calcul posibilitatea de a accepta toate caracterele în câmpurile găzduite, pentru o experiență mai bună a plătitorilor care utilizează tehnologii de asistare. În acest scop, setați parametrul de afișare interaction.displayControl.invalidFieldCharacters=ALLOW în metoda PaymentSession.configure().

Setați atributul lang

Adăugați atributul lang la elementul html.

<html lang="en">
    <head></head>
    <body></body>
</html>

Etichetă ascunsă și mesaj de eroare

Toate câmpurile găzduite conțin o etichetă ascunsă, iar câmpurile găzduite obligatorii conțin un mesaj de eroare ascuns. Toate erorile detectate la invocarea PaymentSession.updateSessionFromForm() vor genera etichete de mesaje de eroare. Suplimentar, puteți semnala erorile proprii folosind metoda PaymentSession.setMessage().

De exemplu, eticheta ascunsă pentru câmpul numărului de card este „Număr de card”. Mesajul de eroare ascuns pentru numărul de card lipsă este „Numărul de card lipsește, introduceți o valoare”. Mesajul de eroare ascuns pentru numărul de card nevalid este „Numărul de card este nevalid, introduceți o valoare corectă”. În timp ce navigați printre filele câmpurilor găzduite, cititorul de ecran citește doar eticheta ascunsă și mesajul de eroare ascuns, nu și eticheta sau mesajul de eroare afișat efectiv pe UI.

Setați proprietatea regională în obiectul de configurare

Proprietatea regională oferă traduceri pentru toate câmpurile găzduite, inclusiv pentru etichetele și mesajele de eroare ascunse. Dacă nu este configurată, setarea implicită va fi limba Engleză. Valorile acceptate pentru această proprietate sunt 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.

Pentru a evita confuzia plătitorilor, este recomandat ca atributul lang să fie corelat cu proprietatea regională.

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: {
    }
});

Focalizare automată

Una dintre funcțiile implicite HTML5 nu este compatibilă cu câmpurile găzduite, și anume, atunci când plătitorul face clic pe etichetă, nu focalizează automat pe elementul introdus/selectat corespunzător. Utilizați setFocus în acest scop.

Câmpurile găzduite nu sunt accesibile pe web atunci când utilizați IE 11 împreună cu cititorul de ecran SuperNova.

Acceptarea mai multor carduri în Hosted Session

Hosted Session vă permite să acceptați mai multe carduri de la plătitorul dvs. pe aceeași pagină. În acest caz, fiecare card devine o sesiune de plată separată și o comandă separată (când utilizați sesiunea de plată într-o tranzacție de plată). Acest lucru poate fi util, de exemplu, atunci când un client dorește să poată plăti folosind mai multe carduri pentru aceeași rezervare. Site-ul dvs. web trebuie să poată asambla apoi aceste comenzi generate prin sesiuni de plată separate într-o singură rezervare pentru client.

Cardurile multiple prin Hosted Session sunt acceptate în API numai începând cu versiunea 51.
Detalii

Solicitarea unei interacțiuni Hosted Session multiple

Pentru a accepta mai multe carduri, trebuie să invocați funcția PaymentSession.configure() folosind parametrul scope. Acest parametru poate fi orice șir unic utilizat pentru identificarea unui bloc de date privind plata cu cardul; nu este necesar să facă referire la un anumit fragment de cod HTML de pe pagină. Datele stocate de dvs. pe serverul dvs. de comerciant pentru fiecare card trebuie păstrate într-un domeniu separat.

  • PaymentSession.configure('configuration', scope)

Parametrul scope din următoarele apeluri Hosted Session devine obligatoriu odată ce apelul PaymentSession.configure() inițial este invocat cu scope.

  • PaymentSession.updateSessionFromForm('card', 'card-type', scope)
  • PaymentSession.setFocus('cardNumber', scope)

Parametrul scope este opțional în următoarele apeluri dacă o interacțiune este configurată cu un domeniu. Dacă apelurile nu specifică un domeniu, funcția/callback-ul se va aplica tuturor seturilor de date de carduri din cadrul iFrame găzduit.

  • 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)

Exemplu

<html>
<head>
<!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY -->
<script src="https://egenius.unicredit.ro/form/version/61/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>

Testați integrarea

Înainte de a începe lucrul în mediul real, trebuie să testați integrarea pentru a vă asigura de funcționarea corectă.

Pentru a permite jurnalizarea suplimentară în timpul testării integrării dvs. Hosted Session (folosind un ID de comerciant de tip TEST), adăugați ?debug=true la URL-ul dvs.

https://egenius.unicredit.ro/form/version/61/merchant/<TESTMERCHANTID>/session.js?debug=true
Hosted Session necesită activarea JavaScript în browserul plătitorului. Browserele acceptate sunt: IE 11, Safari iOS13/12, Safari OSX13, Microsoft Edge 18, Firefox, Android 4.4, Android 5 și Chrome.

Depanare și întrebări frecvente

Cum pot gestiona evenimentele în care tipul de card introdus de plătitor nu este acceptat în profilul meu de comerciant?

Pentru a gestiona acest eveniment, inspectați informațiile privind tipul de card (sourceOfFunds.provided.card.brand și sourceOfFunds.provided.card.scheme) din răspunsul PaymentSession.updateSessionFromForm('card'), validați-le folosindu-vă lista de tipuri de card acceptate și afișați un mesaj de eroare dacă tipul de card nu este acceptat.

Cum pot detecta dacă plătitorul a furnizat codul CSC/CVV într-o interacțiune Hosted Session?

Dacă plătitorul nu furnizează codul CSC/CVV, câmpul securityCode NU este returnat în răspunsul PaymentSession.updateSessionFromForm('card'). Dacă impuneți utilizarea codului CSC/CVV și nu este prezentă nicio valoare, trebuie să afișați o eroare pentru plătitor.

Funcțiile callback pentru evenimentele din câmpurile găzduite funcționează în toate browserele?

Există probleme cunoscute cu funcțiile callback pentru evenimente în următoarele sisteme de operare și browsere:

  • Internet Explorer 11 în Windows 10: Dacă interaction.displayControl.formatCard=EMBOSSED, evenimentul onChange nu este declanșat atunci când schimbați valoarea unui câmp găzduit.
  • iOS9 în iPhone 6+: Evenimentele onChange( ) și onBlur( ) nu sunt găzduite atunci când plătitorul introduce date într-un câmp găzduit și atinge un alt câmp de pe pagina de plată. În plus, plătitorul nu poate naviga de la câmpurile găzduite la alte câmpuri de pe pagina de plată și invers.
  • Evenimentele de trecere a cursorului nu sunt acceptate pe dispozitivele cu ecran tactil.
Pot colecta detaliile de plată pentru mai multe carduri într-o interacțiune Hosted Session?

De la versiunea 51 a API, puteți colecta detaliile de plată pentru unul sau mai multe carduri de credit în cadrul unei interacțiuni Hosted Session. Acest lucru permite plătitorului să utilizeze mai multe carduri de credit pentru a plăti pentru o singură rezervare; dat fiind, însă, că detaliile de plată pentru fiecare card generează o comandă separată, aveți responsabilitatea de a asambla aceste comenzi separate într-o singură rezervare pentru plătitor.

Un identificator unic de sesiune este creat pentru fiecare card, acesta trebuind să fie stocat pe serverul dvs. web. Plătitorul poate alege să elimine un card în timpul interacțiunii; această acțiune elimină datele de sesiune asociate cardului de pe serverul dvs. web.

Unde pot găsi ghidul de integrare și referința API pentru modelul Hosted Payment Session POST?

Modelul Hosted Payment Session POST este înlocuit de integrarea Hosted Session JavaScript (session.js).

Pentru integrările Hosted Payment Session POST existente, consultați ghidul de integrare și referința API.

Unde pot găsi ghidul de integrare și referința API pentru modelul JavaScript Hosted Payment Session HPF.js?

Modelul JavaScript Hosted Payment Session HPF.js este înlocuit de integrarea Hosted Session JavaScript (session.js).

Pentru integrările Hosted Payment Session HPF.js existente, consultați ghidul de integrare și referința API.

Copyright © 2021 UniCredit Bank