Implementarea autentificării RuPay cu ajutorul API JavaScript RuPay

Această pagină descrie modul de integrare pe gateway pentru utilizarea autentificării RuPay cu ajutorul API JavaScript (JS) RuPay.

Ghidul de integrare JS RuPay completează ghidul de integrare a API-ului de autentificare RuPay și, ca atare, trebuie utilizat împreună cu acesta.

Pasul 1: Crearea și actualizarea unei sesiuni

JS RuPay utilizează autentificarea pe baza sesiunii. Ca prim pas, trebuie să creați o sesiune, pe care apoi o puteți actualiza cu câmpurile de solicitare și valorile pe care doriți să le stocați în cadrul sesiunii.

Puteți crea o sesiune folosind apelul Create Session. Acesta este un apel în API de pe partea serverului și reprezintă o cerință preliminară pentru integrarea cu API JS. Acesta returnează următoarele câmpuri:

  • session.id: Un identificator de sesiune unic, pe care trebuie să îl furnizați în solicitările ulterioare pentru a face referire la conținutul sesiunii.
  • session.authenticationLimit: Limita introdusă în solicitare sau valoarea implicită a gateway-ului.
  • session.aes256Key: Cheia pe care o puteți utiliza pentru a decripta datele sensibile transmise site-ului dvs. web prin browserul sau dispozitivul mobil al plătitorului.
  • session.version: Puteți utiliza acest câmp pentru a implementa blocarea optimistă a conținutului sesiunii.
  • session.updateStatus: Un rezumat al rezultatului ultimei încercări de modificare a sesiunii.

Referință API Create Session[REST][NVP]

Solicitarea Update Session

Puteți adăuga sau actualiza câmpurile unei sesiuni folosind apelul Update Session. Acesta permite adăugarea datelor plăților și plătitorilor într-o sesiune care poate deveni ulterior un set de date de intrare pentru determinarea riscului asociat cu plătitorul într-o operațiune de autentificare. Într-o sesiune, următoarele câmpuri sunt obligatorii:

Câmpuri obligatorii

  • sourceOfFunds.provided.card.*: Detaliile cardului utilizat pentru plată.
  • order.amount
  • order.currency: Moneda comenzii.
  • transaction.id: Un identificator unic pentru autentificarea plății.
  • order.id: Identificatorul unic al comenzii.
  • authentication.channel=PAYER_BROWSER: Canalul pe care este inițiată solicitarea de autentificare.
  • authentication.purpose=PAYMENT_TRANSACTION: Indică contextul în care este solicitată autentificarea plătitorului.
  • authentication.redirectResponseUrl: Adresa URL către care doriți să redirecționați plătitorul după finalizarea procesului de autentificare a plătitorului.

Rețineți că nu puteți să ștergeți câmpuri dintr-o sesiune, dar puteți suprascrie valorile câmpurilor existente.

Referință API Update Session[REST][NVP]

Pasul 2: Inițializați API

Consultați API-ul JS RuPay (rupay.js) de pe serverele gateway-ului. Această acțiune va plasa obiectul rupay în fereastră/spațiul de nume global.

Referința rupay.js[JavaScript]

Odată ce ați creat o sesiune, inițializați API-ul prin metoda configure( ). Această metodă trebuie apelată în timpul încărcării paginii sau când DOM se află în starea pregătită. Aceasta trebuie apelată o singură dată pentru o încărcare de pagină. După apelarea acestei metode, JS RuPay va furniza valorile de configurare sub formă de variabile-membru.

Solicitarea de inițializare JS RuPay

Puteți inițializa API-ul RuPay JS invocând metoda configure() cu următoarele câmpuri obligatorii ca argumente într-un obiect de cartografiere:

  • merchantId: Identificatorul dvs. de comerciant pe gateway.
  • sessionId: ID-ul de sesiune creat prin apelul Create Session.
  • containerId: ID-ul <div> din codul dvs. HTML în care API-ul va injecta un cadru iFrame ascuns.
  • callback: O funcție care va fi invocată după inițializarea API-ului.
  • configuration: Valoarea JSON asociată elementelor de date precum userLanguage(optional), versiunea API-ului REST (wsVersion).
Exemplu de inițializare a configurării API-ului
<html>
    <head>
    <script src="https://egenius.unicredit.ro/static/rupay/1.0.0/rupay.js"
            data-error="errorCallback"
            data-cancel="cancelCallback">
    </script>

    <script type="text/javascript">
        //The output of this call will return 'false', since the API is not configured yet
        console.log(Rupay.isConfigured());
        /**
        Configure method with the configuration{} parameter set and demonstrates the state change of the rupay object before and after the configure method is invoked.
        */
        Rupay.configure({
    merchantId: "TESTMERCHANT",
    sessionId: "SESSION0002899787259G30902270H6",
    containerId: "ABC",
    callback: function() {
        if (Rupay.isConfigured())
            console.log("Done with configure");
    },
    configuration: {
        userLanguage: "en-US",
        wsVersion: 55
    }
});

    </script>
    </head>
    <body>
        <div id="RupayUI"></div>
    </body>
