Implementarea integrării 3DS cu ajutorul API de autentificare

Puteți iniția autentificarea completând următoarele câmpuri în solicitarea Initiate Authentication:

Gateway-ul returnează următoarele câmpuri-cheie în răspunsul la operațiunea Initiate Authentication:

• authentication.version: Dacă autentificarea 3DS a plătitorului este disponibilă, acest câmp afișează tipul 3DS1 sau 3DS2. Dacă ambele sunt disponibile, va fi returnat tipul 3DS2.
• authentication.3ds2.methodSupported: Dacă versiunea 3DS2 este disponibilă, iar ACS-ul emitentului acceptă apelurile de metodă, câmpul are valoarea SUPPORTED. Apelul de metodă poate fi utilizat de ACS pentru a colecta data suplimentare înainte de solicitarea de autentificare, pentru a mări probabilitatea ca autentificarea fluidizată să fie disponibilă. Apelul de metodă este declanșat într-un cadru iFrame ascuns, respectiv invizibil pentru plătitor. De asemenea, acesta nu declanșează funcția callback după finalizare.
• transaction.authenticationStatus: Consultați acest câmp dacă doriți mai multe detalii despre starea de autentificare.
• response.gatewayRecommendation: Acest câmp vă permite să stabiliți pasul următor. Rețineți că această recomandare se bazează numai pe regulile 3DS de filtrare a tranzacțiilor, configurate de către dvs. sau your payment service provider.
  
  

  response.gatewayRecommendation	Pasul următor
  DO_NOT_PROCEED	Nu continuați autentificarea 3DS a cardului, dar poate doriți să continuați plata fără datele 3DS. De asemenea, puteți oferi plătitorului opțiunea de a încerca o altă metodă de plată.
  PROCEED	Puteți continua cu autentificarea plătitorului folosind operațiunea Authenticate Payer.

• authentication.redirectHtml: Introduceți conținutul acestui câmp pe pagina afișată plătitorului. În acest scop, adăugați conținutul text într-un element DIV ascuns și specificați identificatorul scriptului în DOM HTML. Acest lucru va determina crearea și postarea automată a formularului. De exemplu,

  div.innerHtml= response.authentication.redirectHtml;
   
  eval(document.getElementById('initiate-authentication-script').text)
  	

  Dacă gateway-ul recomandă să nu continuați, atunci introducerea conținutului acestui câmp pe pagina dvs. web nu va executa nicio funcție.

Trimiteți această operațiune completând următoarele câmpuri.  Dacă se acceptă doar 3DS1, gateway-ul ignoră câmpurile specifice pentru 3DS2. 

Gateway-ul returnează următoarele câmpuri-cheie în răspunsul la operațiunea Authenticate Payer:

• transaction.authenticationStatus: Consultați acest câmp dacă doriți mai multe detalii despre starea de autentificare.
• response.gatewayRecommendation: Acest câmp vă permite să determinați dacă ar trebui să continuați la o tranzacție financiară sau nu. Această recomandare se bazează numai pe regulile 3DS de filtrare a tranzacțiilor, configurate de către dvs. sau your payment service provider.
  
  

  response.gatewayRecommendation	Pasul următor
  DO_NOT_PROCEED	Nu continuați cu acest card deoarece autentificarea este respinsă sau indisponibilă, dar poate doriți să continuați plata fără datele 3DS. De asemenea, puteți oferi plătitorului opțiunea de a încerca o altă metodă de plată.
  PROCEED	Puteți continua cu finalizarea procesului de autentificare (procesul de testare) sau puteți finaliza plata (proces optimizat).

• authentication.redirectHtml: Introduceți conținutul acestui câmp pe pagina afișată plătitorului. În acest scop, adăugați conținutul text într-un element DIV și specificați identificatorul scriptului în DOM HTML. Acest lucru va determina crearea și postarea automată a formularului. De exemplu,

  div.innerHtml= response.authentication.redirectHtml;
   
  eval(document.getElementById('authenticate-payer-script').text)
  	

  Dacă gateway-ul recomandă să nu continuați, atunci introducerea conținutului acestui câmp pe pagina dvs. web nu va executa nicio funcție.

