实现 Hosted Payment Page
您有两种选择来实现 Hosted Payment Page：
- 嵌入页面是在您网站现有的结账页面内激活的组件。
- 付款页是一个单独的页面，付款人将被从您现有的结账页面重定向到此页面。
如果您最初已经实现了 Lightbox 页面（使用 API v62 或更早版本），您的付款页是显示在现有结账页面顶部的模态对话框。 新 API 版本不直接支持此实现，但如果您在迁移到新 API 版本，可以使用模态模式，这样，您可以将 Lightbox 用作嵌入页面的扩展。
建立了结账会话后，为 Hosted Checkout 实现 Hosted Payment Page 的过程包括以下步骤：
- 创建 Checkout 对象。
- 配置 Checkout 对象。
- 使用 Checkout 对象的适当方法来开始付款流程。
此外，您还可以定义在付款流程中付款人采取某些操作时触发的回调。
Hosted Payment Page 实现在您的应用或网站中完成，使用 Checkout JavaScript (JS) 库。
步骤 1： 创建 Checkout 对象
会话初始化后，您需要在结账页面上引用网关服务器中的 checkout.min.js 文件。 这会将 Checkout 对象放到全局范围内。
示例
<script src="https://ap-gateway.mastercard.com/static/checkout/checkout.min.js" data-error="errorCallback" data-cancel="cancelCallback"></script>
如果您同时启用了 AUTHORIZATION 和 PAY 操作，则必须使用 Hosted Checkout v52 或更高版本。
步骤 2： 配置 Checkout 对象
调用 Checkout.configure() 函数并向其传递一个 JSON 对象，该对象包含之前从 Initiate Checkout 操作返回的 session.id。
示例
Checkout.configure({
session: {
id: '<your_initiate_checkout_ID>'
}
});
- 在 API v67 或更高版本中，会话对象是 configure() 允许使用的唯一字段 - 所有其他字段必须通过 INITIATE CHECKOUT 包含在内。
- Checkout.configure() 中传递的数据永远不会覆盖您在 INITIATE CHECKOUT 操作中已经提供的数据。
步骤 3： 开始付款流程
通过调用 Checkout 对象的以下方法之一开始付款流程，具体取决于您实现的 Hosted Payment Page 类型。
- 要在嵌入页面上显示结账交互：
示例
Checkout.showEmbeddedPage('#embed-target') - 要在付款页上显示结账交互：
示例
Checkout.showPaymentPage()
请求嵌入或付款页面的 HTML 代码示例
示例
<html>
<head>
<script src="https://ap-gateway.mastercard.com/static/checkout/checkout.min.js" data-error="errorCallback" data-cancel="cancelCallback"></script>
<script type="text/javascript">
function errorCallback(error) {
console.log(JSON.stringify(error));
}
function cancelCallback() {
console.log('Payment cancelled');
}
Checkout.configure({
session: {
id: '<your_initiate_checkout_session_ID>'
}
});
</script>
</head>
<body>
...
<div id="embed-target"> </div>
<input type="button" value="Pay with Embedded Page" onclick="Checkout.showEmbeddedPage('#embed-target');" />
<input type="button" value="Pay with Payment Page" onclick="Checkout.showPaymentPage();" />
...
</body>
</html>
使用模态模式的 HTML 代码示例
示例
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/css/bootstrap.min.css" integrity="sha384-JcKb8q3iqJ61gNV9KGb8thSsNjpSL0n8PARn9HuZOnIxN0hoP+VmmDGMN5t9UJ0Z" crossorigin="anonymous">
<title>Hello, world!</title>
</head>
<body>
<h1>Hello, world!</h1>
<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal">
Launch demo modal
</button>
<div class="modal fade" id="exampleModal" tabindex="-1" role="dialog" aria-labelledby="exampleModalLabel" aria-hidden="true">
<div class="modal-dialog" role="document">
<div class="modal-content">
<div class="modal-header">
<h5 class="modal-title" id="exampleModalLabel">Modal title</h5>
<button type="button" class="close" data-dismiss="modal" aria-label="Close">
<span aria-hidden="true">—</span>
</button>
</div>
<div class="modal-body" id="hco-embedded">
</div>
<div class="modal-footer">
<button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>
<button type="button" class="btn btn-primary">Save changes</button>
</div>
</div>
</div>
</div>
<script src="https://code.jquery.com/jquery-3.6.0.slim.min.js" integrity="sha256-u7e5khyithlIdTpu22PHhENmPcRdFiHRjhAuHcs05RI=" crossorigin="anonymous"></script>
<script src="https://cdn.jsdelivr.net/npm/bootstrap@4.5.2/dist/js/bootstrap.min.js" crossorigin="anonymous"></script>
<script src="https://ap-gateway.mastercard.com/static/checkout/checkout.min.js" ></script>
<script>
// Configure Checkout first
Checkout.configure({
session: {
id: "<your_initiate_checkout_ID>"
}
})
// after the modal is shown, then call Checkout.showEmbeddedPage('#hco-embedded')
$('#exampleModal').on('shown.bs.modal', function (e) {
Checkout.showEmbeddedPage('#hco-embedded',
() => { $('#exampleModal').modal() } // tell Checkout how to launch the modal
)
});
$('#exampleModal').on('hide.bs.modal', function (e) {
sessionStorage.clear(); // tell Checkout to clear sessionStorage when I close the modal
});
</script>
</body>
</html>
步骤 4： 实现回调
提供回调来处理付款交互期间可能发生的事件。 使用回调是可选的，但如果需要，必须在引用 checkout.min.js 的同一个 <script> 标签的正文中进行定义。
所有定义的回调必须一一实施。 当相关事件被触发时它们会被调用。 以下代码示例显示在页面上定义和实现回调（在付款人取消付款时触发）的示例。
回调示例
<script src="https://ap-gateway.mastercard.com/static/checkout/checkout.min.js"
data-cancel="cancelCallback"
data-beforeRedirect="Checkout.saveFormFields"
data-afterRedirect="Checkout.restoreFormFields">
</script>
<script>
function cancelCallback() {
confirm('Are you sure you want to cancel?');
// code to manage payer interaction
}
// or if you want to provide a URL:
// cancelCallback = "someURL"
</script>
有两种类型的回调方法： 基本回调和重定向回调。
基本回调
为以下事件提供基本回调：
- cancel： 付款人取消付款交互时。
cancel 回调只能用于付款页，不适用于嵌入页面。
- error： 发生错误时。
- complete： 付款人完成付款交互时。
- timeout： 在可供付款人付款的持续时间内完成付款时。
重定向回调
由于 Hosted Checkout 支持需要将付款人重定向到其他网站以推进付款（如 PayPal）的付款交互，需要提供回调来管理重定向前以及返回到 Hosted Checkout 后发生的事件以完成交易处理：
- beforeRedirect： 在向付款人呈现付款界面前。 返回恢复付款界面状态所需的数据，供 afterRedirect 使用。
- afterRedirect： 当付款人从完成付款交互返回时。 使用 beforeRedirect 保存的数据返回保存的付款界面状态。
Checkout 对象还提供两个函数来帮助您实现 beforeRedirect 和 afterRedirect 回调：
- saveFormFields()： 保存所有当前表单字段以供 restoreFormFields() 使用。 在 beforeRedirect 实现中使用或将 beforeRedirect 实现为 Checkout.saveFormFields()。
- restoreFormFields()： 恢复由 saveFormFields() 保存的表单字段。 在您的 afterRedirect 实现中使用或将 afterRedirect 实现为 Checkout.restoreFormFields()。
常见问题
如果 Hosted Checkout 返回错误，我应该怎么做？
Hosted Checkout 可能返回一些集成错误。 请参见测试步骤了解有关测试和错误的更多信息。
为什么我收到错误页面而不是 Hosted Payment Page？
在尝试错误的 Hosted Checkout 请求时会显示错误页面。 常见错误原因包括：
- 缺少强制字段。
- 请求中提供的 URL 不是绝对的。
如果付款人双击“支付”按钮会发生什么？
如果付款人双击“支付”按钮，即提交付款两次，该交易不会与您或付款人银行的交易重复。