Recent Revisions to This Document

23.01

Added a Standing Instructions section that includes use cases.

22.02

Updated OTP Resend section.

22.01

Added Seamless Flow section to manual.
Added a REST version.

19.01

Initial release.

About This Guide

Audience and Purpose

This guide is written for application developers who want to use the
REST
API to integrate Payer Authentication services into their order management system to process RuPay payments.
It describes the tasks you must perform in order to complete this integration. Implementing Payer Authentication services requires software development skills. You must write code that uses the API request and response fields to integrate payer authentication services into your existing order management system.

Scope

This guide describes how to use the
REST
API to integrate payer authentication services with your order management system. It does not describe how to get started using the
REST
API nor does it explain how to use services other than payer authentication. For that information, see the following
Related Documents
section.

Conventions

The following special statements are used in this document:
IMPORTANT
An
Important
statement contains information essential to successfully completing a task or learning a concept.
WARNING
A
Warning
contains information or instructions, which, if not heeded, can result in a security risk, irreversible loss of data, or significant cost in time or revenue or both.

Customer Support

For support information about any service, visit the Support Center:

VISA Platform Connect: Specifications and Conditions for Resellers/Partners

The following are specifications and conditions that apply to a Reseller/Partner enabling its merchants through
Cybersource for Visa Platform Connect (“VPC”) processing
. Failure to meet any of the specifications and conditions below is subject to the liability provisions and indemnification obligations under Reseller/Partner’s contract with Visa/Cybersource.
  1. Before boarding merchants for payment processing on a VPC acquirer’s connection, Reseller/Partner and the VPC acquirer must have a contract or other legal agreement that permits Reseller/Partner to enable its merchants to process payments with the acquirer through the dedicated VPC connection and/or traditional connection with such VPC acquirer.
  2. Reseller/Partner is responsible for boarding and enabling its merchants in accordance with the terms of the contract or other legal agreement with the relevant VPC acquirer.
  3. Reseller/Partner acknowledges and agrees that all considerations and fees associated with chargebacks, interchange downgrades, settlement issues, funding delays, and other processing related activities are strictly between Reseller and the relevant VPC acquirer.
  4. Reseller/Partner acknowledges and agrees that the relevant VPC acquirer is responsible for payment processing issues, including but not limited to, transaction declines by network/issuer, decline rates, and interchange qualification, as may be agreed to or outlined in the contract or other legal agreement between Reseller/Partner and such VPC acquirer.
DISCLAIMER: NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR ANY ERRORS OR OMISSIONS BY THE VISA PLATFORM CONNECT ACQUIRER IN PROCESSING TRANSACTIONS. NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR RESELLER/PARTNER BOARDING MERCHANTS OR ENABLING MERCHANT PROCESSING IN VIOLATION OF THE TERMS AND CONDITIONS IMPOSED BY THE RELEVANT VISA PLATFORM CONNECT ACQUIRER.

Overview of RuPay Payer Authentication

Cybersource
payer authentication services provide support to your web store for card authentication services for RuPay cards. Payer authentication for RuPay uses the same API services provided by
Cybersource
for other card brands. If you are currently using
Cybersource
payer authentication services for other card brands, you can enhance your existing integration to send the additional fields in the request that are required for RuPay cards.
Payer authentication provides these services:
  • Check Enrollment: Determines whether the customer is enrolled in a card authentication program.
  • Validate Authentication: Ensures that the authentication that you receive from the issuing bank is valid.
Unlike Visa and Mastercard cards, authentication is mandatory for RuPay cards. Without authentication, authorization cannot occur and the transaction is declined by the RuPay network.

Authentication Modes

RuPay authenticates the cardholder in two ways:
  • Redirection—This mode of payer authentication has the issuer hosting the password entry page. When a cardholder is being authenticated during a transaction, the issuer sends a one-time password to the cardholder's phone so that the cardholder can enter the password into a displayed entry form. If the entered password matches the password that was sent, the cardholder is authenticated and the transaction proceeds. In the Redirection mode, the password authentication is redirected away from the merchant to a URL that the issuer sends. The issuer hosts the password entry form at this URL. This redirection from the merchant to the issuer can cause lag time during the transaction processing due to network traffic.
  • Seamless Server to Server—This mode of payer authentication has the merchant hosting the password entry page. This is an improved method of authenticating with a one-time password. The process of password authenticating is much the same as the redirection but this method keeps the hosting of the password entry page with the merchant. The cardholder does not leave the merchant's web site during authentication. When the merchant hosts the password entry page, timeouts are reduced and transactions process faster.
The first section of this guide describes the Redirection Flow of payer authentication while the following section describes the Seamless Flow mode.

Redirection Mode Payer Authentication

When using Redirection Mode, during a transaction, the cardholder is redirected to the issuer's authentication page. Once redirected, a one-time password is sent to the cardholder's previously set email or phone number. When the cardholder re-enters the one-time password successfully, the cardholder is authenticated and returned to the merchant site to complete the transaction.
Network processing can introduce lag time into the purchase transaction.

Check Enrollment Service

When the customer places an online order, the the customer information is sent to the Verify Enrollment Response service (VERes) to verify that the card is enrolled in a payer authentication program.
  • If the card is enrolled, the VERes reply field indicates enrollment. The reply also contains the URL of the Access Control Server and the PAReq.
  • If the card is not enrolled, decline the payment and ask the customer for another form of payment.

Check Enrollment Request

For RuPay, the Check Enrollment service verifies that the card is enrolled in a card authentication program.
This request must include the following fields:
deviceInformation.ipAddress
The IP address must be the IP address of the customer who is making the purchase on your website. It must not be hard-coded or contain the address of the merchant’s servers. RuPay needs the correct IP address to manage any potential disputes.
deviceInformation.httpAcceptBrowserValue
This field contains the value of the Accept header sent by the customer’s web browser.
deviceInformation.userAgentBrowserValue
This field contains the value of the User-Agent header sent by the customer’s web browser.
paymentInformation.card.securityCode

REST Example: Enrollment Service