</html>

Pasul 3: Inițierea autentificării

Odată ce toate datele plătitorului și plății au fost colectate într-o sesiune, puteți iniția autentificarea invocând metoda initiateAuthentication(). Aceasta vă permite să determinați dacă autentificarea plătitorilor RuPay este disponibilă pentru comerciant în cazul unui anumit card. Dacă tipul cardului este RuPay, gateway-ul determină eligibilitatea codului BIN al cardului RuPay pentru tranzacțiile de comerț electronic.

Solicitarea Initiate Authentication

Puteți iniția autentificarea completând următoarele câmpuri obligatorii în metoda initiateAuthentication():

  • orderId: Identificatorul unic al comenzii.
  • transactionId: Identificatorul unic pentru această autentificare a plății.
  • callback: Funcția callback.
  • optionalParams: (opțional) argument cu orice câmpuri suplimentare ale solicitării API REST Initiate Authentication, cum ar fi correlationId.
Răspunsul la inițierea autentificării

Dacă autentificarea RuPay a plătitorului este disponibilă, următoarele câmpuri sunt returnate în argumentul data al funcției callback. În caz contrar, răspunsul va include o eroare.

  • data.restApiResponse: Conține răspunsul brut din apelul API REST Initiate Authentication.
  • data.correlationId: Ultimul ID de corelare utilizat pentru efectuarea apelului API REST Authentication. Acesta permite corelarea răspunsului cu solicitarea.
  • data.gatewayRecommendation

Pentru a determina pasul următor, verificați recomandarea gateway-ului, furnizată în câmpul gatewayRecommendation.

gatewayRecommendation Pasul următor
PROCEED Puteți continua cu autentificarea plătitorului folosind apelarea metodei authenticatePayer( ).
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS Solicitați plătitorului detalii alternative de plată (de exemplu, un card nou sau altă metodă de plată) și retrimiteți solicitarea cu noile detalii. Nu retrimiteți aceeași solicitare.

Tabelul de mai jos prezintă răspunsul Initiate Authentication pentru diferitele scenarii de autentificare RuPay.

Stare response.gatewayRecommendation transaction.authenticationStatus response.gatewayCode result
  • Initiate Authentication finalizată
  • Înscris (eligibil pentru comerț electronic)
 PROCEED AUTHENTICATION_AVAILABLE AUTHENTICATION_IN_PROGRESS SUCCESS
  • Initiate Authentication finalizată
  • Neînscris (neeligibil pentru comerț electronic)
 RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS AUTHENTICATION_NOT_SUPPORTED DECLINED FAILURE
  • Expirare timp achizitor
 RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS AUTHENTICATION_UNAVAILABLE DECLINED FAILURE
  • Răspuns BIN nevalid de la RuPay PaySecure
 RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS AUTHENTICATION_NOT_SUPPORTED DECLINED FAILURE
  • Dacă RuPay PaySecure nu poate procesa tranzacțiile dintr-un motiv nespecificat.
 RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS AUTHENTICATION_UNAVAILABLE DECLINED FAILURE
Exemplu de trimitere a unei solicitări Initiate Authentication
var optionalParams = {
    sourceOfFunds: {
        type: "CARD"
    },
    order: {
        walletProvider: "MASTERPASS_ONLINE"
    }
};

Rupay.initiateAuthentication({orderId}, {transactionId}, function (data) {
    if (data && data.error) {
        var error = data.error;

        //Something bad happened, the error value will match what is returned by the Authentication API
        console.error("error.code : ", error.code);
        console.error("error.msg : ", error.msg);
        console.error("error.result : ", error.result);
        console.error("error.status : ", error.status);
    } else {
        console.log("After Initiate RuPay ", data);

        //data.response will contain information like gatewayRecommendation, authentication version, etc.
        console.log("REST API raw response ", data.restApiResponse);
        console.log("Correlation Id", data.correlationId);
        console.log("Gateway Recommendation", data.gatewayRecommendation);
        console.log("HTML Redirect Code", data.htmlRedirectCode);
        console.log("Authentication Version", data.authenticationVersion);

        switch (data.gatewayRecommendation) {
            case "PROCEED":
                authenticatePayer();//merchant's method
                break;
            case "RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS":
                tryOtherPayment();//Card does not support 3DS and transaction filtering rules require 3DS on this transaction: Ask the payer to select a different payment method
                break;
        }
    }
}, optionalParams);

Pasul 4: Autentificarea plătitorului

