- Linee guida per l'integrazione
- Funzionalità supportate (sicurezza)
- Autenticazione del pagante RuPay
- Implementazione dell'autenticazione RuPay utilizzando l'API JavaScript RuPay
Implementazione dell'autenticazione RuPay utilizzando l'API JavaScript RuPay
Questa pagina descrive come integrarsi al gateway per utilizzare l'autenticazione RuPay utilizzando l'API RuPay JavaScript (JS).
Passaggio 1: Creazione e aggiornamento della sessione
RuPay JS utilizza l'autenticazione basata sulla sessione. Il primo passaggio consiste nella creazione di una sessione, che è quindi possibile aggiornare con i campi e i valori delle richieste che si desidera archiviare nella sessione.
È possibile creare una sessione utilizzando la chiamata Create Session. Si tratta di una chiamata API lato server ed è un prerequisito per l'integrazione con l'API JS. Vengono restituiti i seguenti campi:
session.id
: un identificativo di sessione univoco che è necessario fornire nelle richieste successive per fare riferimento al contenuto della sessione.session.authenticationLimit
: il limite fornito nella richiesta o il valore predefinito del gateway.session.aes256Key
: la chiave che può essere utilizzata per decrittografare i dati sensibili inviati al sito Web tramite il browser o il dispositivo mobile del pagante.session.version
: è possibile utilizzare questo campo per implementare il blocco ottimistico del contenuto della sessione.session.updateStatus
: un riepilogo del risultato dell'ultimo tentativo di modificare la sessione.
Riferimento API per Create Session[REST][NVP]
È possibile aggiungere o aggiornare i campi in una sessione utilizzando la chiamata Update Session. Consente di aggiungere dati di pagamento e di pagante a una sessione che può successivamente diventare l'input per determinare il rischio associato a un pagante in una operazione di autenticazione. In una sessione sono richiesti i seguenti campi:
Campi obbligatori
- sourceOfFunds.provided.card.*: i dettagli della carta usata per il pagamento.
order.amount
- order.currency: la valuta dell'ordine.
- transaction.id: un identificativo univoco per l'autenticazione di questo pagamento.
- order.id: un identificativo univoco per questo ordine.
authentication.channel
=PAYER_BROWSER
: il canale in cui viene avviata la richiesta di autenticazione.authentication.purpose
=PAYMENT_TRANSACTION
: indica il contesto in cui viene richiesta l'autenticazione del pagante.authentication.redirectResponseUrl
: l'URL a cui si desidera reindirizzare il pagante dopo aver completato il processo Authenticate Payer.
Tenere presente che non è possibile rimuovere i campi da una sessione, ma è solo possibile sovrascrivere i valori dei campi esistenti.
Passaggio 2: Inizializzazione dell'API
Fare riferimento all'API RuPay JS ( rupay.js
) dai server gateway. Questo posizionerà un oggetto rupay
nella finestra/spazio dei nomi globale.
Riferimento per rupay.js[JavaScript]
Dopo aver creato una sessione, inizializzare l'API utilizzando il metodo configure( )
. Questo metodo deve essere chiamato durante il caricamento della pagina o quando il DOM è pronto. Dovrebbe essere chiamato solo una volta per il caricamento della pagina. Dopo aver chiamato questo metodo, RuPay JS fornirà i valori di configurazione come variabili del membro.
È possibile inizializzare l'API JS di RuPay richiamando il metodo configure()
, con i seguenti campi obbligatori come argomenti in un oggetto mappa:
merchantId
: il proprio ID esercente sul gateway.sessionId
: l'ID sessione creato utilizzando la chiamata Create Session.containerId
: L'ID <div> nel proprio html, dove l'API inietterà un iframe nascosto.callback
: Una funzione che verrà invocata dopo l'inizializzazione dell'API.configuration
: valore JSON che supporta elementi di dati come userLanguage (opzionale), versione dell'API REST (wsVersion).
<html> <head> <script src="https://eu-gateway.mastercard.com/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>
Passaggio 3: Initiate Authentication
Una volta raccolti tutti i dati del pagante e di pagamento in una sessione, è possibile avviare l'autenticazione invocando il metodo initiateAuthentication()
. Consente di determinare se l'autenticazione del pagante RuPay è disponibile per l'esercente per una determinata carta. Se il tipo di carta è RuPay, il gateway determina l'idoneità del BIN della carta RuPay per le transazioni e-commerce.
È possibile avviare l'autenticazione fornendo i seguenti campi obbligatori nel metodo initiateAuthentication()
:
- ID ordine: l'identificativo univoco per questo ordine.
- transactionId: l'identificativo univoco per l'autenticazione di questo pagamento.
- callback: la funzione di callback.
- optionalParams: argomento (facoltativo) con eventuali campi di richiesta aggiuntivi API REST Initiate Authentication, come correlationId.
Se l'autenticazione RuPay del pagante è disponibile, nell'argomento data
della funzione di callback vengono restituiti i seguenti campi. In caso contrario, la risposta includerà un errore.
data.restApiResponse
: Contiene una risposta non elaborata dalla chiamata API REST Initiate Authentication.data.correlationId
: L'ultimo ID di correlazione utilizzato per effettuare la chiamata API REST Initiate Authentication. Consente di abbinare la risposta alla richiesta.data.gatewayRecommendation
Per determinare il passaggio successivo, controllare la raccomandazione del gateway fornita nel campo gatewayRecommendation.
gatewayRecommendation |
Passaggio successivo |
---|---|
PROCEED | È possibile procedere all'autenticazione del pagante usando la chiamata con metodo authenticatePayer( ) . |
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | Chiedere al pagante dettagli di pagamento alternativi (ad esempio, una nuova carta o un'altra modalità di pagamento) e inviare nuovamente la richiesta con i nuovi dettagli. Non inviare nuovamente la stessa richiesta. |
La tabella seguente mostra la risposta Initiate Authentication per i vari scenari di autenticazione Rupay.
Esito | 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);
Passaggio 4: Authenticate Payer
Se la risposta Initiate Authentication ha indicato che l'autenticazione è disponibile (authentication.version = RUPAY) per la carta RuPay, è possibile invocare il metodo authenticatePayer()
. L'esercente dovrebbe richiamarla quando il pagante fa clic sul pulsante "Paga adesso" nella pagina di checkout.
L'operazione Authenticate Payer scambia in modo sicuro le informazioni necessarie, incluso il numero della carta, tra la banca affiliante e RuPay PaySecure. PaySecure restituisce un ID transazione univoco (tran_ID), che può essere utilizzato nelle successive operazioni di autorizzazione o pagamento.
È necessario invocare il metodo authenticatePayer()
fornendo i seguenti campi obbligatori:
orderId
: lo stesso orderId del metodoinitiateAuthentication()
che lo ha preceduto.transactionId
: lo stesso transactionId del metodoinitiateAuthentication()
che lo ha preceduto.callback
: la funzione di callback.optionalParams
: Argomenti (facoltativi) con eventuali campi di richiesta aggiuntivi API REST Authenticate Payer comefullScreenRedirect
,billing
.
I seguenti campi sono restituiti nell'argomento data
della funzione di callback:
data.restApiResponse
: contiene una risposta non elaborata dalla chiamata API REST Authenticate Payerdata.correlationId
: l'ultimo ID di correlazione utilizzato per effettuare la chiamata API REST Authenticate Payer. Consente di abbinare la risposta alla richiesta.data.gatewayRecommendation
data.htmlRedirectCode
: il gateway restituisce sempre questo campo per l'inserimento nella pagina visualizzata al pagante.
Per determinare il passaggio successivo, controllare la raccomandazione del gateway fornita nel campo gatewayRecommendation
restituito nel callback.
gatewayRecommendation |
Passaggio successivo |
---|---|
Continuare | È possibile procedere per completare il processo di autenticazione (flusso di verifica) o procedere per completare il pagamento (flusso agevole). |
DO_NOT_PROCEED_ABANDON_ORDER | Non inviare nuovamente la stessa richiesta. Il provider di servizi di pagamento, il circuito o l'issuer richiedono di abbandonare l'ordine. |
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | Chiedere al pagante dettagli di pagamento alternativi (ad esempio, una nuova carta o un'altra modalità di pagamento) e inviare nuovamente la richiesta con i nuovi dettagli. Non inviare nuovamente la stessa richiesta. |
Se il gateway consiglia PROCEED
, incollare il contenuto del campo di risposta htmlRedirectCode
nella pagina visualizzata al pagante.
La tabella seguente mostra la risposta authenticatePayer()
per i vari scenari di autenticazione Rupay.
Esito | 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 |
Autenticazione OTP
Il gateway reindirizza il browser del pagante all'interfaccia utente di convalida OTP dell'issuer in cui verrà richiesto al pagante di inserire una OTP valida, dopodiché verrà reindirizzato al sito web dell'esercente. Dopo il reindirizzamento al sito Web dell'esercente, nel callback vengono restituiti i seguenti campi:
- order.id
- transaction.id
- result
- response.gatewayRecommendation
È possibile determinare il risultato dell'autenticazione utilizzando il valore restituito nel campo response.gatewayRecommendation
.
response.gatewayRecommendation |
Passaggio successivo |
---|---|
PROCEED | È possibile procedere con il pagamento poiché viene concessa l'autenticazione. Se l'autorizzazione per il pagamento è andata a buon fine, procedere con l'acquisizione dei fondi e, se applicabile, spedire la merce. |
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | Chiedere al pagante dettagli di pagamento alternativi (ad esempio, una nuova carta o un'altra modalità di pagamento) e inviare nuovamente la richiesta con i nuovi dettagli. Non inviare nuovamente la stessa richiesta. |
Il gateway aggiorna i campi della risposta Authenticate Payer dopo aver recuperato i risultati dall'autenticazione OTP.
Esito | 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);
Passaggio 5: Uso del risultato dell'autenticazione in un'operazione di pagamento
Quando il risultato del metodo authenticatePayer()
indica che è possibile procedere al pagamento (response.gatewayRecommendation=PROCEED) l'esercente può avviare un'operazione Authorize o Pay. Oltre ai campi standard, è necessario fornire i campi indicati di seguito:
-
order.id: fornire il
orderId
fornito nei metodiinitiateAuthentication()
eauthenticatePayer()
. -
authentication.transactionId: fornire il
transactionId
fornito nei metodiinitiateAuthentication()
eauthenticatePayer()
. Non è necessario includere alcun parametro del gruppo di parametri di autenticazione, in quanto il gateway utilizzerà authentication.transactionId per cercare i risultati dell'autenticazione archiviati quando si è chiesto al gateway di effettuare l'autenticazione. Il gateway inoltrerà le informazioni richieste all'acquirer.
URL | https://eu-gateway.mastercard.com/api/rest/version/72/esercente/{merchantId}/ordine/{orderid}/transazione/{transactionid} |
Metodo 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" }
Test dell'integrazione
Per testare la propria integrazione è possibile utilizzare il proprio profilo esercente di PROVA nell'ambiente di produzione.