Request
{ "clientReferenceInformation":{ "code":"cybs_test" }, "orderInformation":{ "billTo":{ "firstName":"Suman", "lastName":"Kumar", "address1":"Bagmane WTC", "address2":"Doddenakundi", "locality":"Bangalore", "country":"IN", "administrativeArea":"KA", "postalCode":"560048", "email":"test@domain.com", "phoneNumber":"7606160717" }, "amountDetails":{ "totalAmount":"100.00", "currency":"INR" } }, "paymentInformation":{ "card":{ "type":"061", "expirationMonth":"12", "expirationYear":"2025", "number":"6080900372345281", "securityCode" :"123" } }, "deviceInformation" :{ "httpAcceptBrowserValue" : "http", "userAgentBrowserValue" : "user", "ipAddress":"10.0.0.1" } }
Response
{ "clientReferenceInformation": { "code": "cybs_test" }, "consumerAuthenticationInformation": { "acsUrl": "https://pnrstage.ic3.com:9448/cybersource/payerAuthentication/paySecure/initiate?binType=S", "xid": "MTM0MjE0MjYzODEzMTIwODE3NTA=", "authenticationTransactionId": "MTM0MjE0MjYzODEzMTIwODE3NTA=", "pareq": "e0NCQ2l2fWs3SVplQTVsZytraXBrOEFSNldKQVJBQUVDVmFhQlI2cC9DNVAzRGMrcFl6T3N1L09RZjF3UEhRU2NYWDZ4Y0wyVjhMalhiT0xtZW5zRVJ6Zi9ONEhyN1JXQ2NzbVFSbkZrZUYySDBNOGFxODUyYnJiRG1FTnBqMHZ2Z1NObFo1dHdEYjFlVlAwdnd5NDZSamttUzFiclZKZ2dkbkJPZWVmMlpnajVMWjVSaHhBZUhPN2VBM3lLNm5lTUZJQ3g0K1pkcVU4NWJRZW9vZVNTZFFnOGhBL3ZzNlZ3S0FWMHhJZUdaanJwREVQZ1RXM1ZDNnlqdS8xLzhVTWxIUGV1QjhOb3B3YnA2Y1UwZDl0aU9IVUJEQ0J2NFYyM0F1ZXFZQVFMNi9ramdvSFJWSjdkdVBGSHllWXc5endnc2VidVkxeTBYTmRMSFpEYXdkSjJVcFJlaGFwOC9kVHNNNmVFbGQ4N2k1UXBBdE82STFOY0xERkZRbmNUY2VOSFU5b2JYWkdrMThGN29MeXBUeTZTZjJHSlZsb2ZhTUl6U1N4OXAzNmM0bjhqK2RSN3ZCazdteXBrSVBINW1zR25zNjROeExSNnRYTCswd216RHIzaHZrUFNnK3ZsK1dyU2Z1c0F1TjR6dmtLVitQcEpZQUdtOWJsODhrbjMvYzVXN2FCbWFYcjZaVg==", "veresEnrolled": "Y", "authenticationPath": "ENROLLED", "specificationVersion": "rupay", "token": "AxjzbwSTWmCT4JORCOKv/989TSoG953CyDpxAU+Xb2/+xcVYlDjA6AAA+AGE" }, "errorInformation": { "reason": "CONSUMER_AUTHENTICATION_REQUIRED", "message": "The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction." }, "id": "6389532602277120500399", "status": "PENDING_AUTHENTICATION", "submitTimeUtc": "2021-12-08T08:47:52Z" }

Authenticating Cards Using Redirection

After verifying that a customer’s card is enrolled in a card authentication program, you must redirect the customer to the URL of the card-issuing bank’s Access Control Server (ACS URL).
The HTTP POST request web form must contain the following:
  • PAReq data
  • Termination URL (TermURL)
  • merchant data (MD)
The MD value must be posted for RuPay. If necessary, you can include it for other card brands as well.

HTML Frame Requirements

When your customers are redirected to the ACS URL, their browsers display the frame containing the password authentication page of the card-issuing bank or the option to sign up for the program (activation form).
On the page that contains the in-line frame for the ACS URL:
  • Ensure that the HTML frame is large enough to accommodate the card-issuer’s authentication or activation form, and the text that describes the process to the customer.
  • Provide a brief message outside the HTML frame to guide customers through the process. For example, “We are processing your request. Do not click the Back button or refresh the page or this transaction may be interrupted.”

HTTP Post Form

The page typically includes JavaScript that automatically posts the form. This code provides:
  • A page that receives the reply fields for the enrollment check service.
  • A form that contains the required data for the card-issuing bank.

Example: POST Form

if card is enrolled == TRUE Then variable acsURL = <acsURL reply field> variable paReq = <paReq reply field> <body onload=”document.PAEnrollForm.submit ();”> <form id=”PAEnrollForm” name=”PAEnrollForm” action=”acsURL value” method=”post” target=”paInlineFrame”> <input type=”hidden” name=”PaReq” value=”paReq value” <input type=”hidden” name=”TermUrl” value=”http:// myPAValidationPage.ext” / <input type=”hidden” name=”MD” value=”<xid value>” /> </form> else

PARes Message from the RuPay Card-Issuing Bank

The card-issuing bank sends a PARes message to your TermURL in response to the PAReq data that was sent with the web form. The PARes message is sent by using an HTTP POST request and contains the result of the requested authentication.
The signed PaRes field contains a base64-encoded string with this information:
  • PARes—Digitally signed payer authentication response message that contains the authentication result. (Note that while the field name has a lowercase “a” (PaRes), the message name has an uppercase “A” (PARes)).
  • MD—Merchant data, which must be submitted for RuPay.

Authorization Service

The authorization service format that you send for RuPay is the same used for other card types. Send the CAVV and XID in the authorization service request with the card details for
Cybersource
to process this request with the RuPay card network.
For RuPay, the e-commerce indicator returned in the validation service response must be set to
rpy
or the authorization results in an error.
For an SMS type of card, send the authorization service and capture service requests at the same time. Sending just the authorization service request for an SMS type of card causes an error.

REST Example: Authorization

