Efectuarea unei plăți
Acest subiect descrie pașii pe care trebuie să îi urmați pentru a efectua o plată folosind o sesiune în care colectați date sensibile de plată de la plătitor cu câmpuri găzduite pe pagina dvs. de plată. Acest lucru se realizează utilizând Session JavaScript library(session.js) în combinație cu WSAPI. Pentru un exemplu de fragment de cod complet al implementării întregii pagini de plată pe un site web, consultați Exemplu de cod pentru pagina de plată.
Pasul 1: Creați o sesiune
Creați o sesiune trimițând o solicitare Create Session. de la 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 face referire la această sesiune.
| URL | https://egenius.unicredit.ro/api/rest/version/72/merchant/<merchant_ID>/session |
| Metoda HTTP | POST |
{
"session": {
"authenticationLimit": 25
}
}
Pasul 2: Actualizați sesiunea cu detaliile comenzii
Actualizați sesiunea cel puțin cu moneda și valoarea comenzii, trimițând o solicitare Update Session. de pe serverul dvs. Moneda comenzii este necesară pentru a putea stabili dacă cardul de credit pe care plătitorul dorește să îl folosească este acceptat și dacă trebuie să furnizeze codul de securitate al cardului (CSC).
| URL | https://egenius.unicredit.ro/api/rest/version/72/merchant/<merchant_ID>/session/<session_ID> |
| Metoda HTTP | PUT |
{
"order": {
"amount": 100,
"currency": "USD"
}
}
Pasul 3: Includeți biblioteca Session JavaScript
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.
<html> <head> <script src="https://egenius.unicredit.ro/form/version/72/merchant/<MERCHANTID>/session.js"></script> </head> </html>
Pasul 4: Crearea paginii de plată
Creați codul HTML pentru pagina dvs. de plată, inclusiv câmpurile pentru a culege detaliile de plată necesare de la plătitor.
readonly și omiteți atributul name .Puteți utiliza una sau mai multe dintre următoarele metode de plată pentru a captura detaliile de plată de la plătitor. Câmpurile pe care trebuie să le includeți pe pagina dvs. de plată depind de metoda de plată:
Carduri de credit și debit
Puteți captura următoarele detalii ale cardului în câmpurile găzduite:
card.numbercard.expiryMonthcard.expiryYearcard.securityCodecard.nameOnCard
card.expiryMonth este utilizat, card.expiryYear va fi obligatoriu și vice-versa.Click to Pay
Puteți captura detaliile de plată din interacțiunea Click to Pay. Pentru mai multe informații, consultați Integrarea Click to Pay Hosted Session.
Următorul cod exemplu ilustrează câmpurile necesare din pagina de plată pentru o plată cu cardul de credit.
<!-- 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>
Pasul 5: Configurarea sesiunii
Invocați funcția PaymentSession.configure() cu un obiect de configurare ca argument pentru a atașa câmpurile găzduite la pagina dvs. de plată și pentru a configura interacțiunea de plată. Trebuie să furnizați următoarele în obiectul de configurare:
- ID-ul sesiunii primit când ați creat sesiunea.
- Selectoare de câmpuri pentru câmpurile găzduite pentru anumite metode de plată. Configurația le înlocuiește cu câmpurile proxy corespunzătoare încorporate în iFrame găzduit de eGenius Platform. Câmpurile proxy au același aspect și stil ca cele înlocuite.
- 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 una sau mai multe dintre următoarele apărări împotriva atacurilor de tip clickjacking și să specificați ce apărări sunt implementate folosind câmpul frameEmbeddingMitigation:
- Javascript: Includeți JavaScript „frame-breaker” pe pagina dvs. de plată.
- x-frame-options: Serverul dvs. returnează un antet de răspuns HTTP cu opțiuni X-Frame.
- csp: Serverul dvs. returnează un antet de răspuns HTTP cu politica de securitate a conținutului, care să includă o directivă de tip frame-ancestors.
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() este invocat atunci când câmpurile găzduite se atașează paginii dvs. de plată.
- formSessionUpdate() este invocat ca răspuns la funcția PaymentSession.updateSessionFromForm(paymentType) (consultați pasul următor).
- Detalii ale interacțiunii care definesc vizibilitatea și opțiunile de interacțiune cu plătitorul pentru unele informații afișate.
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
},
},
interaction: {
displayControl: {
formatCard: “EMBOSSED”,
invalidFieldCharacters: “REJECT”
}
}
});
Pasul 6: Actualizați sesiunea cu detaliile câmpurilor
După ce plătitorul și-a introdus detaliile de plată în câmpurile găzduite, invocați funcția PaymentSession.updateSessionFromForm() cu metoda de plată aplicabilă ca argument. Funcția stochează detaliile de plată decontate în sesiunea de plată. După finalizarea operațiunii, funcția callback formSessionUpdate() este invocată cu un parametru de rezultat. Verificați câmpul rezultat.status pentru a determina dacă operația a avut succes. Pentru mai multe informații, consultați Gestionarea răspunsurilor callback.
function pay() {
// UPDATE THE SESSION WITH THE INPUT FROM HOSTED FIELDS
PaymentSession.updateSessionFromForm('card');
}
Pasul 7: Creați plata utilizând sesiunea
Trimiteți tranzacția de plată (sau altă operațiune asociată) de pe serverul dvs. la gateway folosind ID-ul sesiunii (session.id) în solicitare:
- Trimiteți solicitarea Retrieve Session pentru a verifica detaliile incluse în sesiune.
- Creați solicitarea de tranzacție adăugând orice câmpuri necesare care nu sunt incluse în sesiune.
- Trimiteți solicitarea de tranzacție.
Puteți trimite mai multe operațiuni legate de plată folosind aceeași sesiune. De exemplu, puteți iniția o plată cu o operațiune PAY și puteți stoca un simbol reprezentând detaliile plății (pentru a fi utilizat în tranzacții viitoare) cu operațiunea Create or Update Token.
Exemplu de cod al paginii de plată
Următorul exemplu de cod ilustrează codul HTML pentru o pagină de plată completă.
<html>
<head>
// INCLUDE SESSION.JS JAVASCRIPT LIBRARY
<script src="https://egenius.unicredit.ro/form/version/<version>/merchant/<merchant_ID>/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>
Funcții callback pentru pagina de plată
Hosted Session vă permite să utilizați diverse callback-uri pentru a personaliza modul în care se comportă pagina de plată și ce fel de feedback oferă plătitorului.
Funcții callback pentru configurarea sesiunii
Această secțiune definește callback-urile de configurare a sesiunii și răspunsurile returnate de callback-urile pentru rezultate. Pentru un exemplu despre cum să gestionați callback-urile în codul paginii dvs. de plată, consultați Exemplu de cod al paginii de plată.
Callback-urile utilizate în funcția PaymentSession.configure():
- Funcția callback initialized(result) este invocată atunci când câmpurile găzduite sunt atașate la pagina de plată:
- Dacă result.status=="ok", câmpurile găzduite sunt atașate cu succes la pagina dvs. de plată.
- Dacă result.status=="system_error" sau result.status=="request_timeout", a apărut o eroare la atașarea câmpurilor găzduite. Reîncercați după un scurt timp.
Exemplu de răspuns de inițializare reușită// An ok response { "status":"ok", }Exemplu de răspuns la inițializare nereușită// 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." } - Funcția callback formSessionUpdate(result) este invocată atunci când conținutul câmpului găzduit este stocat în sesiune:
- Dacă result.status=="ok", sesiunea conține acum detaliile de plată colectate.
Exemplu de actualizare a formularului de sesiune pentru un răspuns reușit// 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" } - Dacă result.status=="fields_in_error", introducerea plătitorului este nevalidă. Solicitați plătitorului să își actualizeze datele introduse. Structura răspunsului errors conține informații despre câmpurile nevalide.
- 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ă un scurt timp.
// An error response (fields_in_error)
{
"status": "fields_in_error",
"session": {
"id": "SESSION000218450948092491657986"
},
"errors": {
"cardNumber": "invalid",
"securityCode": "invalid"
},
version: "43"
}
// 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"
}
Funcțiile callback pentru câmpurile 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. Evenimentele vă permit să urmăriți ceea ce face plătitorul și să le oferiți feedback de validare în timpul diferitelor etape de interacțiune cu plata.
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. Odată ce plătitorul a terminat de tastat și a părăsit câmpul, și acest eveniment se declanșează, invocați funcția validate() și afișați orice erori pentru câmp din callback-ul funcției validate().
- 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.
- onValidityChange(): Invocat după fiecare apăsare de tastă a plătitorului, oferind feedback cu privire la validitatea datelor introduse de plătitor până acum.
/**
* 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", "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";
}
});
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
});
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";
}
});
Î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, utilizați mai întâi operațiunea PAYMENT OPTIONS INQUIRY pentru a obține o listă a tipurilor de carduri acceptate. Apoi inspectați informațiile despre tipul cardului (sourceOfFunds.provided.card.brand și sourceOfFunds.provided.card.scheme) în răspunsul PaymentSession.updateSessionFromForm('card'), validați-le în raport cu lista de tipuri de carduri acceptate și afișați un mesaj de eroare dacă tipul de card nu este acceptat.
Cum știu dacă CSC-ul sau CVV-ul plătitorului este necesar și a fost furnizat?
Pentru a afla dacă este necesar CSC sau CVV, utilizați operațiunea PAYMENT OPTIONS INQUIRY. Dacă plătitorul nu furnizează CSC/CVV, câmpul securityCode NU este returnat în răspunsul PaymentSession.updateSessionFromForm('card'). Dacă aveți nevoie de codul CSC/CVV și nu este prezentă nicio valoare, trebuie să afișați o eroare plătitorului.
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 modificați valoarea unui câmp găzduit.
- iOS9 în iPhone 6+: Evenimentele onChange() și onBlur() nu sunt declanșate 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.