- 集成指南
- 支持的功能（安全）
- RuPay 付款人身份验证
- 使用 RuPay JavaScript API 实施 RuPay 身份验证
使用 RuPay JavaScript API 实施 RuPay 身份验证
此页内容介绍如何使用 RuPay JavaScript (JS) API 集成到网关以使用 RuPay 身份验证。
RuPay JS 集成指南是对 RuPay 身份验证 API 集成指南的补充，必须与其结合使用。
步骤 1： 创建和更新会话
RuPay JS 使用基于会话的身份验证。 作为第一步，您必须创建会话，然后您可以使用希望存储在会话中的请求字段和值更新会话。
您可以使用 Create Session 调用来创建会话。 这是一个服务器端 API 调用，是与 JS API 集成的一个先决条件。 它返回以下字段：
session.id: 您必须在后续请求中提供以引用会话内容的唯一会话识别码。session.authenticationLimit: 您在请求中提供的限制或网关的默认值。session.aes256Key: 您可以用来解密通过付款人浏览器或移动设备传递到您网站的敏感数据的密钥。session.version: 您可以使用此字段来实现会话内容的乐观锁。session.updateStatus: 上次尝试修改会话的结果的摘要。
Create Session API 参考[REST][NVP]
Update Session 请求
您可以使用 Update Session 调用在会话中添加或更新字段。 它允许您将付款和付款人数据添加到会话中，数据随后可以成为确定在身份验证操作中与付款人关联的风险的输入。 会话中需要以下字段：
强制字段
- sourceOfFunds.provided.card.*： 用于付款的卡的详细信息。
order.amount- order.currency： 订单货币。
- transaction.id： 此支付身份验证的唯一识别码。
- order.id： 此订单的唯一识别码。
authentication.channel=PAYER_BROWSER: 发起身份验证请求的通道。authentication.purpose=PAYMENT_TRANSACTION: 指示正在请求付款人身份验证的上下文。authentication.redirectResponseUrl: 您希望在完成付款人身份验证流程后将付款人重定向到的 URL。
请注意，您无法从会话中删除字段，只能覆盖现有字段的值。
步骤 2： 初始化 API
引用来自网关服务器的 RuPay JS API (rupay.js)。 这会将 rupay 对象放入窗口/全局名称空间。
rupay.js 参考[JavaScript]
创建会话后，使用 configure( ) 方法初始化 API。 此方法应该在页面加载过程中或 DOM 处于就绪状态时调用。 对于页面加载应该只调用一次。 调用此方法后，RuPay JS 将提供配置值作为成员变量。
RuPay JS 初始化请求
您可以通过调用 configure() 方法来初始化 RuPay JS API，在映射对象中使用以下强制字段作为参数：
merchantId: 您在网关上的商家识别码。sessionId: 您使用 Create Session 调用创建的会话 ID。containerId: API 将在其中插入隐藏内嵌框架的 html 中的 <div> ID。callback: API 初始化后将调用的函数。configuration: JSON 值支持数据元素，如 userLanguage（可选）、REST API 版本 (wsVersion)。
初始化 API 配置示例
<html>
<head>
<script src="https://gateway-na.americanexpress.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>
步骤 3： 发起身份验证
将所有付款人和付款数据收集到一个会话中后，您可以通过调用 initiateAuthentication() 方法来发起身份验证。 您可以通过它来确定商家是否可以为给定卡使用 RuPay 付款人身份验证。 如果卡类型为 RuPay，网关将确定 RuPay 卡 BIN 是否拥有进行电子商务交易的资格。
Initiate Authentication 请求
您可以通过在 initiateAuthentication() 方法中提供以下强制字段来发起身份验证：
- orderId： 此订单的唯一识别码。
- transactionId： 此支付身份验证的唯一识别码。
- callback： 回调函数。
- optionalParams： （可选）包含任何其他 Initiate Authentication REST API 请求字段（如 correlationId）的参数。
Initiate Authentication 响应
如果付款人的 RuPay 身份验证可用，回调函数的 data 参数中将返回以下字段。 否则，响应将包含错误。
data.restApiResponse: 包含来自 Initiate Authentication REST API 调用的原始响应。data.correlationId: 用于发起 Initiate Authentication REST API 调用的最后一个关联 ID。 您可以使用它匹配响应和请求。data.gatewayRecommendation
要确定下一步，请查看 gatewayRecommendation 字段中提供的网关建议。
gatewayRecommendation |
下一步 |
|---|---|
| PROCEED | 您可以使用 authenticatePayer( ) 方法调用继续对付款人进行身份验证。 |
| RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | 向付款人询问备用付款详细信息（例如，新卡或另一个付款方式），然后使用新详细信息重新提交请求。 不要重新提交相同的请求。 |
下表显示了各种 Rupay 身份验证场景的 Initiate Authentication 响应。
| 状态 | 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 |
Initiate Authentication 请求示例
var optionalParams = {
sourceOfFunds: {
type: "CARD"
},
order: {
walletProvider: "MASTERPASS_ONLINE"
}
};
Rupay.initiateAuthentication({orderId}, {transactionId}, function (data) {
if (data && data.error) {
var error = data.error;
//Something bad happened, the error value will match what is returned by the Authentication API
console.error("error.code : ", error.code);
console.error("error.msg : ", error.msg);
console.error("error.result : ", error.result);
console.error("error.status : ", error.status);
} else {
console.log("After Initiate RuPay ", data);
//data.response will contain information like gatewayRecommendation, authentication version, etc.
console.log("REST API raw response ", data.restApiResponse);
console.log("Correlation Id", data.correlationId);
console.log("Gateway Recommendation", data.gatewayRecommendation);
console.log("HTML Redirect Code", data.htmlRedirectCode);
console.log("Authentication Version", data.authenticationVersion);
switch (data.gatewayRecommendation) {
case "PROCEED":
authenticatePayer();//merchant's method
break;
case "RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS":
tryOtherPayment();//Card does not support 3DS and transaction filtering rules require 3DS on this transaction: Ask the payer to select a different payment method
break;
}
}
}, optionalParams);
步骤 4： 对付款人进行身份验证
如果 Initiate Authentication 响应已指示可对 RuPay 卡进行身份验证 (authentication.version=RUPAY)，您可以调用 authenticatePayer() 方法。 您应该在付款人单击结账页面的“立即付款”按钮时调用此项。
Authenticate Payer 操作可以安全地在您的收单银行和 RuPay PaySecure 之间交换必要的信息，包括卡号。 PaySecure 返回唯一的交易 ID (tran_ID)，可用于后续的 Authorization 或 Pay 操作。
Authenticate Payer 请求
您必须通过提供以下强制字段来调用 authenticatePayer() 方法：
orderId: 与之前的initiateAuthentication()方法相同的 orderId。transactionId: 与之前的initiateAuthentication()方法相同的 transactionId。callback: 回调函数。optionalParams: （可选）包含任何其他 Authenticate Payer REST API 请求字段（如fullScreenRedirect、billing）的参数。
Authentication Payer 响应
回调函数的 data 参数中返回以下字段：
data.restApiResponse: 包含来自 Authentication Payer REST API 调用的原始响应。data.correlationId: 用于发起 Authentication Payer REST API 调用的最后一个关联 ID。 您可以使用它匹配响应和请求。data.gatewayRecommendationdata.htmlRedirectCode: 网关始终返回此字段用于插入到向付款人显示的页面中。
要确定下一步，请查看回调中返回的 gatewayRecommendation 字段中提供的网关建议。
gatewayRecommendation |
下一步 |
|---|---|
| 继续 | 您可以继续完成身份验证流程（质询流）或继续完成付款（无障碍流）。 |
| DO_NOT_PROCEED_ABANDON_ORDER | 不要再次提交相同的请求。 支付服务提供商、组织或发卡机构要求您放弃订单。 |
| RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | 向付款人询问备用付款详细信息（例如，新卡或另一个付款方式），然后使用新详细信息重新提交请求。 不要重新提交相同的请求。 |
如果网关建议您 PROCEED，则将 htmlRedirectCode 响应字段的内容粘贴到显示给付款人的页面中。
下表显示了各种 Rupay 身份验证场景的 authenticatePayer() 响应。
| 状态 | 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 |
OTP 身份验证
网关将付款人的浏览器重定向到发卡机构的 OTP 验证 UI，在那里，系统将提示付款人输入有效的 OTP（在付款人被重定向回您的网站之后）。 在付款人的浏览器返回到您的网站后，以下字段将在回调中返回。
- order.id
- transaction.id
- result
- response.gatewayRecommendation
您可以使用 response.gatewayRecommendation 字段中返回的值来确定身份验证结果。
response.gatewayRecommendation |
下一步 |
|---|---|
| PROCEED | 您可以继续处理付款，因为同意进行身份验证。 如果对付款的授权成功，继续过账资金，如果适用，则发货。 |
| RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS | 向付款人询问备用付款详细信息（例如，新卡或另一个付款方式），然后使用新详细信息重新提交请求。 不要重新提交相同的请求。 |
在从 OTP 身份验证中检索结果后，网关会更新 Authentication Payer 响应字段。
| 状态 | 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 |
示例 Authenticate Payer 请求
var optionalParams = {
fullScreenRedirect: true,
billing: {
address: {
city: "London",
country: "GBR"
}
}
};
Rupay.authenticatePayer("5678", "ABC", function (data) {
if (!data.error) {
//data.response will contain all the response payload from the AUTHENTICATE_PAYER call.
console.log("REST API response ", data.restApiResponse);
console.log("HTML redirect code ", data.htmlRedirectCode);
}
}, optionalParams);
步骤 5： 在付款操作中使用身份验证结果
当 authenticatePayer() 方法的结果指示您可以继续处理付款时 (gatewayRecommendation=PROCEED)，您可以发起 Authorize 或 Pay 操作。 除了标准字段外，您还必须提供以下字段：
-
order.id： 提供您在
initiateAuthentication()和authenticatePayer()方法中提供的orderId。 -
authentication.transactionId： 提供您在
initiateAuthentication()和authenticatePayer()方法中提供的transactionId。 您无需在身份验证参数组中包括任何字段，因为当您要求执行身份验证时，网关将使用 authentication.transactionId 查找存储的身份验证结果。 网关将需要的信息传送到收单行。
示例 Pay 请求
| URL | https://gateway-na.americanexpress.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
| 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"
}
}
Pay 响应示例
{
"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"
}
测试您的集成
要测试您的集成，您可以在生产环境中使用测试商家配置文件。