Request
{ "clientReferenceInformation": { "code": "TC50171_3" }, "paymentInformation": { "card": { "number": "4111111111111111", "expirationMonth": "12", "expirationYear": "2031" } }, "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "INR" }, "billTo": { "firstName": "Sumar", "lastName": "Kumar", "address1": "Bagmane WTC", "locality": "Bangalore", "administrativeArea": "KA", "postalCode": "560048", "country": "IN", "email": "test@test.com", "phoneNumber": "7606160717" } } }
Response
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6482343863386805804004/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6482343863386805804004" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6482343863386805804004/captures" } }, "clientReferenceInformation": { "code": "TC50171_3" }, "id": "6482343863386805804004", "orderInformation": { "amountDetails": { "authorizedAmount": "102.21", "currency": "INR" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "paymentInformation": { "tokenizedCard": { "type": "001" }, "card": { "type": "001" } }, "pointOfSaleInformation": { "terminalId": "111111" }, "processorInformation": { "approvalCode": "888888", "networkTransactionId": "123456789619999", "transactionId": "123456789619999", "responseCode": "100", "avs": { "code": "X", "codeRaw": "I1" } }, "reconciliationId": "74673184C10Z9JYR", "status": "AUTHORIZED", "submitTimeUtc": "2022-03-25T18:53:06Z" }

Validating Authentication

For enrolled cards, the next step is to request the validation service to verify the authentication message (PARes) returned by the card-issuing bank.

Validation Service Request

When you make the validation request, you must:
  • Extract the PARes message from the form received from the card-issuing bank.
  • Remove any spaces created by tabs, spaces, or line breaks from the
    PaRes
    field. Do not modify any other part of the
    PaRes
    field.
  • Send the
    PaRes
    value in the signed
    PaRes
    field of the validation service to
    Cybersource
    . The response contains the validation result.
You can use the validation and card authorization services in the same request or in separate requests:
  • Same request—
    Cybersource
    automatically attempts to authorize your customer’s card if validation succeeds. The values of the required fields are added automatically to the authorization service. Do not pass any fields that
    Cybersource
    derives from the
    PaRes
    value into the request because that data could be overwritten.
  • Separate requests—You must manually include the validation result values (Payer Authentication response fields) in the authorization service request (Card Authorization request fields), which are listed in this table:
Identifier
Payer Authentication Response Field
Card Authorization Request Field
XID
consumerAuthenticationInformation. xid
consumerAuthenticationInformation. xid
E-commerce indicator
consumerAuthenticationInformation. indicator
processingInformation.commerce Indicator
CAVV
consumerAuthenticationInformation. cavv
consumerAuthenticationInformation. cavv
If you are currently passing additional card-specific values in the Payer Authentication Validate response for Visa and Mastercard, you can continue to pass them for RuPay.

Pass or Fail Message Page

After authentication is complete, redirect the customer to a page containing a success or failure message. Ensure that all messages that display to customers are accurate, complete, and that they address all possible scenarios for enrolled and non-enrolled cards. When authentication fails, a message such as this example, should be displayed to the customer:
Authentication Failed Your card issuer cannot authenticate this card. Please select another card or form of payment to complete your purchase.

REST Example: Validate Authentication Service

Request
{ "clientReferenceInformation": { "code": "testingValidate" }, "consumerAuthenticationInformation": { "signedPares": "e0NCQ2l2fSt1UVdvZGZZdmlFSldlc0kwcS9jc2hBQUVLaFcyYVBiYmgzZFh2bXVMN1RmMnlBd0g5cTdMSVdaN3M3dzFGdXB0WGJ5dkxRQ3dab3NGS0tqOStveWdaV2xaalB2bVhoNmJRaHVoVTBkYnVlbG8wdG8rV1hhcnBVZDlJYkxadnhWYi9hZlNZdjRJWHNpQzdkNklHd05TZWJOUzBKRHYxZjRMVVh3YVZiWmU3K0JiVnJuU0FvL1pZV25IK2pqaTBMcG5yQ05WaUZZa0xabzNDR210S2N5TGlNMVphNEdOdzVXNHBqSmducjJkOXNESUZuNUZhUFdlOFd5dk9SQzBNWVh5OVlDcHdHczlsbVR2dkJEZWxMSUxHMVlEUVhuRmZjVlRWTmNuVTY0dFJOeGFXSldwaU1OZFpBSTZJY0RXTXgwZ3JRRDFNVzl1TG4xUVh6aTBuN2ZqaWcyOG56ODY0YlZMbjB0Mm1hWDQ3Y2hmVFFjRU4zQ1M5dmJZcW56V0dXN3VvNkRwNnRxaTJkVzQ2bFljdyt4SVZoVGpYNnZHYUVrcG1wTTdNaXVRaStWVUlLa2lmRitzZWNnSkhjZkVONmpTSnBTSndqZkVYZnJoc20yZWlKdVVJMFpSSURpMWZJa0JiUjNFWWZPaGtjUHBRK0taaGJLOXNHakQ3OVBxUkxIdSsyYVVocXJEbzkwR01RcWZoN2NGcHhhdFMzdmpsUTNVVmRsZkMvQllQYjBLOEVxREVMSnhldTc3YjdML1hlRVZXMVhGUjJUNjNXUVp2WkRXZUY0NkNETlNwQm10TEViVlFZVFBVSWsvUkhqUDR4L2Urelp4Nk8wZlhTUlNSeTFSWEpCN0NTWFBjck1Qb0tNTGRsUFFBbXBJUT09JkNBUkRfVFlQRT0wNjE=" } }
Response
{ "clientReferenceInformation": { "code": "testingValidatie" }, "consumerAuthenticationInformation": { "indicator": "rpy", "eciRaw": "05", "cavv": "MTAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDI1MjM2", "paresStatus": "Y", "authenticationResult": "0", "xid": "ODMwOTE0MDkyNTM4", "authenticationStatusMsg": "Success", "eci": "05", "specificationVersion": "rupay", "token": "AxizLwSTVy8V2QPElwm1/989T/brWMmwAJ8wybf/YuJ58+oAvjMm" }, "id": "6330626073786876103093", "status": "AUTHENTICATION_SUCCESSFUL", "submitTimeUtc": "2021-10-01T04:30:08Z" }

Seamless Flow Payer Authentication

In Rupay Redirection Flow, the card issuer hosts an entry page on the payment terminal where the cardholder enters a one-time password (OTP). Redirecting the OTP process from the merchant to the issuer results in extra processing time and timeouts. In RuPay Seamless Flow, the merchant, who must be PCI DSS compliant, hosts the OTP entry page, providing a more seamless experience and reducing transaction timeouts. You might have to use tokenization to ensure PCI DSS compliance.

Figure:

Example of an OTP Page
To use the RuPay Seamless workflow, contact the merchant reseller or customer support to have the account configured with this service.
The OTP entry page is part of the two-factor authentication used in payer authentication for the transaction. If you are PCI DSS compliant and can host the OTP entry page, use this workflow:
  1. When payer authentication is initiated, it checks if the transaction is with RuPay. When the transaction is not with RuPay, Cardinal Direct does the payer authentication.
  2. When it is a RuPay transaction, the BIN of the issuer is checked to determine whether to use the Redirection Flow or the Seamless Flow.
  3. If the Seamless Flow is used, the Payer Authentication Enrollment service sends a call to the issuer to create and send an OTP to the cardholder.
  4. Payer Authentication prompts the merchant to display a page on the payment terminal for the cardholder to enter the OTP that is received on their phone.
  5. The OTP entered by the cardholder is authenticated with the Payer Authentication Validation service using the ID associated with the OTP that was sent to the cardholder.
  6. After the OTP is validated, the validation response returns a validation transaction context ID. Send this ID in the authorization request.

Possible Authentication Results

The following table lists the expected results based on the parameters included in your authorization request.
XID
CAVV
Authentication Value
Installment Identifier
ECI
Expected Result
Y
Y
N
N
ANY
redirection flow
N
N
Y
N
ANY
s2s flow
N
N
IGNORE
Y
R
s2s flow
IGNORE
IGNORE
IGNORE
N
R
identifier error
Y
N
Y
IGNORE
IGNORE
conflict error
N
Y
Y
IGNORE
IGNORE
conflict error
s2s flow(default)
Y
Y
N
Y
R
Y
Y
N
Y
rpy
Y
N
N
N
rpy
N
Y
N
N
rpy

One-Time Password Generation

When the cardholder is being authenticated, the Payer Authentication Enrollment service is called sending a one-time password (OTP) to the cardholder. The merchant is notified to display a merchant-branded page on the terminal where the cardholder can enter the OTP they received. This OTP is returned to the issuer for validation. This section lists the API fields used to generate and send the OTP to the cardholder, explains how to call this service, and provides samples of calling the service.
The
consumerAuthenticationInformation.authenticationTransactionId
field that is returned in the response must be included for reference when the password entered by the cardholder is sent.

Required Fields for Generating a One-Time Password in RuPay

These fields are required when generating a one-time password in RuPay:
Required for the request that resends the OTP entered by the cardholder. Without this ID, the request is treated as a request to generate a new OTP. Also used in the Payer Authentication Validation request.
Returned by Payer Authentication Enrollment service and required for the Payer Authentication Validation service request.
Rupay only. Merchant passes a valid value (01-07) to indicate the transaction flow. Possible values are:
01
: NW – Transaction performed at domestic merchant.
02
: TW – Transaction performed at domestic merchant along with token provisioning.
03
: IT – Transaction performed at international merchant.
04
: AT – Authentication transaction only.
05
: AW – Authentication transaction for provisioning.
06
: DI – Domestic InApp transaction.
07
: II – International InApp transaction.

REST Example: One-Time Password Generation

Request
{ "clientReferenceInformation":{ "code":"test" }, "orderInformation":{ "billTo":{ "firstName":"Suman", "lastName":"Kumar", "address1":"Bagmane WTC", "address2":"Doddenakundi", "locality":"Bangalore", "country":"IN", "administrativeArea":"KA", "postalCode":"560048", "email":"test@domain.com", "phoneNumber":"7606160717" }, "amountDetails":{ "totalAmount":"100.00", "currency":"INR" } }, "paymentInformation":{ "card":{ "type":"061", "expirationMonth":"12", "expirationYear":"2025", "number":"50823012264085197", "securityCode" :"123" } }, "deviceInformation" :{ "httpAcceptBrowserValue" : "accept", "userAgentBrowserValue" : "user", "ipAddress":"10.0.0.1" } }
Response
{ "clientReferenceInformation": { "code": "test" }, "consumerAuthenticationInformation": { "validityPeriod": "05", "authenticationTransactionContext": "100000000000000000000000025253", "authenticationTransactionId": "00000012345330095100258805", "veresEnrolled": "Y", "authenticationPath": "ENROLLED", "authenticationType": "20", "specificationVersion": "rupay", "token": "AxjzbwSTWc547SrcOWki/989TSoGaw7iyDpxAUxXb2/+xcVYlDjA/AAA+wGp" }, "errorInformation": { "reason": "CONSUMER_AUTHENTICATION_REQUIRED", "message": "The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction." }, "id": "6379004607567152900386", "status": "PENDING_AUTHENTICATION", "submitTimeUtc": "2021-11-26T04:21:01Z" }

REST Example: One-Time Password Generation (with Token)

Request
{ "clientReferenceInformation":{ "code":"test" }, "orderInformation":{ "billTo":{ "firstName":"Suman", "lastName":"Kumar", "address1":"Bagmane WTC", "address2":"Doddenakundi", "locality":"Bangalore", "country":"IN", "administrativeArea":"KA", "postalCode":"560048", "email":"test@domain.com", "phoneNumber":"7606160717" }, "amountDetails":{ "totalAmount":"100.00", "currency":"INR" } }, "paymentInformation":{ "tokenizedCard": { "transactionType":"1", "cryptogram":"AxjzbwSTWXrGh42hi2ugABEBTSoX+EHukDpxAUqXb8n+Wcc3UiIJAPAAhhO5", "number":"50823012264085197", "expirationMonth": "11", "expirationYear": "2021", "securityCode" :"123", "type":"061" } }, "deviceInformation" :{ "httpAcceptBrowserValue" : "accept", "userAgentBrowserValue" : "user", "ipAddress":"10.0.0.1" } }
Response
{ "clientReferenceInformation": { "code": "test" }, "consumerAuthenticationInformation": { "validityPeriod": "05", "authenticationTransactionContext": "100000000000000000000000025253", "authenticationTransactionId": "00000012345330104948258905", "veresEnrolled": "Y", "authenticationPath": "ENROLLED", "authenticationType": "20", "specificationVersion": "rupay", "token": "AxjzbwSTWc72QPm3yK4i/989TSoGbqdyyDpxAUxXb2/+xcVYlDjA/AAAXgKG" }, "errorInformation": { "reason": "CONSUMER_AUTHENTICATION_REQUIRED", "message": "The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction." }, "id": "6379039884087153700386", "status": "PENDING_AUTHENTICATION", "submitTimeUtc": "2021-11-26T05:19:48Z" } }