Acolo unde răspunsul la operațiunea Initiate Authentication a indicat disponibilitatea autentificării (authentication.version=RUPAY) pentru cardul RuPay, puteți invoca metoda authenticatePayer(). Aceasta trebuie invocată atunci când plătitorul face clic pe butonul „Plătiți acum” de pe pagina de validare.

Operațiunea Authenticate Payer transmite în mod securizat informațiile necesare, inclusiv numărul cardului, între banca achizitoare și RuPay PaySecure. PaySecure returnează un ID unic al tranzacției (tran_ID), care poate fi utilizat pentru operațiunile de autorizare sau plată ulterioare.

Solicitarea Authenticate Payer

Trebuie să invocați metoda authenticatePayer() completând următoarele câmpuri obligatorii:

  • orderId: Aceeași valoare orderId cu cea a metodei initiateAuthentication() anterioare.
  • transactionId: Aceeași valoare transactionId cu cea a metodei initiateAuthentication() anterioare.
  • callback: Funcția callback.
  • optionalParams: (opțional) argumentează cu orice câmpuri suplimentare ale solicitării API REST Authenticate Payer, cum ar fi fullScreenRedirect, billing.
Răspunsul de autentificare a plătitorului

Următoarele câmpuri sunt returnate în argumentul data al funcției callback:

  • data.restApiResponse: Conține răspunsul brut din apelul API REST Authentication Payer.
  • data.correlationId: Ultimul ID de corelare utilizat pentru efectuarea apelului API REST Authentication Payer. Acesta permite corelarea răspunsului cu solicitarea.
  • data.gatewayRecommendation
  • data.htmlRedirectCode: Gateway-ul returnează întotdeauna acest câmp pentru inserarea în pagina afișată pentru plătitor.

Pentru a determina pasul următor, verificați recomandarea gateway-ului, furnizată în câmpul gatewayRecommendation returnat în funcția callback.

gatewayRecommendation Pasul următor
Continuați Puteți continua cu finalizarea procesului de autentificare (procesul de testare) sau puteți finaliza plata (proces optimizat).
DO_NOT_PROCEED_ABANDON_ORDER Nu trimiteți din nou aceeași solicitare. Furnizorul de servicii de plată, schema sau emitentul vă solicită să abandonați comanda.
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS Solicitați plătitorului detalii alternative de plată (de exemplu, un card nou sau altă metodă de plată) și retrimiteți solicitarea cu noile detalii. Nu retrimiteți aceeași solicitare.

Dacă gateway-ul recomandă PROCEED, atunci lipiți conținutul câmpului htmlRedirectCode din răspuns pe pagina afișată pentru plătitor.

Tabelul de mai jos prezintă răspunsul authenticatePayer() pentru diferitele scenarii de autentificare RuPay.

Stare response.gatewayRecommendation transaction.authenticationStatus authentication.payerInteraction response.gatewayCode result
  • Autentificare plătitor realizată cu succes
  • Proces de testare inițiat.
 PROCEED AUTHENTICATION_PENDING REQUIRED PENDING PENDING
  • Autentificarea la emitent a eșuat din cauza detaliilor nevalide ale cardului.
 DO_NOT_PROCEED_ABANDON_ORDER AUTHENTICATION_REJECTED NOT_REQUIRED DECLINED FAILURE
  • Expirare timp achizitor
 RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS AUTHENTICATION_UNAVAILABLE NOT_POSSIBLE DECLINED FAILURE
  • Răspuns BIN nevalid de la NPCI
 RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS AUTHENTICATION_UNAVAILABLE NOT_POSSIBLE DECLINED FAILURE
  • Dacă RuPay PaySecure nu poate procesa tranzacțiile dintr-un motiv nespecificat.
 RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS AUTHENTICATION_UNAVAILABLE NOT_POSSIBLE DECLINED FAILURE
  • Eroare sistem (eroare tehnică la RuPay PaySecure)
 RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS AUTHENTICATION_UNAVAILABLE NOT_POSSIBLE DECLINED FAILURE

Autentificare OTP

Gateway-ul redirecționează browserul plătitorului către IU de validare OTP a emitentului, unde plătitorului i se va solicita să introducă o OTP validă, după care plătitorul va fi redirecționat înapoi către 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
  • result
  • response.gatewayRecommendation

Puteți determina rezultatul autentificării folosind valoarea returnată în câmpul response.gatewayRecommendation.

response.gatewayRecommendation Pasul următor
PROCEED Puteți continua cu plata, deoarece autentificarea a fost efectuată. Dacă autorizarea plății a reușit, cu rambursarea fondurilor și, dacă este cazul, cu expedierea bunurilor.
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS Solicitați plătitorului detalii alternative de plată (de exemplu, un card nou sau altă metodă de plată) și retrimiteți solicitarea cu noile detalii. Nu retrimiteți aceeași solicitare.

