- Ghid de integrare
- Caracteristici acceptate (Securitate)
- Autentificarea 3-D Secure
Autentificarea 3-D Secure
Autentificarea 3-Domain Secure™ (3-D Secure sau 3DS) este concepută pentru a proteja achizițiile online împotriva fraudei cu carduri de credit, permițându-vă să autentificați plătitorul înainte de a trimite o tranzacție de tip Authorization sau Pay. Autentificarea 3DS funcționează prin redirecționarea plătitorului către emitentul cardului, unde introduce o parolă înregistrată anterior.
QNB ALAHLI acceptă autentificarea 3DS prin Mastercard SecureCode™, Verified by Visa™, J/Secure™, American Express SafeKey™ și Diners Club ProtectBuy™.
Cerințe preliminare
- Trebuie să fiți înregistrat la achizitorul dvs. pentru a utiliza 3DS.
- Trebuie să aveți activată o schemă 3DS în profilul dvs. de comerciant din QNB ALAHLI.
Experiența plătitorului 3DS
Această secțiune descrie un exemplu de proces de validare pentru site-ul magazinului dvs., unde plătitorul este autentificat folosind 3DS.
Procesul de validare pentru o autentificare cu succes este următorul:
- Un plătitor navighează pe site-ul magazinului dvs., selectează unul sau mai multe produse, continuă către pagina de plată și selectează ca metodă de plată un card care acceptă 3DS.
- Verificați înscrierea 3DS: Solicitați QNB ALAHLI să consulte cu schema cardului pentru a afla dacă respectivul card este înscris la 3DS
- Autentificare plătitor: După confirmarea înscrierii cardului, redirecționați browserul plătitorului către pagina de autentificare 3DS a emitentului cardului. Plătitorul introduce parola 3DS și trimite informația. Emitentul returnează rezultatul autentificării către dvs.
- Procesare rezultat ACS: Solicitați QNB ALAHLI să proceseze rezultatul autentificării. QNB ALAHLI vă furnizează detaliile răspunsului de autentificare primit de la emitent.
- Utilizare rezultat 3DS într-o operațiune de plată: Trimiteți plata pentru procesare
- Afișați pentru plătitor pagina de confirmare a comenzii.
Integrare pentru a utiliza autentificarea 3DS
Această secțiune descrie modul de integrare cu QNB ALAHLI pentru utilizarea 3DS.
Puteți să verificați dacă un card este înscris, furnizând următoarele câmpuri în solicitarea Check 3DS Enrollment:
3DSecureId: identificatorul dvs. unic pentru această autentificare. Va trebui să includeți acest identificator, identic, în toate operațiunile ulterioare.3DSecure.authenticationRedirect.responseUrl: adresa URL către care doriți să redirecționați plătitorul după finalizarea procesului de autentificare 3DSorder.amount: valoarea totală a comenziiorder.currency: moneda comenziisourceOfFunds.provided.cardsausession.idsausourceOfFunds.token: Detaliile cardului utilizat pentru plată- (Opțional)
3DSecure.goodsDescription:puteți furniza o scurtă descriere a bunurilor achiziționate. Dacă opțiunea este acceptată de serverul emitentului de control al accesului (ACS), această descriere va fi afișată pe pagina de autentificare prezentată plătitorului.
QNB ALAHLI furnizează rezultatele verificării înscrierii în răspuns:
3DSecure.xid: Un identificator unic al tranzacției generat de QNB ALAHLI pentru autentificarea 3DS.3DSecure.summaryStatus: un răspuns rezumat care indică starea generală de înscriere a carduluiresponse.3DSecure.gatewayCode: un răspuns detaliat care descrie starea de înscriere a cardului
Trebuie să consultați 3DSecure.summaryStatus pentru a stabili care este următorul pas pe care să îl întreprindeți. Acest lucru este rezumat în tabelul de mai jos:
| 3DSecure.summaryStatus | Pasul următor |
|---|---|
| CARD_ENROLLED | Cardul este înscris la 3DS. Continuați cu autentificarea plătitorului. |
| CARD_NOT_ENROLLED | Cardul nu este înscris la 3DS. Continuați cu operațiunea de plată, incluzând 3DSecureID în solicitare. |
| CARD_DOES_NOT_SUPPORT_3DS | Cardul nu acceptă 3DS și nu puteți continua autentificarea 3DS. |
| AUTHENTICATION_NOT_AVAILABLE | A apărut o eroare. Continuați cu operațiunea de plată, incluzând 3DSecureID în solicitare |
Dacă, cardul este înscris (response.3DSecure.gatewayCode = CARD_ENROLLED), atunci trebuie să redirecționați browserul plătitorului către site-ul web al emitentului cardului pentru autentificare. Aceasta se realizează returnând conținutul furnizat în 3DSecure.authenticationRedirect.simple.htmlBodyContent către browserul plătitorului.
Când procesul de autentificare la site-ul web al emitentului cardului este finalizat, serverul de control al accesului (ACS) al emitentului returnează către dvs. răspunsul de autentificare sub forma unei operațiuni post HTTP către adresa URL de răspuns (3DSecure.authenticationRedirect.responseUrl) specificată de dvs. în solicitarea de verificare a înscrierii 3DS.
Răspunsul de autentificare pentru plată (PARes), care vă este returnat, este furnizat ca valoare codificată base64. Pentru a decodifica această valoare, transferați răspunsul PARes în câmpul 3DSecure.paRes din operațiunea Process ACS Result și trimiteți operațiunea. QNB ALAHLI furnizează rezultatele autentificării în răspuns:
3DSecure.summaryStatus: Un răspuns rezumat care indică starea generală de autentificareresponse.3DSecure.gatewayCode: Un răspuns detaliat care descrie starea de autentificare
Trebuie să consultați response.3DSecure.summaryStatus pentru a stabili care este următorul pas pe care să îl întreprindeți. Acest lucru este rezumat în tabelul de mai jos:
| 3DSecure.summaryStatus | Pasul următor |
|---|---|
| AUTHENTICATION_SUCCESSFUL | Autentificarea plătitorului a avut succes. Continuați cu operațiunea de plată, incluzând 3DSecureID în solicitare. |
| AUTHENTICATION_FAILED | Autentificarea plătitorului a eșuat. Trebuie să nu continuați cu operațiunea de plată. Este contrar regulilor schemei să continuați. |
| AUTHENTICATION_ATTEMPTED | A fost încercată autentificarea plătitorului, dar nu a putut fi finalizată. Continuați cu operațiunea de plată, incluzând 3DSecureID în solicitare. |
| AUTHENTICATION_NOT_AVAILABLE | A apărut o eroare. Continuați cu operațiunea de plată, incluzând 3DSecureID în solicitare |
Dacă rezultatul operațiunii Check 3DS Enrollment sau Process ACS indică faptul că puteți continua plata, puteți să inițiați o operațiune Authorize sau Pay. Includeți în solicitare codul 3DSecureId furnizat în operațiunea Check 3DS Enrollment. Nu este necesar să includeți niciunul dintre parametri din grupul de parametri 3DSecure, deoarece QNB ALAHLIva utiliza valoarea 3DSecureId pentru a căuta rezultatele autentificării pe care le-a salvat în momentul în care ați solicitat procesarea rezultatului autentificării. QNB ALAHLI va transmite achizitorului informațiile necesare.
Alte opțiuni
Înainte de a verifica înscrierea la 3DS, puteți trimite o solicitare de cotație de schimb pentru conversie valutară dinamică (DCC) pentru a afla moneda plătitorului și valoarea comenzii în acea monedă. Dacă plătitorul acceptă oferta DCC, trebuie să includeți informațiile DCC în solicitarea Check 3DS Enrollment.
Codul HTML necesar pentru formularul utilizat pentru redirecționarea plătitorului pentru autentificare poate fi generat utilizând una dintre următoarele două metode de generare a paginii:
Simple: QNB ALAHLI generează formularul HTML. Formularul completat este returnat în cadrul răspunsului Check 3DS Enrollment. Aceasta este opțiunea implicită.Customized: Dvs. generați un formular HTML propriu, particularizat, utilizând parametrii furnizați în răspunsul Check 3DS Enrollment.
Răspunsul la operațiunea Check 3DS Enrollment va include informațiile necesare pentru opțiunea selectată.
(Opțional) Personalizați formularul simplu
Puteți să modificați formularul simplu generat prin setarea 3DSecure.authenticationRedirect.pageGenerationMode = SIMPLE în solicitarea Check 3DS Enrollment, specificând apoi valori pentru unul sau mai mulți parametri:
3DSecure.authenticationRedirect.simple.expectedHtmlEncoding3DSecure.authenticationRedirect.simple.redirectDisplayBackgroundColor3DSecure.authenticationRedirect.simple.redirectDisplayContinueButtonText3DSecure.authenticationRedirect.simple.redirectDisplayTitle
(Opțional) Generați propriul formular personalizat
Puteți să specificați faptul că veți genera propriul dvs. formular setând 3DSecure.authenticationRedirect.pageGenerationMode = CUSTOMIZED în solicitarea Check 3DS Enrollment. Răspunsul va include următorii parametri:
3DSecure.authenticationRedirect.customized.acsUrl: Adresa URL a serverului de control al accesului (ACS) al emitentului unde plătitorul poate fi autentificat.3DSecure.authenticationRedirect.customized.paReq: Mesajul Solicitare autentificare plătitor (PAReq) ce va fi trimis către ACS pentru a iniția autentificarea plătitorului.
Includeți aceste valori în formularul dvs., împreună cu adresa URL la care să fie returnat plătitorul după finalizarea autentificării.
Un exemplu de formular personalizat este prezentat mai jos.
<!-- Populate the form action attribute with the value returned in the 3DSecure.authenticationRedirect.customized.acsUrl response parameter -->
<form name="3dsRedirect" action="[3DSecure.authenticationRedirect.customized.acsUrl]" method="POST" accept-charset="UTF-8">
<!-- Populate the mandatory PaReq parameter with the value returned in the 3DSecure.authenticationRedirect.customized.paReq response parameter. -->
<input type="hidden" name="PaReq" value="[3DSecure.authenticationRedirect.customized.paReq]"/>
<!-- Populate the mandatory TermUrl value with the URL to which you want the payer returned when the authentication process has completed. This should be the same value as supplied in the 3DSecure.authenticationRedirect.responseUrl parameter to the CHECK_ENROLLMENT request. -->
<input type="hidden" name="TermUrl" value="https://merchant.com/3ds/return"/>
<!-- The ACS will echo the contents of the mandatory MD parameter when the payer is returned to the URL specified in the TermUrl parameter. You can use this parameter to establish a link between the ACS request and response. -->
<input type="hidden" name="MD" value="[mdvalue]"/>
<input type="submit" value="Click here to continue" class="button">
</form>
Referință API personalizare formular la Check 3DS Enrollment[REST] [NVP]
Dacă ați utilizat un MPI 3DS extern pentru a autentifica plătitorul, trebuie să furnizați informațiile referitoare la autentificare în grupul de parametri 3DSecure pentru operațiunea Pay sau Authorize.
Există un câmp obligatoriu:
3DSecure.enrollmentStatus: indică faptul că posesorul de card este înscris la 3DS. Acest câmp este obligatoriu.
Celelalte câmpuri sunt opționale, deoarece starea de autentificare a tranzacției indică dacă acestea v-au fost sau nu furnizate de către MPI 3DS extern.
3DSecure.authenticationStatus:indică dacă autentificarea 3DS a plătitorului a avut succes.3DSecure.authenticationToken: Valoarea codificată base64 generată de emitentul cardului care vă poate fi returnată în mesajul de răspuns de autentificare.3DSecure.acsEci: Indicatorul de comerț electronic (ECI) care vă poate fi returnat în mesajul de răspuns de autentificare.3DSecure.xid: un identificator unic de tranzacție pentru autentificarea 3DS.
3DSecure.summaryStatus = AUTHENTICATION_ATTEMPTED, să furnizați 3DSecure.authenticationToken.Referință API 3DS pre-autentificat la autorizare [REST] [NVP]
Dacă doriți să recuperați rezultatele autentificării, în orice moment, utilizați operațiunea Retrieve 3DS Result.
Întrebări frecvente
QNB ALAHLI furnizează un rezumat al stării de autentificare în câmpul response.3DSecure.gatewayCode. Dacă doriți să extrageți valorile câmpurilor 3DS utilizate pentru procesarea unei plăți, puteți să realizați aceasta operațiune din câmpul response.3DSecure.gatewayCode.
| response.3DSecure.gatewayCode | 3DSecure.enrollmentStatus | 3DSecure.authenticationStatus | Trimitere operațiune de plată |
|---|---|---|---|
| CARD_ENROLLED | ENROLLED | - | (Continuați cu autentificarea) |
| NOT_ENROLLED_NO_ERROR_DETAILS | NOT_ENROLLED | - | Da |
| NOT_ENROLLED_ERROR_DETAILS_PROVIDED | NOT_ENROLLED | - | Da |
| ENROLLMENT_STATUS_UNDETERMINED_NO_ERROR_DETAILS | ENROLLMENT_STATUS_UNDETERMINED | - | Da |
| ENROLLMENT_STATUS_UNDETERMINED_ERROR_DETAILS_PROVIDED | ENROLLMENT_STATUS_UNDETERMINED | - | Da |
| AUTHENTICATION_SUCCESSFUL | ENROLLED | AUTHENTICATION_SUCCESSFUL | Da |
| AUTHENTICATION_ATTEMPTED | ENROLLED | AUTHENTICATION_ATTEMPTED | Da |
| AUTHENTICATION_NOT_AVAILABLE_NO_ERROR_DETAILS | ENROLLED | AUTHENTICATION_NOT_AVAILABLE | Da |
| AUTHENTICATION_NOT_AVAILABLE_ERROR_DETAILS_PROVIDED | ENROLLED | AUTHENTICATION_NOT_AVAILABLE | Da |
| AUTHENTICATION_FAILED | ENROLLED | AUTHENTICATION_FAILED | Nu (nu este permis) |
| MPI_PROCESSING_ERROR | ENROLLED | - | Da |
| ACS_SESSION_TIMEOUT | ENROLLED | - | Da |
| ERROR_PARSING_AUTHENTICATION_RESPONSE | ENROLLED | - | Nu (eșuat) |
| INVALID_SIGNATURE_ON_AUTHENTICATION_RESPONSE | ENROLLED | - | Nu (eșuat) |
| CARD_DOES_NOT_SUPPORT_3DS | - | - | Nu (eșuat) |
| ERROR_PARSING_CHECK_ENROLLMENT_REQUEST | - | - | Nu (eșuat) |
| INVALID_DIRECTORY_SERVER_CREDENTIALS | - | - | Da (fără date 3DS) |
| ERROR_PARSING_CHECK_ENROLLMENT_RESPONSE | - | - | Da (fără date 3DS) |
| ERROR_COMMUNICATING_WITH_DIRECTORY_SERVER | - | - | Da (fără date 3DS) |
Dacă este necesar, puteți extrage valoarea VERes.enrolled din 3DSecure.enrollmentStatus:
| VERes.enrolled | 3DSecure.enrollmentStatus |
|---|---|
| Da | ENROLLED |
| Nu | NOT_ENROLLED |
| U | ENROLLMENT_STATUS_UNDETERMINED |
Puteți, de asemenea, extrage valoarea PAREs.status din 3DSecure.authenticationStatus:
| PARes.status | 3DSecure.authenticationStatus |
|---|---|
| Da | AUTHENTICATION_SUCCESSFUL |
| Nu | AUTHENTICATION_FAILED |
| U | AUTHENTICATION_NOT_AVAILABLE |
| A | AUTHENTICATION_ATTEMPTED |
Dacă ați furnizat detalii 3DS pentru o tranzacție, căutați comanda sau tranzacția în Merchant Administration. Vizualizați detaliile comenzii, apoi selectați legătura pentru a vizualiza detaliile de autentificare.
Dacă doriți să vizualizați detaliile de autentificare pentru o autentificare pentru care nu ați continuat cu plata (de exemplu, autentificarea a eșuat), atunci utilizați opțiunea de căutare Autentificare plată în Merchant Administration.
Codul de stare autentificare afișat la vizualizarea detaliilor de autentificare în Merchant Administration poate fi asociat cu response.3DSecure.gatewayCode. Consultați Codurile noi în tabelul de mai jos:
| Client de plată/Client virtual de plată | <<webServicesIntegration>> | |
|---|---|---|
| Coduri noi | Coduri vechi | response.3DSecure.gatewayCode |
| E | E | NOT_ENROLLED_NO_ERROR_DETAILS |
| Z | NOT_ENROLLED_ERROR_DETAILS_PROVIDED |
|
| C | C | CARD_DOES_NOT_SUPPORT_3DS |
| B | U | ENROLLMENT_STATUS_UNDETERMINED_NO_ERROR_DETAILS |
| V | ENROLLMENT_STATUS_UNDETERMINED_ERROR_DETAILS_PROVIDED |
|
| F | F | ERROR_PARSING_CHECK_ENROLLMENT_REQUEST |
| A | A | INVALID_DIRECTORY_SERVER_CREDENTIALS |
| M | U | ERROR_PARSING_CHECK_ENROLLMENT_RESPONSE |
| D | D | ERROR_COMMUNICATING_WITH_DIRECTORY_SERVER |
| I | I | MPI_PROCESSING_ERROR |
| P | P | ERROR_PARSING_AUTHENTICATION_RESPONSE |
| S | S | INVALID_SIGNATURE_ON_AUTHENTICATION_RESPONSE |
| T | T | ACS_SESSION_TIMEOUT |
| X | U | AUTHENTICATION_NOT_AVAILABLE_NO_ERROR_DETAILS |
| U | AUTHENTICATION_NOT_AVAILABLE_ERROR_DETAILS_PROVIDED |
|
| Da | Da | AUTHENTICATION_SUCCESSFUL |
| Nu | Nu | AUTHENTICATION_FAILED |
| M | M | AUTHENTICATION_ATTEMPTED |
| R | CARD_ENROLLED |
|
Vă puteți testa integrarea pentru realizarea autentificării 3DS prin intermediul QNB ALAHLI utilizând emulatorul ACS. Acesta vă permite să selectați un anumit rezultat de autentificare 3DS (returnat în răspunsul de tranzacție în câmpul 3DSecure.authenticationStatus).
Testarea este acceptată pentru următoarele scheme de autentificare 3-D Secure:
- Mastercard SecureCode
- Verified by Visa
- American Express SafeKey
- J/Secure
- Diners ProtectBuy
Pentru a testa funcția de Autentificare 3-D Secure:
- Utilizați un card de testare înscris la 3-D Secure (consultați cardurile listate în secțiunile specifice achizitorilor) pentru trimiterea solicitării
CHECK_3DS_ENROLLMENTpentru profilul dvs. de comerciant utilizat pentru testare. - Verificați dacă primiți un răspuns cu
response.3DSecure.gatewayCode=CARD_ENROLLED. - Utilizați formularul furnizat în
3DSecure.authenticationRedirect.simple.htmlBodyContentpentru a redirecționa browserul plătitorului către pagina Emulatorului ACS.Emulatorul ACS redirecționează browserul plătitorului înapoi către site-ul dvs. web și conține PARes.
- Trimiteți o solicitare
PROCESS_ACS_RESULTcu PARes în3DSecure.paRes. - Utilizați valoarea ID pentru această autentificare 3-D Secure prin intermediul QNB ALAHLI, furnizat în
3DSecureIdîntr-o solicitare de tranzacție ulterioară (de ex.PAYsauAUTHORIZE).