One-Time Password Resend

After the cardholder receives the OTP on their mobile phone, they enter it into the form that is displayed on the merchant terminal. After entering the password, the cardholder presses
Enter
and the password is returned to the issuer to verify that the OTP matches what was sent to the cardholder. When the response from the issuer is an invalid or incorrect OTP, resend OTP can be triggered. The request includes the original
consumerAuthenticationInformation.authenticationTransactionId
that was returned in the Payer Authentication Enrollment response. The transaction ID enables the matching of the original OTP that was sent to the cardholder with the OTP that the cardholder entered into the terminal. After the OTP match is made, the cardholder is authenticated and can then be validated.
The process for running this service is the same one used to generate the original OTP except for including the ID generated by the response. Refer to the One-Time Password Generation section for a list of required and optional fields used in Payer Authentication Enrollment when resending the password to the issuer.

Required Field for Resending a One-Time Password in RuPay

This field is required for RuPay when returning the one-time password to the issuer:
consumerAuthenticationInformation.authenticationTransactionId
You must include this field in the authorization request.

Response Field for Checking Enrollment in Payer Authentication

This field is required for RuPay when responding to the Payer Authentication Enrollment service request:
consumerAuthenticationInformation.validityPeriod
Supported only on RuPay for the Payer Authentication seamless flow.

REST Example: One-Time Password Resend

Request
{ "clientReferenceInformation":{ "code":"test" }, "orderInformation":{ "billTo":{ "firstName":"Suman", "lastName":"Kumar", "address1":"Bagmane WTC", "address2":"Doddenakundi", "locality":"Bangalore", "country":"IN", "administrativeArea":"KA", "postalCode":"560048", "email":"test@domain.com", "phoneNumber":"7606160717" }, "amountDetails":{ "totalAmount":"100.00", "currency":"INR" } }, "paymentInformation":{ "card":{ "type":"061", "expirationMonth":"12", "expirationYear":"2025", "number":"50823012264085197", "securityCode" :"123" } }, "consumerAuthenticationInformation":{ "authenticationTransactionId" :"00000012345330094331258803" }, "deviceInformation" :{ "httpAcceptBrowserValue" : "accept", "userAgentBrowserValue" : "user", "ipAddress":"10.0.0.1" } }
Response
{ "clientReferenceInformation": { "code": "test" }, "consumerAuthenticationInformation": { "validityPeriod": "05", "authenticationTransactionContext": "100000000000000000000000025253", "authenticationTransactionId": "00000012345330094331258803", "veresEnrolled": "Y", "authenticationPath": "ENROLLED", "authenticationType": "20", "specificationVersion": "rupay", "token": "AxjzbwSTWc6CHxEpkK5i/989TSoGaw7yyDpxAUxXb2/+xcVYlDjA/AAABgHE" }, "errorInformation": { "reason": "CONSUMER_AUTHENTICATION_REQUIRED", "message": "The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction." }, "id": "6379007195707153100386", "status": "PENDING_AUTHENTICATION", "submitTimeUtc": "2021-11-26T04:25:19Z" }

REST Example: One-Time Password Resend (with Token)

Request
{ "clientReferenceInformation":{ "code":"test" }, "orderInformation":{ "billTo":{ "firstName":"Suman", "lastName":"Kumar", "address1":"Bagmane WTC", "address2":"Doddenakundi", "locality":"Bangalore", "country":"IN", "administrativeArea":"KA", "postalCode":"560048", "email":"test@domain.com", "phoneNumber":"7606160717" }, "amountDetails":{ "totalAmount":"100.00", "currency":"INR" } }, "paymentInformation":{ "tokenizedCard": { "transactionType":"1", "cryptogram":"AxjzbwSTWXrGh42hi2ugABEBTSoX+EHukDpxAUqXb8n+Wcc3UiIJAPAAhhO5", "number":"50823012264085197", "expirationMonth": "11", "expirationYear": "2021", "securityCode" :"123", "type":"061" } }, "consumerAuthenticationInformation":{ "authenticationTransactionId" :"00000012345330094331258803" }, "deviceInformation" :{ "httpAcceptBrowserValue" : "accept", "userAgentBrowserValue" : "user", "ipAddress":"10.0.0.1" } }
Response
{ "clientReferenceInformation": { "code": "test" }, "consumerAuthenticationInformation": { "validityPeriod": "05", "authenticationTransactionContext": "100000000000000000000000025253", "authenticationTransactionId": "00000012345330094331258803", "veresEnrolled": "Y", "authenticationPath": "ENROLLED", "authenticationType": "20", "specificationVersion": "rupay", "token": "AxjzbwSTWc8FjykV5njC/989TSoGbqd6yDpxAUxXb2/+xcVYlDjA/AAAVgJm" }, "errorInformation": { "reason": "CONSUMER_AUTHENTICATION_REQUIRED", "message": "The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction." }, "id": "6379044192177153800386", "status": "PENDING_AUTHENTICATION", "submitTimeUtc": "2021-11-26T05:26:59Z" }

One-Time Password Validation

If the OTP entered by the cardholder matches the OTP that was sent, the cardholder is authenticated and is ready to be validated so the transaction can be authorized. The
consumerAuthenticationInformation.authenticationTransactionId
field that is used during payer authentication is also used during validation to associate the validation with the proper Payer Authentication Enrollment call.
Note that no token or card number is necessary during validation of an OTP so no example with token is provided in this section.

Required Fields for Validating a One-Time Password in RuPay

