- 集成指南
- 实施 Hosted Payment Session 集成
- 使用 JavaScript 模型的Hosted Payment Session
使用 JavaScript 模型的Hosted Payment Session
使用 JavaScript(HPF.js) 模型的 Hosted Payment Session 是一种简单集成，其使用客户端 JavaScript 库最大限度地减少 Web 服务器与 Mastercard Gateway 之间的交互，您必须在付款页包括 JavaScript 库并通过 HostedForm.updateSession( ) 方法访问。 付款人的卡详细信息将被发送到 HostedForm.updateSession( ) 方法中的 Mastercard Gateway，当付款人单击“支付”提交付款页时，会调用此方法。
最佳做法和建议
确保敏感的付款字段不会提交到您的服务器非常重要。 例如，如果您使用付款单，您可以通过忽略“卡号”、“卡过期时间”和 CSC/CVV 字段的 'name' 属性来实现此目的。
如果付款人浏览器不支持 JavaScript，您无法使用采用 JavaScript 模型的 Hosted Payment Session。
HPF.js 信息流
HPF.js 模型的详细付款流如下所示。
- 向等待输入卡详细信息及其他所需信息的付款人显示付款页。 付款页：
- 必须包括 hpf.js 库，其通过调用 HostedForm.updateSession( ) 方法访问。
- 必须包括 HostedForm.setMerchant( ) 方法来使用 Mastercard Gateway 设置您商家账户的识别码。
- 必须包含您需要从付款人处捕获的卡字段（卡号、安全码、过期月份和过期年份）。
- 可以包含您希望在此阶段捕获的其他字段。 例如，送货地址、凭证号等。
- 可以根据您的需要设定样式。
请参阅构建您的集成。
此页只用于收集卡详细信息，不执行付款。 - 付款人输入卡详细信息并点击您网站上的“支付”按钮，这将调用 HostedForm.createSession( ) 方法。 通过付款页收集的卡详细信息在 HostedForm.createSession( ) 方法中传递。
Mastercard Gateway 在将卡详细信息（卡号、卡过期时间和 CSC/CVV 数据）添加到会话之前收集、验证（使用基本验证）并处理这些信息。
- Mastercard Gateway 使用您提供的回调函数返回对 HostedForm.createSession( ) 调用的响应。
- 您的网站解析 Mastercard Gateway 返回的所有错误，并在遇到错误时重新显示付款页。
- 您的网站将返回的会话识别码提交到您的 Web 服务器。
您可以根据您的业务工作流选择向付款人显示更多页面，或者在收集卡详细信息时执行存储或付款交易。
- 您通过使用以下一项或多项 API 操作指定所需字段来发起对 Mastercard Gateway 的请求： Authorize、Pay、Tokenization。 可以使用多个卡详细信息来源提供卡详细信息。 有关详细信息，请参见使用会话执行操作。
在执行付款交易前，您可以为动态货币兑换 (DCC) 提交费率报价请求来检索付款人货币以及使用该货币的订单金额。
在此阶段，您还可以使用 3D 验证服务对付款人进行身份验证。 请注意，如果付款人接受 DCC 出价，那么您必须在身份验证请求中提供 DCC 信息。 - Mastercard Gateway 将请求的结果发回给您。 您可以在会话过期之前使用会话标识符执行后续操作。
- 您在您的网站上向付款人显示交易结果。
如果您有自己的付款页，那么您可以选择此选项来让 Mastercard Gateway 管理包括 Visa Checkout SDK、启动 Visa Checkout Lightbox 和更新付款会话的结果等详细信息。 对于现有 Hosted Payment Session（使用 JavaScript）集成来说，这是最简单的选项。
付款流如下：
- 根据使用 JavaScript 集成的 Hosted Payment Session 的需要向付款人显示付款页。 您的付款页应包含一种方法来将 Visa Checkout 识别为付款人选择的结账选项。
下面是一些示例代码，显示如何在您的付款页上显示 Visa Checkout 作为选项。
<script id="hpfScript" src="https://mepspay.gateway.mastercard.com/form/v3/hpf.js"></script>
<!-- REPLACE THE action URL with the payment URL on your webserver -->
<form name="myform" method="POST" action="https://my.company.com/pay">
<!-- Other fields can be added to enable you to collect additional data on the payment page -->
Email: <input type="text" name="email">
<!-- The hidden values below can be set in the callback function as they are returned when creating the session -->
<input type="hidden" name="sessionId" id="sessionId">
<img alt="Visa Checkout" role="button" src="https://sandbox.www.v.me/wallet-services-web/xo/button.png" onclick="showVisaCheckoutLightbox()"/>
</form> - 当付款人选择 Visa Checkout 时，付款页将启动带有所需选项的 Visa Checkout Lightbox。 当与 Lightbox 的交互完成后，hpf.js 会自动使用 Lightbox 返回的 callId 从 Visa Checkout 检索付款详细信息。 交互结果在回调函数中返回 — 如果交互成功，付款详细信息在付款会话中填充。
下方是一些示例代码，显示如何调用 HostedForm.showVisaCheckout( ) 方法来启动包含所需选项的 Visa Checkout Lightbox，以及如何将 Visa Checkout 的交互详细信息填充到付款会话。
<script>
var options = {
acceptedCards: [
"MASTERCARD",
"AMEX",
"DISCOVER",
"VISA"
],
order: {
currency: "AUD",
amount: 10.50
},
merchant: {
logo: "https://test.te",
displayName: "your merchant"
},
country: "AUS",
locale: "en_AU",
paymentConfirmation: "CONFIRM_AT_PROVIDER"
paymentConfirmationMessage: "Continue to the merchant to complete your purchase"
};
function showVisaCheckoutLightbox() {
if (typeof HostedForm === 'undefined') {
throw 'hpf.js is not loaded';
}HostedForm.setMerchant("MERCHANT_ID"); //Replace with your merchant id
HostedForm.showVisaCheckout(options,
callback);
}</script> - JavaScript 回调函数通过描述
HostedForm.showVisaCheckout( )调用结果的对象处理来自 Visa Checkout 的交互响应。 您必须在您的付款页中定义此回调函数。如果
response.status="ok"，您的网页应将返回的会话识别码传送到您的 Web 服务器，以便可以使用此识别码来调用引用此会话的操作。下方是显示如何在付款页定义提交到您 Web 服务器的回调函数的一些示例代码。
var callback = function(response) {
if (response.status === "ok") {
// call your server to do the payment with the response.session value
// this is where we populate the hidden values in the form
var sessionIdElement = document.getElementById("sessionId");
sessionIdElement.value = response.session;
document.myform.submit();
}else if (response.status === "request_timeout") {
// handle the timeout for example by giving the payer the possibility to retry
}else if (response.status === "invalid_session") {
// handle invalid session details for example by giving the payer the possibility to retry with different card details. If the new details are correct,
you can call the updateSession( ) method
}else if (response.status === "cancelled") {
// handler code for the case when the user closes the Visa Checkout lightbox without selecting a credit card
}else {
// add system error handling here. Typically this would mean the integration is not working properly because there is no response from the client library.
// this could result in displaying a page to the payer to try again later and call support
}
}; - 现在，您可以使用此付款会话识别码来执行付款会话可以提供付款详细信息（例如，Authorize、Pay、Tokenize 请求）的任何操作。 请注意，可以使用多个卡详细信息来源提供卡详细信息。
疑难解答和常见问题
如果您使用 HostedForm.updateSession( ) 方法更新会话，那么您只能使用 API v30 来通过会话执行 Pay 交易。 如果您集成了 API v29 或更低版本，则必须将您的集成升级到 v30。
付款单可能会返回各种类型的错误。 请参阅错误处理。
您的付款页可能包含商家定义的字段以收集其他信息，例如，折扣券代码、忠诚度计划识别码、送货地址、送货方法等。但是，如果您将此信息传入 HostedForm.updateSession( ) 方法，其将被忽略。
可以，您可以多次调用 HostedForm.createSession( ) 方法 — 每次调用 HostedForm.createSession( ) 方法时都会创建一个新的会话。