Gateway-ul actualizează câmpurile răspunsului Authenticate Payer după apelarea rezultatelor din cadrul autentificării OTP.

Stare response.gatewayRecommendation transaction.authenticationStatus authentication.payerInteraction response.gatewayCode result
  • Proces de testare realizat cu succes.
 PROCEED AUTHENTICATION_SUCCESSFUL REQUIRED APPROVED SUCCESS
  • Proces de testare eșuat; de exemplu, timp expirat, OTP nevalidă etc.
 RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS AUTHENTICATION_FAILED REQUIRED DECLINED FAILURE
Exemplu de solicitare Authenticate Payer
var optionalParams = {
    fullScreenRedirect: true,
    billing: {
        address: {
            city: "London",
            country: "GBR"
        }
    }
};

Rupay.authenticatePayer("5678", "ABC", function (data) {
    if (!data.error) {
        //data.response will contain all the response payload from the AUTHENTICATE_PAYER call.
        console.log("REST API response ", data.restApiResponse);
        console.log("HTML redirect code ", data.htmlRedirectCode);
    }
}, optionalParams);

Pasul 5: Utilizarea rezultatului autentificării într-o operațiune de plată

Dacă rezultatul metodei authenticatePayer() indică faptul că puteți continua plata (gatewayRecommendation=PROCEED), puteți să inițiați o operațiune Authorize sau Pay. În plus față de câmpurile standard, trebuie să completați următoarele câmpuri:

  • order.id: Furnizați orderId utilizat în metodele initiateAuthentication() și authenticatePayer().
  • authentication.transactionId: Furnizați transactionId utilizat în metodele initiateAuthentication() și authenticatePayer(). Nu este necesar să includeți niciunul dintre câmpurile din grupul de parametri de autentificare, deoarece gateway-ul va utiliza valoarea authentication.transactionId pentru a căuta rezultatele autentificării pe care le-a salvat în momentul în care ați solicitat efectuarea autentificării. Gateway-ul va transmite achizitorului informațiile solicitate.
Exemplu de solicitare Pay
URL https://egenius.unicredit.ro/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}
Metoda HTTP PUT 
{
      "apiOperation":"PAY",
      "order":{
         "amount":"100",
         "currency":"INR"
     },
     "sourceOfFunds":{
         "provided":{
            "card":{
               "expiry":{
                  "month":"01",
                  "year":"21"
               },
               "number":"6074819900004939",
               "securityCode":"111"
            }
         },
         "type":"CARD"
      },
         "authentication": {
           "transactionId":"8286737"
       }
   }
Exemplu de răspuns de plată
	{
        "authentication": {
            "transactionId": "471707320"
        },
        "authorizationResponse": {
            "transactionIdentifier": "500000000000000000000002347854"
        },
        "gatewayEntryPoint": "WEB_SERVICES_API",
        "merchant": "TESTMERCHANT",
        "order": {
            "amount": 100.00,
            "chargeback": {
                "amount": 0,
                "currency": "INR"
            },
            "creationTime": "2019-07-03T09:08:28.309Z",
            "currency": "INR",
            "id": "802014086",
            "merchantCategoryCode": "4511",
            "status": "CAPTURED",
            "totalAuthorizedAmount": 100.00,
            "totalCapturedAmount": 100.00,
            "totalRefundedAmount": 0.00
        },
        "response": {
            "acquirerCode": "00",
            "acquirerMessage": "Success",
            "gatewayCode": "APPROVED"
        },
        "result": "SUCCESS",
        "sourceOfFunds": {
            "provided": {
                "card": {
                    "brand": "RUPAY",
                    "expiry": {
                        "month": "1",
                        "year": "21"
                    },
                    "fundingMethod": "DEBIT",
                    "issuer": "DMBB9990001",
                    "number": "607481xxxxxx4939",
                    "scheme": "RUPAY",
                    "storedOnFile": "NOT_STORED",
                    "tags": "{\"RUPAY_BIN_STATUS_FLAG\":\"ACTIVE\",\"RUPAY_BIN_MESSAGE_TYPE\":\"SMS\"}"
                }
            },
            "type": "CARD"
        },
        "timeOfRecord": "2019-07-03T09:08:28.309Z",
        "transaction": {
            "acquirer": {
                "id": "<acquirer_id>",
                "merchantId": "423555234334123"
            },
            "amount": 100.00,
            "authorizationCode": "143835",
            "currency": "INR",
            "frequency": "SINGLE",
            "id": "108379916",
            "receipt": "918409000035",
            "source": "INTERNET",
            "terminal": "88011019",
            "type": "PAYMENT"
        },
        "version": "72"
    }

Testați integrarea

Pentru a vă testa integrarea, vă puteți utiliza profilul de comerciant de TEST în mediul de lucru.

Copyright © 2023 UniCredit Bank