These fields are required for RuPay when validating the one-time password the customer sends:
This value must be the same value received in the Payer Authentication Enrollment response.
The same value returned in the Payer Authentication Enrollment response must be used as the
consumerAuthenticationInformation.authenticationTransactionId
in the Payer Authentication Validate request.
Merchant must send the OTP entered by the cardholder as part of this request field in Payer Authentication Validate request.
Merchant must pass the customer IP address as part of this field.

Response Fields for Payer Authentication Validation in RuPay

These fields are required for RuPay when responding to the Payer Authentication Validation service request:
consumerAuthenticationInformation.authenticationTransactionContextId
This field contains the same value passed by the merchant in Payer Authentication Validation request as part of
consumerAuthenticationInformation.authenticationTransactionId
.
consumerAuthenticationInformation.authenticationTransactionId
You must pass this field in the authorization request.
consumerAuthenticationInformation.transactionToken
This token is returned in the Payer Authentication Validation OTP response. While required for customer initiated transactions, do not include this field during merchant initiated Standing Instructions transactions that use the
installmentInformation.identifier
.

Example: One-Time Password Validation (No Token)

Request
{ "clientReferenceInformation": { "code": "testingValidatie" }, "consumerAuthenticationInformation": { "authenticationTransactionId":"00000012345298152551253625", "authenticationTransactionContext":"1000000000000000000000000252531", "otpToken":"123456" }, "deviceInformation": { "ipAddress":"10.0.0.1" } }
Response
{ "clientReferenceInformation": { "code": "testingValidatie" }, "consumerAuthenticationInformation": { "indicator": "rpy", "eciRaw": "05", "paresStatus": "Y", "authenticationResult": "0", "transactionToken": "MDEwMTIzNTQ2NzA5YWJjZGVmMDEyMzU0NjcwOWFiY2RlZjAxMjM1NDY3MDlhYmNkZWYwMTIzNTQ2NzA5YWJjZGVm100403210110040321011004032101", "authenticationTransactionContext": "100000000000000000000000025253", "authenticationTransactionId": "00000012345298152551253625", "authenticationStatusMsg": "Success", "eci": "05", "specificationVersion": "rupay", "token": "AxizLwSTWc6HUJD/TcUC/989TSoGbqdIAUxhk2/+xcVYlDjAMA1m" }, "id": "6379008657507153200386", "status": "AUTHENTICATION_SUCCESSFUL", "submitTimeUtc": "2021-11-26T04:27:46Z" }

Standing Instructions

A Standing Instruction (SI) is an agreement between the customer, the merchant, and the acquirer. The merchant sets up a fixed payment to automatically charge the customer's card account at regular intervals and notifies the acquirer of the billing arrangement. The cardholder enters their card information and configures when the payments should occur. The payment interval can be specified as a day of the week or a date during the month. A notice of the amount and the date of the transaction is sent to the customer and the issuer before the transaction happens so that the customer retains the opportunity to decline the transaction. This process of alerting the customer to an impending transaction is called
intimation
. The customer can cancel a SI transaction by contacting the merchant or the issuer.
There are three aspects to a SI transaction:
  • Registration: The customer registers their payment information and configures the parameters of the SI transactions so that the payments can be automatically processed at the stipulated time. By configuring the payment parameters for the first SI transaction, subsequent SI transactions do not require the cardholder to enter any payment information. With intimation, the cardholder must approve of each transaction before it occurs.
  • Modification: The cardholder information and payment parameters configured for the SI transactions can be modified at any time. Before any cardholder information or the existing parameters configured for the SI transaction can be modified, two factor authentication is used to verify the cardholder's identity .
  • Deregistration: Cardholder information and payment parameters for SI transactions can be deregistered (or cancelled) at any time. To end the future payments scheduled with a SI transaction, deregister the cardholder.
For each aspect of a SI transaction, the cardholder goes through payer authentication to verify that the cardholder is enrolled in a payer authentication program and then the cardholder's identity is validated using two factor authentication. After the SI transaction is initially set up, payer authentication is not required for subsequent installments unless the SI is modified.

Standing Instruction Registration

During registration, the merchant uses the information provided by the cardholder to register with the issuer for SI transactions through RuPay. During registration, the cardholder is authenticated. Once the cardholder is authenticated, subsequent transactions do not require authentication. After registration, authentication is only required again when the billing agreement is modified or cancelled (deregistered). The registration can occur at two different times:
  • Before any SI transactions start: Cardholder sets up the SI transaction to start at a future time, often 30 days later. The customer can be sent a payment link or go to a payment portal to initiate the first payment. The customer must verify their identity with two factor authentication.
  • At the time of the first SI transaction: Cardholder makes the first payment when setting up the SI transactions. Parameters for future payments are configured and the customer provides consent for the first payment. Payer authentication is only done for the first SI transaction. Subsequent SI transactions do not require payer authentication unless the original SI agreement is modified.
When registering a customer for SI transactions, the merchant collects information to configure the parameters of the transactions. The cardholder is assigned a SI registration ID that links to the information provided by the cardholder. This information includes:
  • Number of SI transactions
  • Mode of communication with the customer (email or text)
  • Frequency
  • Minimum and maximum amount limits for a transaction
  • Transaction amount
  • Preferred date for transaction
While the specific amount and date of the transaction might be unavailable at the time of registration, the merchant always intimates the amount and date to the customer by text or email before each SI transaction occurs.
After the SI transaction is set up, each SI transactions is charged by the merchant on the preferred date. Twenty-four hours before each SI transaction occurs, the merchant intimates to the customer, the amount and date of the pending transaction. The amount charged must be within the minimum and maximum amount values configured by the cardholder during registration. If no maximum value was specified, 5,000 rupees is the maximum value.

Required Fields for Standing Instruction Registration

These fields are required when registering for a SI transaction:
installmentInformation.alertPreference
Only used with RuPay for the payer authentication seamless flow.
Only used with RuPay for the payer authentication seamless flow.
installmentInformation.lastInstallmentDate
Only used with RuPay for the payer authentication seamless flow.
installmentInformation.maxAmount
Only used with RuPay for the payer authentication seamless flow.
installmentInformation.minAmount
Only used with RuPay for the payer authentication seamless flow.
Only used with RuPay for the payer authentication seamless flow.
installmentInformation.preferredDay
Only used with RuPay for the payer authentication seamless flow.
Only used with RuPay for the payer authentication seamless flow.
Only used with RuPay for the payer authentication seamless flow.

Optional Fields for Standing Instruction Registration

The following fields are optional when completing registration for a SI transaction:

REST Example: Registering a Standing Instruction

Request
{ "clientReferenceInformation":{ "code":"test" }, "orderInformation":{ "billTo":{ "firstName":"Suman", "lastName":"Kumar", "address1":"Bagmane WTC", "address2":"Doddenakundi", "locality":"Bangalore", "country":"IN", "administrativeArea":"KA", "postalCode":"560048", "email":"test@domain.com", "phoneNumber":"7606160717" }, "amountDetails":{ "totalAmount":"100.00", "currency":"INR" } }, "paymentInformation":{ "card":{ "type":"061", "expirationMonth":"12", "expirationYear":"2025", "number":"5082301226408XXXX", "securityCode" :"123" } }, "deviceInformation" :{ "httpAcceptBrowserValue" : "accept", "userAgentBrowserValue" : "user", "ipAddress":"10.0.0.1" }, "installmentInformation": { "paymentType": "1", "firstInstallmentDate": "01012023", "lastInstallmentDate": "01012024", "totalCount": "12", "minAmount" :"10", "maxAmount" :"100", "preferredDay":"05", "frequency": "1", "alertPreference":"SMS", "sequence": "2" }, }
Successful Response
{ "clientReferenceInformation": { "code": "test" }, "consumerAuthenticationInformation": { "validityPeriod": "05", "authenticationTransactionContext": "100000000000000000000000025253", "authenticationTransactionId": "00000012345334130405260122", "veresEnrolled": "Y", "authenticationPath": "ENROLLED", "authenticationType": "20", "specificationVersion": "rupay", "token": "AxjzbwSTWgAKsBvnFT5i/989TSoGg2p6yDpxAU1Xb2/+xcVYlDjA/AAABgHI" }, "errorInformation": { "reason": "CONSUMER_AUTHENTICATION_REQUIRED", "message": "The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction." }, "id": "6382576457887159500386", "status": "PENDING_AUTHENTICATION", "submitTimeUtc": "2023-11-30T07:34:06Z" }

