RuPay Guest Checkout
In Guest Checkout if a payer is not registered on your portal, they must follow the integration described in this guide. You can follow similar integration for redirect payer authentication mode.
Guest Checkout Transaction
Guest Checkout is a transaction flow where cardholders manually enter the card details while undertaking the transaction.
Guest Checkout or ALT ID overview
Currently, Guest Checkout transactions that the Indian merchants' processes for Indian RuPay cardholders are processed using the card detail.
To support the Guest checkout transactions without FPANs, industry provided a solution to replace FPAN details with ALT-ID and ALT-ID-cryptogram.
Cardholders still use FPANs during Guest Checkout and you can call any token integrator to replace FPAN details with ALT-ID and ALT-ID-cryptogram. Initiate transaction request with ALT-ID and ALT-ID-cryptogram to payment gateways.
Transaction flow overview
- Cardholder reviews and confirms the order details using FPAN details on your application or website.
- You use FPAN clear card for authentication.
- After successful authentication, your website or application initiates a call to the token integrator or ALT-ID service provider using the Authref ID.
- Authref ID is sent to the token integrator or ALT-ID service provider, who then contacts NPCI Tokenization Service (NTS) to obtain ALT-ID and ALT-ID-cryptogram.
- Token integrator or ALT-ID provider sends the ALT-ID and ALT-ID-cryptogram either to you or to token requestor.
- After successful authentication replace FPAN details with ALT-ID and ALT-ID-cryptogram, and then complete the payment transaction.
- Mastercard Gateway follows NPCI specifications and RBI Guest Checkout guidelines to map required fields and keep you and the acquirer compliant for RuPay cards.
WS API operations
For more information about the guidelines for API operation Authorize, see the following guides:
- RuPay Authentication Implementation using Authentication API
- WS API Integration guide
For WS API Integration guide, ensure to see from v71 onwards.
Merchant implementation
API Operation Authentication: Initiate Authentication and Authenticate Payer API Operation Authorize – Authorize or Pay Subsequent Operation such as Retrieve Transaction, Capture, Refund, and Void. If you are integrated with WS API v71 and above, send the Authorize or Pay request with Alt-Id and Alt-Id cryptogram as follows:
- sourceOfFunds.provided.card.devicePayment.onlinePaymentCryptogram: Alt-ID cryptogram
- sourceOfFunds.provided.card.number: Alt-ID
- sourceOfFunds.type: SCHEME_TOKEN
- sourceOfFunds.provided.card.storedOnFile= NOT_STORED
- transaction.source: INTERNET
As stated, gateway allows you to use clear card in authentication flow. You must submit WS API request with customer.account.authentication.method=NONE in Authenticate Payer API.
This API fields indicate that the authentication is performed for the Guest Checkout transaction and gateway will send the required indicator to NPCI according to the specification.
The following table describes the gateway validation and recommendation.
| Use case | WS API | Description |
|---|---|---|
| Add card for Guest Checkout | Step 1: Initiate Authentication
authentication.purpose= ADD_CARD
Step 2: Authenticate Payer customer.account.authentication.method=NONE |
Do not add card during their guest checkout transaction. |
| Guest checkout with the payer that includes an initial charge | Step 1: Initiate Authentication
authentication.purpose= PAYMENT_TRANSACTION
Step 2: Authenticate Payer Amount > 0 customer.account.authentication.method=NONE |
Use any amount greater than 0 for guest checkout transaction. |
The following table describes the WS API validations.
| Scenario | Error message |
|---|---|
WS API Operation - AUTHORIZE or PAY
Request containing sourceOfFunds.type= SCHEME_TOKEN and an Indian merchant with the RuPay credential has made a transaction, if sourceOfFunds.provided.card.devicePayment.onlinePaymentCryptogram is not alphanumeric.
|
result=Error error.cause=INVALID_REQUEST error.validationType=INVALID error.field="sourceOfFunds.provided.card.devicePayment.onlinePaymentCryptogram" error.explanation= "Value <value> is invalid. The field must only contain up to 113 alphanumeric characters including 0-9, a-z, A-Z,", |
WS API Operation - AUTHORIZE or PAY
Request containing sourceOfFunds.type= SCHEME_TOKEN and an Indian merchant with the RuPay credential has made a transaction,
if sourceOfFunds.provided.card.devicePayment.onlinePaymentCryptogram has more than 113 characters.
|
result=Error
error.cause=INVALID_REQUEST
error.validationType=INVALID
error.field="sourceOfFunds.provided.card.devicePayment.onlinePaymentCryptogram"
error.explanation="Value <value> is invalid. The field must only contain up to 113 alphanumeric characters including 0-9, a-z, A-Z,", |
WS API Operation -AUTHORIZE or PAY
If the transaction has sourceOfFunds.type= SCHEME_TOKEN and sourceOfFunds.provided.card.devicePayment.onlinePaymentCryptogram and the sourceOfFunds.provided.card.storedOnFile=NOT_STORED not present.
|
result=Error error.cause=INVALID_REQUEST error.validationType=INVALID error.field=sourceOfFunds.provided.card.storedOnFile error.explanation= For Rupay India Guest Checkout transactions that use sourceOfFunds.provided.card.devicePayment.onlinePaymentCryptogram field you must provide sourceOfFunds.provided.card.storedOnFile=NOT_STORED |
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/71/merchant/{MID}/order/{OID}/transaction/{TID}' \ |
| HTTP Method | PUT |
'{
"apiOperation": "INITITATE_AUTHENTICATION",
"authentication" :{
"purpose": "PAYMENT_TRANSACTION",
"channel" : "PAYER_BROWSER"
},
"order": {
"currency": "INR"
},
"sourceOfFunds": {
"provided": {
"card": {
"number": "CARD NUMBER"
}
},
"type": "CARD"
}
}'
{
"authentication": {
"purpose": "PAYMENT_TRANSACTION",
"redirect": {
"html": "<script id=\"initiate-authentication-script\"></script>"
},
"version": "RUPAY"
},
"merchant": "NPCI_HDFC_A",
"order": {
"authenticationStatus": "AUTHENTICATION_AVAILABLE",
"creationTime": "2024-03-19T07:00:35.843Z",
"currency": "INR",
"id": "441843723",
"lastUpdatedTime": "2024-03-19T07:00:32.894Z",
"merchantCategoryCode": "1234",
"status": "AUTHENTICATION_INITIATED",
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"gatewayCode": "AUTHENTICATION_IN_PROGRESS",
"gatewayRecommendation": "PROCEED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"number": "CARD NUMBER",
"scheme": "RUPAY"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2024-03-19T07:00:32.894Z",
"timeOfRecord": "2024-03-19T07:00:35.843Z",
"transaction": {
"amount": 0,
"authenticationStatus": "AUTHENTICATION_AVAILABLE",
"currency": "INR",
"id": "10044439",
"type": "AUTHENTICATION"
},
"version": "71"
}
Following are the sample payload API Request and Response for AUTHENTICATE_PAYER with clear FPAN.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/71/merchant/{MID}/order/{OID}/transaction/{TID}' \ |
| HTTP Method | PUT |
'{
"apiOperation": "AUTHENTICATE_PAYER",
"order": {
"amount": "8",
"currency": "INR"
},
"customer": {
"account": {
"authentication": {
"method": "NONE"
}
}
},
"sourceOfFunds": {
"provided": {
"card": {
"number": "CARD NUMBER",
"expiry": {
"month": "08",
"year": "26"
},
"securityCode": "123"
}
}
},
"device": {
"ipAddress": "103.14.160.193",
"browser": "MOZILLA/4.0 (COMPATIBLE; MSIE 5.0; WINDOWS 95)",
"browserDetails": {
"acceptHeaders": "texct/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
}
},
"authentication": {
"redirectResponseUrl": "www.mastercard.com"
}
}'
{
"authentication": {
"amount": 8.00,
"method": "DYNAMIC",
"payerInteraction": "REQUIRED",
"redirect": {
"html": "<div id='redirectToNpciAcsSimple' xmlns='http://www.w3.org/1999/html'> <form id='redirectToNpciForm' onsubmit='clickedSubmit(event)' name='redirectToNpciForm' method='POST' target='my_iframe' action='https://test-nbkpayment.mtf.gateway.mastercard.com/api/callbackInterface/gateway/3f93c11075c2de30ada7916eb7ef970f62b649366a29736f8d662e542033cefd'> <fieldset id='rupayOTP'> <div align ='left'> <img class='RupayLogo' </div>"
},
"status": {
"code": "00",
"description": "Transaction was successfully initiated and card details verified by issuer."
},
"time": "2024-03-19T07:00:41.699Z",
"version": "RUPAY"
},
"device": {
"ipAddress": "103.14.160.193"
},
"merchant": "NPCI_HDFC_A",
"order": {
"amount": 8.00,
"authenticationStatus": "AUTHENTICATION_PENDING",
"creationTime": "2024-03-19T07:00:41.741Z",
"currency": "INR",
"id": "441843723",
"lastUpdatedTime": "2024-03-19T07:00:38.795Z",
"merchantCategoryCode": "1234",
"status": "AUTHENTICATION_INITIATED",
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0,
"valueTransfer": {
"accountType": "NOT_A_TRANSFER"
}
},
"response": {
"gatewayCode": "PENDING",
"gatewayRecommendation": "PROCEED"
},
"result": "PENDING",
"sourceOfFunds": {
"provided": {
"card": {
"expiry": {
"month": "8",
"year": "26"
},
"number": "CARD NUMBER",
"scheme": "RUPAY"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2024-03-19T07:00:38.795Z",
"timeOfRecord": "2024-03-19T07:00:41.741Z",
"transaction": {
"acquirer": {
"merchantId": "NPCI_HDFC_A"
},
"amount": 8.00,
"authenticationStatus": "AUTHENTICATION_PENDING",
"currency": "INR",
"id": "10044439",
"type": "AUTHENTICATION"
},
"version": "71"
}
Retrieve transaction
After a successful payer authentication in WS API field authentication.3ds.transactionId, the gateway sends the Authref ID either to you or to the token requestor.
Token requestor initiates the Tokenization APIs, an NPCI token service, to fetch the respective ALT ID Tokens, and then shares them with you.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/71/merchant/{MID}/order/{OID}/transaction/{TID}' \ |
| HTTP Method | PUT |
{
"authentication": {
"3ds": {
"transactionId": "348379312580808709865779167062"
},
"status": {
"code": "00",
"description": "Transaction was successfully initiated and card details verified by issuer."
},
"amount": 8.00,
"method": "DYNAMIC",
"payerInteraction": "REQUIRED",
"time": "2024-03-19T07:00:41.699Z",
"version": "RUPAY"
},
"device": {
"browser": "MOZILLA/4.0 (COMPATIBLE; MSIE 5.0; WINDOWS 95)",
"ipAddress": "103.14.160.193"
},
"merchant": "NPCI_HDFC_A",
"order": {
"amount": 8.00,
"authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
"chargeback": {
"amount": 0,
"currency": "INR"
},
"creationTime": "2024-03-19T07:00:38.783Z",
"currency": "INR",
"id": "441843723",
"lastUpdatedTime": "2024-03-19T07:00:55.064Z",
"merchantAmount": 8.00,
"merchantCategoryCode": "1234",
"merchantCurrency": "INR",
"status": "AUTHENTICATED",
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalDisbursedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"gatewayCode": "APPROVED",
"gatewayRecommendation": "PROCEED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"expiry": {
"month": "8",
"year": "26"
},
"number": "CARD NUMBER",
"scheme": "RUPAY"
}
},
"type": "CARD"
},
"timeOfLastUpdate": "2024-03-19T07:00:55.064Z",
"timeOfRecord": "2024-03-19T07:00:55.064Z",
"transaction": {
"acquirer": {
"merchantId": "NPCI_HDFC_A"
},
"amount": 8.00,
"authenticationStatus": "AUTHENTICATION_SUCCESSFUL",
"currency": "INR",
"id": "10044439",
"stan": "0",
"type": "AUTHENTICATION"
},
"version": "71"
}
Following are the API request and response for AUTHORIZE with ALT ID and Cryptogram with reference to AuthRef ID.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/71/merchant/{MID}/order/{OID}/transaction/{TID}' \ |
| HTTP Method | PUT |
'{
"apiOperation": "AUTHORIZE",
"order": {
"amount": "8.00",
"currency": "INR"
},
"sourceOfFunds": {
"provided": {
"card": {
"number": "TOKEN NUMBER / ALT ID",
"expiry": {
"month": "08",
"year": "26"
},
"devicePayment": {
"onlinePaymentCryptogram": "APJUR+bB46ysAAKYEAOYGgADFA=="
},
"securityCode": "123"
}
},
"type": "SCHEME_TOKEN"
},
"authentication": {
"transactionId": "10044439"
},
"device": {
"ipAddress": "103.14.160.193",
"browser": "MOZILLA/4.0 (COMPATIBLE; MSIE 5.0; WINDOWS 95)"
}
}'
{
"authentication": {
"transactionId": "10044439"
},
"authorizationResponse": {
"transactionIdentifier": "348379312580808709865779167062"
},
"device": {
"browser": "MOZILLA/4.0 (COMPATIBLE; MSIE 5.0; WINDOWS 95)",
"ipAddress": "103.14.160.193"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "NPCI_HDFC_A",
"order": {
"amount": 8.00,
"chargeback": {
"amount": 0,
"currency": "INR"
},
"creationTime": "2024-03-19T07:00:38.783Z",
"currency": "INR",
"id": "441843723",
"lastUpdatedTime": "2024-03-19T07:01:26.588Z",
"merchantAmount": 8.00,
"merchantCategoryCode": "1234",
"merchantCurrency": "INR",
"status": "AUTHORIZED",
"totalAuthorizedAmount": 8.00,
"totalCapturedAmount": 0.00,
"totalDisbursedAmount": 0.00,
"totalRefundedAmount": 0.00
},
"response": {
"acquirerCode": "00",
"acquirerMessage": "Success",
"gatewayCode": "APPROVED",
"gatewayRecommendation": "NO_ACTION"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "RUPAY",
"deviceSpecificExpiry": {
"month": "8",
"year": "26"
},
"deviceSpecificNumber": "607484xxxxxx4936",
"expiry": {
"month": "8",
"year": "26"
},
"fundingMethod": "UNKNOWN",
"number": "TOKEN NUMBER",
"scheme": "RUPAY",
"storedOnFile": "NOT_STORED",
"tags": "{\"RUPAY_BIN_STATUS_FLAG\":\"ACTIVE\",\"RUPAY_BIN_MESSAGE_TYPE\":\"DMS\"}"
}
},
"type": "SCHEME_TOKEN"
},
"timeOfLastUpdate": "2024-03-19T07:01:26.588Z",
"timeOfRecord": "2024-03-19T07:01:23.348Z",
"transaction": {
"acquirer": {
"id": "NPCI_ACQ_S2S",
"merchantId": "423555234334123"
},
"amount": 8.00,
"authorizationCode": "686531",
"currency": "INR",
"id": "457711301",
"receipt": "407912000002",
"source": "INTERNET",
"stan": "2",
"terminal": "12334448",
"type": "AUTHORIZATION"
},
"version": "71"
}