Procesul fluidizat

Acest lucru va redirecționa browserul plătitorului înapoi la site-ul dvs. web. Puteți continua cu trimiterea unei tranzacții ulterioare către gateway. Gateway-ul va obține datele de autentificare asociate plății și se va asigura că plățile vor fi procesate numai dacă toate regulile 3DS de filtrare a tranzacțiilor (configurate de dvs. sau your payment service provider) sunt respectate.

Procesul de testare

Acesta redirecționează browserul plătitorului către ACS, unde va apărea IU de testare a emitentului, după care plătitorul va fi redirecționat înapoi la site-ul dvs. web. Următoarele câmpuri sunt returnate în callback odată ce browserul plătitorului revine la site-ul dvs web.

• order.id
• transaction.id
• response.gatewayRecommendation
• result

Puteți determina rezultatul autentificării folosind valoarea returnată în câmpul response.gatewayRecommendation. Această recomandare se bazează numai pe regulile 3DS de filtrare a tranzacțiilor, configurate de către dvs. sau your payment service provider.

Dacă doriți date suplimentare în răspuns, puteți utiliza operațiunea Retrieve Transaction.

Dacă doriți să apelați rezultatele autentificării în orice moment, utilizați operațiunea Retrieve Transaction. Rețineți că acele câmpuri care sunt utilizate numai în timpul autentificării, cum ar fi authentication.redirectHtml, nu rămân pe gateway și, prin urmare, nu vor fi returnate.

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 de autentificare pentru operațiunea Authorize sau Pay.

Toate câmpurile sunt opționale, deoarece, dacă v-au fost sau nu furnizate de către MPI 3DS extern depinde de versiunea de autentificare a tranzacției (3DS1 sau 3DS2) și de starea tranzacției. Dacă, însă, dispuneți de aceste date, este recomandat să le furnizați.

• authentication.3ds.acsEci: Indicatorul de comerț electronic care vă poate fi returnat în mesajul de răspuns de autentificare.
• authentication.3ds.authenticationToken: Valoarea codificată base64 generată de emitentul cardului care vă poate fi returnată în mesajul de răspuns de autentificare.
• authentication.3ds.transactionId: Un identificator unic al tranzacției, generat de gateway pentru autentificarea 3DS.
  Pentru 3DS1, acest câmp corespunde XID, care este un identificator generat de gateway în numele comerciantului. Un XID trimis în acest câmp trebuie să aibă formatul base64.
  Pentru 3DS2, acest câmp corespunde cu identificatorul alocat de serverul de directoare al schemei.
• authentication.3ds1.paResStatus: Indică rezultatul autentificării plătitorului la emitent.
• authentication.3ds1.veResEnrolled: Indică dacă autentificarea plătitorului este disponibilă sau nu pentru numărul de card furnizat.
• authentication.3ds2.protocolVersion: Versiunea protocolului EMV 3-D Secure utilizat pentru autentificarea 3-D Secure, în formatul specificat de EMVCo. De exemplu, 2.1.0
• authentication.3ds2.transactionStatus: Indică rezultatul autentificării plătitorului la emitent.
• authentication.3ds2.statusReasonCode: Un cod care indică motivul pentru starea tranzacției, returnată în authentication.3ds2.transactionStatus. Acesta trebuie furnizat atunci când authentication.3ds2.transactionStatus returnează N, U sau R.

Dacă doriți să efectuați autentificarea doar pentru a verifica identitatea plătitorului, fără procesarea unei plăți, trebuie să indicați scopul autentificării în solicitarea Initiate Authentication. De exemplu, doriți să autentificați plătitorul după ce acesta introduce detaliile cardului pentru o utilizare ulterioară, în timpul sesiunii de înregistrare a clientului sau de creare a contului pe site-ul dvs. web. Abilitatea de a finaliza procesul de autentificare într-un mediu fără plată îmbunătățește experiența plătitorului și reduce frecvența renunțărilor din partea plătitorilor.

