- Ghid de integrare
- Caracteristici acceptate (Securitate)
- Autentificarea plătitorului pentru RuPay
- Implementarea autentificării RuPay cu ajutorul API JavaScript RuPay
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.
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]
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.
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.
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).
<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.
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.
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 |
|---|---|---|---|---|
|
PROCEED | AUTHENTICATION_AVAILABLE | AUTHENTICATION_IN_PROGRESS | SUCCESS |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_NOT_SUPPORTED | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_NOT_SUPPORTED | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | DECLINED | FAILURE |
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.
Trebuie să invocați metoda authenticatePayer() completând următoarele câmpuri obligatorii:
orderId: Aceeași valoare orderId cu cea a metodeiinitiateAuthentication()anterioare.transactionId: Aceeași valoare transactionId cu cea a metodeiinitiateAuthentication()anterioare.callback: Funcția callback.optionalParams: (opțional) argumentează cu orice câmpuri suplimentare ale solicitării API REST Authenticate Payer, cum ar fifullScreenRedirect,billing.
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.gatewayRecommendationdata.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). |
| NU_CONTINUAȚI_ABANDONAȚI_COMANDA | 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 |
|---|---|---|---|---|---|
|
PROCEED | AUTHENTICATION_PENDING | REQUIRED | PENDING | PENDING |
|
DO_NOT_PROCEED_ABANDON_ORDER | AUTHENTICATION_REJECTED | NOT_REQUIRED | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | NOT_POSSIBLE | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | NOT_POSSIBLE | DECLINED | FAILURE |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_UNAVAILABLE | NOT_POSSIBLE | DECLINED | FAILURE |
|
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 decontarea 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 |
|---|---|---|---|---|---|
|
PROCEED | AUTHENTICATION_SUCCESSFUL | REQUIRED | APPROVED | SUCCESS |
|
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | AUTHENTICATION_FAILED | REQUIRED | DECLINED | FAILURE |
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
orderIdutilizat în metodeleinitiateAuthentication()șiauthenticatePayer(). -
authentication.transactionId: Furnizați
transactionIdutilizat în metodeleinitiateAuthentication()șiauthenticatePayer(). 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.
| 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"
}
}
{
"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 TESTARE comerciant în mediul de lucru.