REST Example: Registering a Standing Instruction (with Token)

Request
{ "clientReferenceInformation":{ "code":"test" }, "orderInformation":{ "billTo":{ "firstName":"Suman", "lastName":"Kumar", "address1":"Bagmane WTC", "address2":"Doddenakundi", "locality":"Bangalore", "country":"IN", "administrativeArea":"KA", "postalCode":"560048", "email":"test@domain.com", "phoneNumber":"7606160717" }, "amountDetails":{ "totalAmount":"100.00", "currency":"INR" } }, "paymentInformation":{ "tokenizedCard": { "transactionType":"1", "cryptogram":"AxjzbwSTWXrGh42hi2ugABEBTSoX+EHukDpxAUqXb8n+Wcc3UiIJAPAAhhO5", "type":"061", "expirationMonth":"12", "expirationYear":"2025", "number":"5082301226408XXXX", "securityCode" :"123" } }, "deviceInformation" :{ "httpAcceptBrowserValue" : "accept", "userAgentBrowserValue" : "user", "ipAddress":"10.0.0.1" }, "installmentInformation": { "paymentType": "1", "firstInstallmentDate": "01012023", "lastInstallmentDate": "01012024", "totalCount": "12", "minAmount" :"10", "maxAmount" :"100", "preferredDay":"05", "frequency": "1", "alertPreference":"SMS", "sequence": "2" }, }
Successful Response
{ "clientReferenceInformation": { "code": "test" }, "consumerAuthenticationInformation": { "validityPeriod": "05", "authenticationTransactionContext": "100000000000000000000000025253", "authenticationTransactionId": "00000012345334130405260122", "veresEnrolled": "Y", "authenticationPath": "ENROLLED", "authenticationType": "20", "specificationVersion": "rupay", "token": "AxjzbwSTWgAKsBvnFT5i/989TSoGg2p6yDpxAU1Xb2/+xcVYlDjA/AAABgHI" }, "errorInformation": { "reason": "CONSUMER_AUTHENTICATION_REQUIRED", "message": "The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction." }, "id": "6382576457887159500386", "status": "PENDING_AUTHENTICATION", "submitTimeUtc": "2022-11-30T07:34:06Z" }

Standing Instruction Modification

During SI registration, customer information and payment parameters are set up for subsequent transactions. This transaction configuration remains in effect until the customer modifies the payment parameters or until the specified number of payments is reached. Two factor authentication is used to verify the cardholder's identity before any cardholder information or the parameters of a SI transaction are modified.

Required Fields for Standing Instruction Modification

These fields are required when modifying a SI agreement:
installmentInformation.alertPreference
Only used with RuPay for the payer authentication seamless flow.
Only used with RuPay for the payer authentication seamless flow.
Received in Registration response and used in subsequent SI transactions.
installmentInformation.lastInstallmentDate
Only used with RuPay for the payer authentication seamless flow.
installmentInformation.maxAmount
Only used with RuPay for the payer authentication seamless flow.
installmentInformation.minAmount
Only used with RuPay for the payer authentication seamless flow.
installmentInformation.preferredDay
Only used with RuPay for the payer authentication seamless flow.
Only used with RuPay for the payer authentication seamless flow.
Only used with RuPay for the payer authentication seamless flow.
merchantInformation.administrativeArea
If not included, value is pulled from merchant profile.
When not included, the value is pulled from merchant profile.
When not included, the value is pulled from merchant profile.
When not included, the value is pulled from merchant profile.
When not included, the value is pulled from merchant profile.
When not included, the value is pulled from merchant profile.
paymentInformation.tokenizedCard.number

Optional Fields for Standing Instruction Modification

This field is optional when modifying a SI transaction:
aggregatorInformation.submerchant.merchantId
Optional for redirection flow.
Optional for redirection flow.
Optional for redirection flow.
Optional for redirection flow.
Optional for redirection flow.
Optional for redirection flow.
paymentInformation.tokenizedCard.number
Optional for redirection flow.
Optional for redirection flow.

REST Example: Modifying a Standing Instruction

{ "clientReferenceInformation":{ "code":"test" }, "orderInformation":{ "billTo":{ "firstName":"Suman", "lastName":"Kumar", "address1":"Bagmane WTC", "address2":"Doddenakundi", "locality":"Bangalore", "country":"IN", "administrativeArea":"KA", "postalCode":"560048", "email":"test@domain.com", "phoneNumber":"7606160717" }, "amountDetails":{ "totalAmount":"100.00", "currency":"INR" } }, "paymentInformation":{ "card":{ "type":"061", "expirationMonth":"12", "expirationYear":"2025", "number":"5082301226408XXXX", "securityCode" :"123" } }, "installmentInformation": { "identifier": "abcde1345", "paymentType": "1", "firstInstallmentDate": "01012023", "lastInstallmentDate": "01012024", "totalCount": "12", "minAmount" :"10", "maxAmount" :"100", "preferredDay":"05", "frequency": "1", "alertPreference":"SMS", "sequence": "2" }, "deviceInformation" :{ "httpAcceptBrowserValue" : "http", "userAgentBrowserValue" : "user", "ipAddress":"10.0.0.1" } }
Successful Response
{ "clientReferenceInformation": { "code": "test" }, "consumerAuthenticationInformation": { "validityPeriod": "05", "authenticationTransactionContext": "100000000000000000000000025253", "authenticationTransactionId": "00000012345342141537264106", "veresEnrolled": "Y", "authenticationPath": "ENROLLED", "authenticationType": "20", "specificationVersion": "rupay", "token": "AxjzbwSTWmCPKLjUiOgP/989TSoG9526yDpxAU+Xb2/+xcVYlDjA/AAAXwKK" }, "errorInformation": { "reason": "CONSUMER_AUTHENTICATION_REQUIRED", "message": "The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction." }, "id": "6389531274227120400399", "status": "PENDING_AUTHENTICATION", "submitTimeUtc": "2023-12-08T08:45:37Z" }

REST Example: Modifying a Standing Instruction (with Token)