Pentru a efectua o autentificare fără plată, trebuie să completați următoarele câmpuri în solicitarea Initiate Authentication:

• order.currency: Toate monedele acceptate de linkul sau linkurile de achizitor.
• authentication.purpose: Indică contextul în care este solicitată autentificarea plătitorului. Puteți specifica unul dintre următoarele elemente:
  • ADD_CARD: Autentificarea efectuată înainte de stocarea cardului unui plătitor fie direct de către dvs., fie prin utilizarea funcției de creare de simbol de pe gateway. O plată nu este procesată.
  • MAINTAIN_CARD: Autentificarea efectuată înainte de actualizarea detaliilor cardului unui plătitor, stocate fie direct de către dvs., fie prin utilizarea funcției de creare de simbol de pe gateway. O plată nu este procesată.

  Dacă schema de autentificare nu acceptă scopul solicitat, gateway-ul returnează AUTHENTICATION_NOT_SUPPORTED drept răspuns. Rețineți că gateway-ul setează implicit acest câmp la PAYMENT_TRANSACTION pentru a permite autentificarea care va fi utilizată pentru o tranzacție de plată.

Dacă ați utilizat o sesiune de plată (ID sesiune) pentru a stoca detaliile de autentificare, solicitarea POST trimisă de browserul plătitorului către site-ul dvs. web la finalizarea solicitării Authenticate Payer va fi parametrizată într-un mod care să permită determinarea rezultatului autentificării. Fiecare parametru de autentificare, cum ar fi authentication.3ds2.transactionStatus.data, poate fi util pentru o integrare avansată sau dacă este necesar să furnizați datele de autentificare într-o plată procesată printr-un alt gateway. În acest scop, puteți trimite solicitarea Retrieve Transaction sau puteți alege să decriptați datele de autentificare criptate (a se vedea pașii de mai jos):

1. Creați o sesiune utilizând operațiunea Create Session.
2. Adăugați date relevante la ID-ul sesiunii (returnat în răspunsul Create Session) utilizând solicitarea Update Session.
3. Utilizați acest ID de sesiune în solicitările Initiate Authentication și Authenticate Payer.
4. Redirecționarea browserului plătitorului către site-ul dvs. web va conține detaliile Authenticate Payer în câmpul encryptedData. Acesta este un obiect JSON criptat conținând datele de autentificare obținute în timpul procesului de autentificare. Acesta conține următoarele câmpuri:
   • encryptedData.ciphertext
   • authentication.3ds.acsEci
   • authentication.3ds.authenticationToken
   • authentication.3ds.transactionId
   • authentication.3ds1.veResEnrolled
   • authentication.3ds1.paResStatus
   • authentication.3ds2.transactionStatus
   • authentication.3ds2.dsTransactionId
   • transaction.authenticationStatus
   • authentication.3ds2.statusReasonCode
   • sourceOfFunds.provided.card.number
   • sourceOfFunds.provided.card.expiry.month
   • sourceOfFunds.provided.card.expiry.year
   • sourceOfFunds.token
   • order.id
   • transaction.id
   • encryptedData.nonce
   • encryptedData.tag
5. Pentru a decripta conținutul returnat în câmpul encryptedData.ciphertext, utilizați session.aes256Key (returnat în răspunsul Create Session) în modul GCM. Cheia codată Base64 este secretă și trebuie să fie cunoscută numai de dvs.

public final class SessionDataDecrypter {
    /**
     * The algorithm used for encryption/decryption
     */
    private static final String SYMMETRIC_ALGORITHM = "AES/GCM/NoPadding";
  
    /**
     * The algorithm to be associated with the secret key material
     */
    private static final String SYMMETRIC_KEY_TYPE = "AES";
  
    /**
     * The secret key associated with the session, as returned in the session.aes256Key in a Create Session response.
     */
    private final byte[] key;
  