Request
POST
https://api.cybersource.com
/pts/v2/billing-agreements/:{id}
{ "clientReferenceInformation":{ "code":"cybs_test" }, "orderInformation":{ "billTo":{ "firstName":"Suman", "lastName":"Kumar", "address1":"Bagmane WTC", "address2":"Doddenakundi", "locality":"Bangalore", "country":"IN", "administrativeArea":"KA", "postalCode":"560048", "email":"test@domain.com", "phoneNumber":"7606160717" }, "amountDetails":{ "totalAmount":"100.00", "currency":"INR" } }, "paymentInformation":{ "tokenizedCard": { "transactionType":"1", "cryptogram":"AxjzbwSTWXrGh42hi2ugABEBTSoX+EHukDpxAUqXb8n+Wcc3UiIJAPAAhhO5", "type":"061", "expirationMonth":"12", "expirationYear":"2025", "number":"5082301226408XXXX", "securityCode" :"123" } }, "installmentInformation": { "identifier": "abcde1345", "paymentType": "1", "firstInstallmentDate": "01012023", "lastInstallmentDate": "01012024", "totalCount": "12", "minAmount" :"10", "maxAmount" :"100", "preferredDay":"05", "frequency": "1", "alertPreference":"SMS", "sequence": "2" }, "deviceInformation" :{ "httpAcceptBrowserValue" : "http", "userAgentBrowserValue" : "user", "ipAddress":"10.0.0.1" } }
Successful Response
{ "clientReferenceInformation": { "code": "cybs_test" }, "consumerAuthenticationInformation": { "validityPeriod": "05", "authenticationTransactionContext": "100000000000000000000000025253", "authenticationTransactionId": "00000012345342141537264106", "veresEnrolled": "Y", "authenticationPath": "ENROLLED", "authenticationType": "20", "specificationVersion": "rupay", "token": "AxjzbwSTWmCPKLjUiOgP/989TSoG9526yDpxAU+Xb2/+xcVYlDjA/AAAXwKK" }, "errorInformation": { "reason": "CONSUMER_AUTHENTICATION_REQUIRED", "message": "The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction." }, "id": "6389531274227120400399", "status": "PENDING_AUTHENTICATION", "submitTimeUtc": "2023-12-08T08:45:37Z" }

Standing Instruction Deregistration (Cancellation)

Cardholder information and payment parameters for SI transactions can be deregistered (or cancelled) at any time. Deregister the cardholder when the cardholder wants to end subsequent SI transactions. After the last scheduled transaction, any associated tokens expire.

Required Fields for Deregistering a Standing Instruction

REST Example: Deregistering a Standing Instruction

Request
{ "clientReferenceInformation":{ "code":"cybs_test" }, "orderInformation":{ "billTo":{ "firstName":"Suman", "lastName":"Kumar", "address1":"Bagmane WTC", "address2":"Doddenakundi", "locality":"Bangalore", "country":"IN", "administrativeArea":"KA", "postalCode":"560048", "email":"test@domain.com", "phoneNumber":"7606160717" }, "amountDetails":{ "totalAmount":"100.00", "currency":"INR" } }, "paymentInformation":{ "card":{ "type":"061", "expirationMonth":"12", "expirationYear":"2025", "number":"5082301226408XXXX", "securityCode" :"123" } }, "installmentInformation": { "identifier": "abcde1345", "paymentType": "1", "firstInstallmentDate": "01012023", "lastInstallmentDate": "01012024", "totalCount": "12", "minAmount" :"10", "maxAmount" :"100", "preferredDay":"05", "frequency": "1", "alertPreference":"SMS", "sequence": "2" }, "deviceInformation" :{ "httpAcceptBrowserValue" : "http", "userAgentBrowserValue" : "user", "ipAddress":"10.0.0.1" } }
Successful Response
{ "clientReferenceInformation": { "code": "cybs_test" }, "consumerAuthenticationInformation": { "validityPeriod": "05", "authenticationTransactionContext": "100000000000000000000000025253", "authenticationTransactionId": "00000012345342141537264106", "veresEnrolled": "Y", "authenticationPath": "ENROLLED", "authenticationType": "20", "specificationVersion": "rupay", "token": "AxjzbwSTWmCPKLjUiOgP/989TSoG9526yDpxAU+Xb2/+xcVYlDjA/AAAXwKK" }, "errorInformation": { "reason": "CONSUMER_AUTHENTICATION_REQUIRED", "message": "The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction." }, "id": "6389531274227120400399", "status": "PENDING_AUTHENTICATION", "submitTimeUtc": "2022-12-08T08:45:37Z" } }

REST Example: Deregistering a Standing Instruction (with Token)

Request
POST
https://api.cybersource.com
/pts/v2/billing-agreements/:{id}
{ "clientReferenceInformation":{ "code":"cybs_test" }, "orderInformation":{ "billTo":{ "firstName":"Suman", "lastName":"Kumar", "address1":"Bagmane WTC", "address2":"Doddenakundi", "locality":"Bangalore", "country":"IN", "administrativeArea":"KA", "postalCode":"560048", "email":"test@domain.com", "phoneNumber":"7606160717" }, "amountDetails":{ "totalAmount":"100.00", "currency":"INR" } }, "paymentInformation":{ "tokenizedCard": { "transactionType":"1", "cryptogram":"AxjzbwSTWXrGh42hi2ugABEBTSoX+EHukDpxAUqXb8n+Wcc3UiIJAPAAhhO5", "type":"061", "expirationMonth":"12", "expirationYear":"2025", "number":"5082301226408XXXX", "securityCode" :"123" } }, "installmentInformation": { "identifier": "abcde1345", "paymentType": "1", "firstInstallmentDate": "01012023", "lastInstallmentDate": "01012024", "totalCount": "12", "minAmount" :"10", "maxAmount" :"100", "preferredDay":"05", "frequency": "1", "alertPreference":"SMS", "sequence": "2" }, "deviceInformation" :{ "httpAcceptBrowserValue" : "http", "userAgentBrowserValue" : "user", "ipAddress":"10.0.0.1" } }
Successful Response
{ "clientReferenceInformation": { "code": "cybs_test" }, "consumerAuthenticationInformation": { "validityPeriod": "05", "authenticationTransactionContext": "100000000000000000000000025253", "authenticationTransactionId": "00000012345342141537264106", "veresEnrolled": "Y", "authenticationPath": "ENROLLED", "authenticationType": "20", "specificationVersion": "rupay", "token": "AxjzbwSTWmCPKLjUiOgP/989TSoG9526yDpxAU+Xb2/+xcVYlDjA/AAAXwKK" }, "errorInformation": { "reason": "CONSUMER_AUTHENTICATION_REQUIRED", "message": "The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction." }, "id": "6389531274227120400399", "status": "PENDING_AUTHENTICATION", "submitTimeUtc": "2022-12-08T08:45:37Z" }

Completion of Standing Instructions

Completion of the SI occurs when all of the transactions that were scheduled during the interval of time specified in the agreement process successfully. The completion is handled like previous SI transactions except it is the last transaction. No more transactions will occur because the time period scheduled for the payments to occur has ended. If the customer wants to continue receiving the service covered by the SI, the SI agreement should be modified to extend the payment interval.

Required Fields for Standing Instruction Completion

The following fields are required when completing registration for a SI transaction:
deviceInformation.ipAddress
Only used with RuPay for the payer authentication seamless flow.
deviceInformation.userAgentBrowserValue
Only used with RuPay for the payer authentication seamless flow.
merchantInformation.administrativeArea
When not included, the value is pulled from merchant profile.
merchantInformation.categoryCode
When not included, the value is pulled from merchant profile.
merchantInformation.merchantDescriptor.contact
When not included, the value is pulled from merchant profile.
merchantInformation.merchantDescriptor.locality
When not included, the value is pulled from merchant profile.
merchantInformation.merchantDescriptor.name
When not included, the value is pulled from merchant profile.
merchantInformation.merchantDescriptor.postalCode
When not included, the value is pulled from merchant profile.
merchantInformation.transactionLocalDateTime
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.securityCode
paymentInstrument.card.accountNumber
paymentInformation.tokenizedCard.expirationMonth
Required if using tokens.
paymentInformation.tokenizedCard.expirationYear
Required when using tokens
paymentInformation.tokenizedCard.securityCode
Required when using tokens
paymentInformation.tokenizedCard.transactionType
Required when using tokens
processingInformation.commerceIndicator

REST Example: Completing a Standing Instruction