    /**
     * Constructs a new object with the given key. The key is Base64 encoded, as returned in the session.aes256Key
     * field in a Create Session response. This key must be kept secret, as it may be used to encrypt, decrypt and
     * authenticate data for that session.
     *
     * @param encodedKey Key to be used for decryption.
     */
    public SessionDataDecrypter(String encodedKey) {
        key = Base64.getDecoder().decode(encodedKey);
    }
  
    /**
     * Performs decryption of the given ciphertext, using the key passed in the constructor and the associated nonce.
     * The tag is used to authenticate the ciphertext.
     *
     * @param ciphertext Encrypted and authenticated session data
     * @param nonce Nonce/Initialization vector associated with the ciphertext
     * @param tag Authentication tag
     * @return The decrypted session data
     * @throws AEADBadTagException if the data cannot be authenticated with the given tag
     * @throws InvalidKeyException if the key cannot be constructed properly. This may indicate that it has not been
     * correctly retrieved from the response field
     * @throws GeneralSecurityException other than {@link AEADBadTagException} and {@link InvalidKeyException}, should
     * not be thrown in a correctly set up environment
     */
    public String decrypt(String ciphertext, String nonce, String tag)
            throws GeneralSecurityException {
        Key keySpec = new SecretKeySpec(key, SYMMETRIC_KEY_TYPE);
  
        // The Java crypto classes expect the ciphertext and tag to be a single input, so they need to be concatenated
        byte[] encryptedBytes = Base64.getDecoder().decode(ciphertext);
        byte[] tagBytes = Base64.getDecoder().decode(tag);
        byte[] input = new byte[encryptedBytes.length + tagBytes.length];
        System.arraycopy(encryptedBytes, 0, input, 0, encryptedBytes.length);
        System.arraycopy(tagBytes, 0, input, encryptedBytes.length, tagBytes.length);
  
        // Configure the cipher with AES, using GCM parameter specifying the nonce/initialization vector
        byte[] iv = Base64.getDecoder().decode(nonce);
        GCMParameterSpec parameterSpec = new GCMParameterSpec(tagBytes.length * Byte.SIZE, iv);
        final Cipher decrypter = Cipher.getInstance(SYMMETRIC_ALGORITHM);
        decrypter.init(Cipher.DECRYPT_MODE, keySpec, parameterSpec);
  
        // Perform the decryption and return the value.
        byte[] decryptedBytes = decrypter.doFinal(input);
        return new String(decryptedBytes, StandardCharsets.UTF_8);
    }
}
	

Comercianții agregatori pot activa utilizarea API-ului de autentificare pe gateway de către sub-comercianții lor. Nu este necesar ca sub-comercianții să aibă o relație contractuală cu achizitorul sau gateway-ul. Comerciantul agregator poate trimite detaliile sub-comercianților necesare pentru inițierea autentificării prin operațiunea Initiate Authentication. Pentru mai multe informații, consultați secțiunea Asistența pentru agregatori.

Puteți utiliza API-ul de autentificare ca API pe partea serverului sau pe partea clientului.

• API pe partea clientului: Trebuie să stabiliți mai întâi un canal de autentificare prin care serverul comerciantului trebuie să comunice cu serverul gateway-ului pentru crearea sesiunii pe gateway. Odată ce sesiunea este creată, o puteți utiliza pentru a autentifica toate operațiunile API ulterioare necesare pentru gestionarea proceselor de integrare 3DS direct din browser, folosind API-ul JavaScript 3DS sau propria dvs. bibliotecă.
• API pe partea serverului: Trebuie să efectuați toate operațiunile necesare pentru gestionarea proceselor de integrare 3DS direct de la serverul dvs. de comerciant la serverul gateway-ului. Puteți susține toate modurile de tranzacție pentru autentificare prin API-ul de autentificare.
  
  • Numai autentificare: Efectuați operațiunile Initiate Authentication și Authenticate Payer.
  • Autentificarea și tranzacția de plată: Efectuați operațiunile Initiate Authentication, Authenticate Payer și Authorize/Pay.
  • Tranzacția de plată pre-autentificată: Efectuați operațiunea Authorize/Pay folosind detaliile de autentificare de la un furnizor extern.

Puteți utiliza simboluri din rețea pentru autentificarea plătitorului începând cu API v55. În prezent, eGenius Platform acceptă numai procesarea simbolurilor din rețea obținute de la următorii furnizori de servicii de creare de simboluri: Mastercard Digital Enablement Service (MDES), Visa Token Service (VTS).

Dacă ați obținut un simbol în rețea prin integrarea directă în furnizorul de servicii de creare de simboluri, atunci trebuie să furnizați detaliile simbolului folosind următoarele câmpuri:

• sourceOfFunds.type=SCHEME_TOKEN: Permite gateway-ului să identifice sursa fondurilor, introdusă în solicitare sub forma unui simbol din rețea. MDES și VTS sunt acceptate din API v51 și respectiv v53.
• sourceOfFunds.provided.card.number: Simbolul din rețea. Completați valoarea pentru „PAN simbol” în MDES sau „Simbol” în VTS.
• sourceOfFunds.provided.card.expiry: (opțional) Data expirării simbolului din rețea.

Dacă your payment service provider vă permite crearea de simboluri în rețea, orice solicitare pentru un simbol de pe gateway trimisă de comerciant către gateway va determina și încercarea de generare a unui simbol corespunzător în rețea pentru schemele activate, dacă sunt acceptate de emitentul cardului. Gateway-ul va încerca, de asemenea, crearea de simboluri în rețea pentru orice carduri aplicabile deja stocate în depozitul de simboluri de pe gateway. Solicitarea Initiate Authentication va utiliza simbolul din rețea, dacă este disponibil; în caz contrar, va fi utilizat PAN de finanțare (FPAN) stocat în schimbul simbolului de pe gateway. Acest model acceptă momentan doar simboluri MDES.

Puteți utiliza simboluri ale plăților de pe dispozitiv pentru autentificarea plătitorului începând din API v55. Sunt acceptate numai simbolurile de plată obținute din SDK-ul Google Pay. Puteți furniza un simbol de plată criptat sau codul „PAN” obținut dintr-un simbol de plată decriptat pentru autentificarea plătitorului. Gateway-ul acceptă numai solicitările de autentificare care conțin un FPAN; cele care conțin coduri DPAN vor fi respinse. Pentru a furniza detaliile cardului prin simboluri de plată, completați câmpul de mai jos:

• order.walletProvider=GOOGLE_PAY
• sourceOfFunds.provided.card.devicePayment.paymentToken: Se aplică numai dacă simbolul de plată este decriptat de către gateway. Este simbolul criptat al plății obținut din SDK-ul Google Pay.
• sourceOfFunds.provided.card.number: Se aplică numai dacă simbolul de plată este decriptat de către dvs. Valoarea care corespunde cheii JSON „pan” din Google Pay.

Solicitarea Authenticate Payer poate necesita un volum mare de informații despre plătitor și tranzacție. De exemplu, puteți furniza următoarele date în solicitare, utilizând câmpurile din grupul de parametri customer.account, ceea ce va permite ACS-ului emitentului să evalueze nivelul de risc asociat cu activitatea. Acest lucru înseamnă că, în cazul plăților legitime, ACS poate confirma faptul că plătitorul este, cel mai probabil, posesorul real al cardului.

• Plătitorul utilizează un cont existent?
  • customer.account.history.creationDate
• De când există contul respectiv?
  • customer.account.history.lastUpdated
  • customer.account.history.passwordLastChanged
• Care este frecvența cumpărăturilor plătitorului la dvs.?
  • customer.account.history.addCardAttempts
  • customer.account.history.annualActivity
  • customer.account.history.recentActivity
  • customer.account.history.shippingAddressDate