Request
{ "deviceInformation": { "httpAcceptBrowserValue": "http", "userAgentBrowserValue": "safari", "ipAddress": "10.10.10.10" }, "consumerAuthenticationInformation": { "transactionFlowIndicator": "2" }, "processingInformation": { "commerceIndicator": "rpy", "actionList": [ "CONSUMER_AUTHENTICATION" ] }, "aggregatorInformation": { "subMerchant": { "name": "rupay" }, "name": "aggregatorname" }, "orderInformation": { "billTo": { "country": "IN", "firstName": "Krishna", "lastName": "CYBS", "phoneNumber": "9999999999", "address1": "201 S. Division St.", "district": "BLR", "postalCode": "560048", "locality": "NPCI", "company": "Visa", "administrativeArea": "MI", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "0.00", "currency": "INR" } }, "merchantInformation": { "transactionLocalDateTime": "20211216124549", "categoryCode": "1234", "merchantDescriptor": { "country": "IN", "contact": "1234567890", "postalCode": "213213", "locality": "local", "administrativeArea": "TN" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "608090618XXXX", "securityCode": "123", "expirationMonth": "12", "type": "061" } }, "installmentInformation": { "minAmount": "10", "sequence": "2", "firstInstallmentDate": "01122023", "alertPreference": "SMS", "lastInstallmentDate": "01012025", "preferredDay": "05", "maxAmount": "100", "totalCount": "24", "frequency": "1", "paymentType": "1" } }
Successful Response
{ "id": "6853506446826005503878", "installmentInformation": { "identifier": "1000000000" }, "processorInformation": { "responseCode": "00" }, "status": "SUCCESS", "submitTimeUtc": "2023-05-29T08:57:25Z" }

Standing Instructions Intimation

You must intimate the customer and the issuer of the pending SI transaction 24 hours before the transaction occurs. Notification to the customer is by email, text, or both, as specified during registration. In the notification, you must provide the amount and date of the transaction. The amount must be within the minimum and maximum ranges of value that were configured during registration. The transaction cannot exceed the maximum value of 5,000 rupees that is mandated by the Reserve Bank of India (RBI).
Intimation does not require any type of payer authentication since the customer was authenticated during registration and the card information is already on file.

Required Fields

These fields are required when intimating a pending SI transaction:
installmentInformation.alertPreference
installmentInformation.preferredDay
paymentInstrument.card.number
Required for tokenized transactions.
tokenizedCard.cryptogram
Required for tokenized transactions.

REST Example: Intimating a Standing Instruction

Request
{ "orderInformation": { "amountDetails": { "totalAmount": "00", "currency": "INR" } }, "merchantInformation": { "transactionLocalDateTime": "20211216124549" }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "508230288XXXX", "securityCode": "123", "expirationMonth": "12", "type": "061" } }, "installmentInformation": { "identifier": "1000000000", "minAmount": "100", "sequence": "2", "firstInstallmentDate": "2111", "alertPreference": "SMS", "lastInstallmentDate": "3110", "preferredDay": "1", "maxAmount": "1000", "paymentType": "1" } }
Successful Response
{ "id": "6853506446826005503878", "installmentInformation": { "identifier": "1000000000" }, "processorInformation": { "responseCode": "00" }, "status": "SUCCESS", "submitTimeUtc": "2023-05-29T08:57:25Z" }

Optional Fields for Generating a One-Time Password

Standing Instruction Authorization

When the first transaction occurs when the SI is registered, authorization occurs as payer authentication is done.

Optional Fields for Standing Instruction Authorization

REST Example: Authorizing a Standing Instruction

Request
{ "clientReferenceInformation": { "code": "RTS-Auth" }, "processingInformation": { "commerceIndicator": "rpy" }, "orderInformation": { "billTo": { "country": "IN", "lastName": "VDP", "firstName": "RTS", "address2": "test", "address1": "US", "locality": "48104 2201", "administrativeArea": "TN", "phoneNumber": "9114456621", "postalCode": "411040", "district": "MI", "buildingNumber": "123", "company": "Visa", "email": "test@yyyy.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "inr" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "508230288XXXX", "securityCode": "123", "securityCodeIndicator": "1", "expirationMonth": "12", "type": "061" } }, "payerAuthentication": { "authenticationValue": "jhfgjhgdfhgsdfhgsdfh" }, "deviceInformation": { "httpAcceptContent": "gsfgfdg", "ipAddress": "10.10.10.10", "userAgent": "aa" }, "aggregatorInformation": { "subMerchant": { "name": "rupay" } }, "merchantInformation": { "merchantDescriptor": { "administrativeArea": "AN", "postalCode": "123324" } }, "consumerAuthenticationInformation": { "transactionToken": "MTAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDI1MjM2" } }
Successful Response
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6385272861347128228688/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6385272861347128228688" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6385272861347128228688/captures" } }, "clientReferenceInformation": { "code": "RTS-Auth" }, "id": "6385272861347128228688", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "inr" } }, "paymentAccountInformation": { "card": { "brandName": "RUPAY", "type": "061" } }, "paymentInformation": { "tokenizedCard": { "type": "061" }, "card": { "type": "061" } }, "processorInformation": { "approvalCode": "235426", "networkTransactionId": "100000000000000000000000025253", "transactionId": "100000000000000000000000025253", "responseCode": "00", "avs": { "code": "2" } }, "submitTimeUtc": "2023-12-03T10:28:06Z" }

REST Example: Authorization of a Standing Instruction Transaction (with Token)

Request
{ "clientReferenceInformation": { "code": "RTS-Auth" }, "processingInformation": { "commerceIndicator": "RECURRING" }, "orderInformation": { "billTo": { "country": "US", "lastName": "VDP", "address2": "test", "address1": "test", "postalCode": "560066", "locality": "Ann Arbor", "administrativeArea": "MI", "firstName": "RTS", "phoneNumber": "999999999", "district": "MI", "buildingNumber": "123", "company": "Visa", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100.00", "currency": "inr" } }, "paymentInformation": { "tokenizedCard": { "number": "508230288XXXX", "transactionType": "1", "expirationYear": "2031", "securityCode": "123", "securityCodeIndicator": "1", "expirationMonth": "12", "cryptogram": "abcdefgh" } }, "consumerAuthenticationInformation": { "transactionToken": "MTAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDI1MjM2" }, "installmentInformation": { "identifier": "123", "paymentType": "1" }, "deviceInformation": { "ipAddress": "10.10.10.10", "httpAcceptContent": "text/html", "userAgent" : "Mozilla/5.0 (compatible; MSIE 9.0; Windows Phone OS 7.5; Trident/5.0; IEMobile/9.0)" }, "aggregatorInformation": { "subMerchant": { "name": "rupay" } }, "merchantInformation": { "merchantDescriptor": { "administrativeArea": "AN", "postalCode": "123324" } } }
Successful Response
{ "_links": { "authReversal": { "method": "POST", "href": "/pts/v2/payments/6383780039607106528664/reversals" }, "self": { "method": "GET", "href": "/pts/v2/payments/6383780039607106528664" }, "capture": { "method": "POST", "href": "/pts/v2/payments/6383780039607106528664/captures" } }, "clientReferenceInformation": { "code": "RTS-Auth" }, "id": "6383780039607106528664", "orderInformation": { "amountDetails": { "authorizedAmount": "100.00", "currency": "inr" } }, "paymentAccountInformation": { "card": { "brandName": "RUPAY", "type": "061" } }, "paymentInformation": { "tokenizedCard": { "type": "061" }, "card": { "type": "061" } }, "processorInformation": { "approvalCode": "235426", "networkTransactionId": "100000000000000000000000025253", "transactionId": "100000000000000000000000025253", "responseCode": "00", "avs": { "code": "2" } }, "submitTimeUtc": "2022-12-01T17:00:04Z" }