• Plătitorul a mai comandat anterior articolele respective de la dvs.?
  • customer.account.history.issuerAuthentication.acsTransactionId
  • customer.account.history.issuerAuthentication.time
  • customer.account.history.issuerAuthentication.type
• Ați observat activități suspecte (de ex. încercări eșuate de autentificare) în cont?
  • customer.account.history.suspiciousActivity
  • customer.account.authentication.method
  • customer.account.authentication.time

Puteți, de asemenea, să furnizați următoarele câmpuri recomandate pentru fiecare schemă de carduri din solicitarea Authenticate Payer. Rețineți că această listă nu este definitivă și poate fi modificată.

Gateway-ul furnizează starea de autentificare în câmpul transaction.authenticationStatus. Acest câmp poate returna una dintre următoarele valori, în funcție de etapa autentificării:

• AUTHENTICATION_ATTEMPTED: S-a încercat autentificarea plătitorului și a fost obținută o dovadă a tentativei de autentificare.
• AUTHENTICATION_AVAILABLE: Autentificarea plătitorului este disponibilă pentru metoda de plată furnizată.
• AUTHENTICATION_FAILED: Plătitorul nu a fost autentificat. Nu trebuie să continuați tranzacția.
• AUTHENTICATION_NOT_SUPPORTED: Metoda de autentificare solicitată nu este acceptată pentru această metodă de plată.
• AUTHENTICATION_NOT_IN_EFFECT: Nu există informații de autentificare asociate cu această tranzacție.
• AUTHENTICATION_PENDING: Autentificarea plătitorului se află în așteptarea finalizării unui proces de testare.
• AUTHENTICATION_REJECTED: Emitentul a respins solicitarea de autentificare și a solicitat să nu încercați autorizarea unei plăți.
• AUTHENTICATION_REQUIRED: Autentificarea plătitorului este obligatorie pentru plata respectivă, însă nu a fost furnizată.
• AUTHENTICATION_SUCCESSFUL: Plătitorul a fost autentificat cu succes.
• AUTHENTICATION_UNAVAILABLE: Plătitorul nu a putut fi autentificat din cauza unei probleme tehnice sau de altă natură.

Puteți vizualiza detaliile de autentificare atât pentru autentificările individuale, cât și pentru cele care au continuat cu efectuarea plății în Merchant Administration. Căutați comanda sau tranzacția pe pagina de căutare și consultați detaliile autentificării.

Dacă doriți să vedeți detaliile unei autentificări 3DS1, de exemplu, pentru a vedea datele din câmpuri precum PARes, PAReq, utilizați funcția de căutare autentificări din Merchant Administration.

Da, puteți evita autentificarea 3DS pentru plătitori atunci când asiguratorul extern al riscului consideră că plata are un nivel scăzut de risc. Pentru mai multe informații, consultați Dynamic 3DS.

Pentru a testa funcționalitatea 3DS:

1. Utilizați un card de testare (din tabelul de mai jos) atunci când trimiteți solicitarea de inițiere a autentificării pentru profilul dvs. de comerciant de TESTARE.
2. Asigurați-vă că autentificarea este disponibilă (authentication.version=3DS2 or 3DS1)
3. Trimiteți o solicitare Authenticate Payer și inserați conținutul câmpului authentication.redirectHtml pe pagina afișată pentru plătitor, pentru a redirecționa browserul plătitorului către pagina de testare a emulatorului 3DS.
   Emulatorul 3DS redirecționează browserul plătitorului înapoi către site-ul dvs. web odată ce autentificarea este finalizată.
4. Selectați un anumit rezultat al autentificării 3DS din meniul derulant al emulatorului 3DS (a se vedea valorile din tabelul de mai jos).
5. Utilizați ID-ul tranzacției pentru această autentificare 3DS în authentication.transactionId, prin intermediul unei solicitări de Authorize sau Pay ulterioare.

În cazul valorii transStatus „C”, sunt posibile următoarele rezultate, prin selectarea din meniul derulant al emulatorului 3DS: