- 集成指南
- 支持的功能（付款方式）
- Masterpass
Masterpass
Masterpass 是一项服务，允许付款人存储、管理其付款信息、送货地址和账单地址信息，并与其执行交易的网站和移动应用程序安全共享这些信息。如果您希望改善付款人的结账体验，同时降低 PCI 合规成本（因为电子钱包提供商负责保护付款人信息），那么此方法非常有用。
先决条件
若要通过 American Express Payment Gateway 使用 Masterpass，您的支付服务提供商必须将您的商家配置文件登入 Masterpass。成功登录后，您将收到一个支付服务提供商用于为您配置 Masterpass 的结账识别码。
Masterpass Standard Checkout
Masterpass Standard Checkout 允许付款人与其 Masterpass 数字钱包交互，无需离开您的网页。此交互在您的结账页顶部上方显示的 Lightbox 中呈现。
下图显示了您的购物网站和 Masterpass 的示例结账流。
- 付款人浏览您的购物网站，选择一件或多件产品，然后单击结账页的使用 Masterpass 购买。
- 在 Masterpass Lightbox（显示在购物网站顶部上方）中，付款人：
- 登录到其 Masterpass 电子钱包。
- 选择付款使用的卡。
- 选择送货地址或添加新地址。
- 单击按钮确认其选择并关闭 Masterpass Lightbox。
- 在您的购物网站，付款人结束购买，您显示订单摘要/收据。
请求 Masterpass Standard Checkout 交互
如果您有现有的 Hosted Checkout 集成，当您成功启用此集成后，Masterpass 将自动可用。
如果您希望在付款页完全控制 Masterpass Lightbox 交互，您可以选择此选项来自行调用 Lightbox。
<script src="https://masterpass.com/lightbox/Switch/integration/MasterPass.client.js"></script>
<script type="text/javascript">
// INITIALIZE and INVOKE THE MASTERPASS LIGHTBOX
MasterPass.client.checkout({
"version":"v6",
"successCallback": onSuccessfulCheckout,
"cancelCallback": onCancel,
"failureCallback": onFailure,
// USE PARAMETERS FROM THE OPEN WALLET RESPONSE
"requestToken": "<wallet.masterpass.requestToken>",
"merchantCheckoutId": "<wallet.masterpass.merchantCheckoutId>",
"allowedCardTypes": "<wallet.masterpass.allowedCardTypes>"
});
// RETRIEVE PARAMETERS FROM THE LIGHTBOX INTERACTION
function onSuccessfulCheckout(data) {
document.getElementById('oauthToken').value=data.oauth_token;
document.getElementById('oauthVerifier').value=data.oauth_verifier;
document.getElementById('checkoutUrl').value=data.checkout_resource_url;
}
function onCancel() {
// do something to tell you the cardholder cancelled
}
function onFailure() {
// do something to tell you things have gone wrong
}
</script>
- 执行
Create Session操作来获取会话 ID。 - 在
Open Wallet操作中使用Create Session响应中的会话 ID 来获取调用 Masterpass Lightbox 所需的数据。您需要在Open Wallet操作中提供以下项：
order.walletProvider:将此项设置为MASTERPASS_ONLINE。order.amount:订单金额。order.currency:支付订单使用的货币。wallet.masterpass.originUrl:调用 Masterpass Lightbox 的页面的 URL。
- 参考付款页中的
MasterPass.client.jsJavaScript 客户端库。 -
当付款人单击使用 Masterpass 购买时，使用
Open Wallet响应中的以下参数调用 Masterpass Lightbox。wallet.masterpass.requestTokenwallet.masterpass.merchantCheckoutIdwallet.masterpass.allowedCardTypes
您必须提供回调 URL 和/或回调方法来管理 Masterpass Lightbox 交互的响应。有关处理回调的更多信息，请参见 Masterpass 文档。
-
从回调 URL 或成功回调方法检索以下参数（仅当 Masterpass Lightbox 交互成功时返回），并将这些参数传入您的 Web 服务器。
oauth_tokenoauth_verifiercheckout_resource_url
- 执行
Update Session From Wallet操作从 Masterpass 获取付款人的付款详细信息和送货详细信息。您需要在此操作中提供以下参数。
- 会话 ID：
Create Session操作返回的付款会话的识别码。 order.walletProvider:将此项设置为MASTERPASS_ONLINE。wallet.masterpass.oauthToken:从回调检索的oauth_token。wallet.masterpass.oauthVerifier:从回调检索的oauth_verifier。wallet.masterpass.checkoutUrl:从回调检索的checkout_resource_url。
如果成功，返回的会话将包含来自 Masterpass 交互的付款人付款详细信息。
如果 Masterpass 付款人交互包括 3D 支付验证，那么 3DS 验证结果将被添加到会话中，并在Update Session From Wallet响应中返回。请参见高级结账。 - 会话 ID：
- 使用返回的会话呈现订单确认页或将付款提交到 American Express Payment Gateway。请参见使用会话执行操作。
购物网站的 Masterpass 品牌要求
在您的网站上作为一个选项向付款人呈现 Masterpass 时，您必须遵守 Masterpass 关于用户界面的商标要求。要获取有关如何在结账页呈现用户界面元素的指南，请参见 Masterpass 品牌。
Masterpass 配对
Masterpass 配对是将付款人的 Masterpass 电子钱包账户与其购物网站/应用程序账户进行关联的流程。有关详细信息，请参见 Masterpass 配对。
高级结账
如果您通过 Masterpass 设置了高级结账付款人身份验证服务，那么 Masterpass 的 MPI 将推进 3D 验证 (3DS)。
3DS 验证结果将被添加到会话中，并在 Update Session From Wallet 响应中返回。建议在继续将付款提交到 American Express Payment Gateway 前让您的集成对会话中的 3DS 结果进行验证。
测试您的集成
如果您的商家 ID 的前缀为 "TEST"，请求将被路由到 Masterpass 沙盒。
若进行测试，请确保将 MasterPass.client.js 库的参考设置为 https://sandbox.masterpass.com/lightbox/Switch/integration/MasterPass.client.js。
若要对您的 Masterpass 集成（包括 3DS 交互）执行端到端测试，请将以下测试卡添加到您在 Masterpass 沙盒的付款人电子钱包中。您可以随意提供过期日期或 CSC。
| 测试卡 | 卡号 | 已注册 3D 验证 |
|---|---|---|
Mastercard |
5506900140100305 | Y |
| 5506900140100107 | Y | |
| 5506900140100503 | N | |
Visa |
4440000009900010 | Y |
| 4440000042200014 | Y | |
| 4440000042200022 | N | |
American Express |
340000099900036 | Y |
| 340000099900028 | Y | |
| 340000099900044 | Y | |
| 340000099900051 | N | |
Diners Club |
30599900026332 | Y |
| 30599900026340 | N | |
| Discover | 6011100099900534 | - |
| 6011100099900013 | - |
常见问题
如果付款人的 Masterpass 电子钱包未与您的企业配对，American Express Payment Gateway 将从您的商家配置检索支持的卡类型，并确保在 Masterpass 仅这些卡类型可供选择。
如果付款人的 Masterpass 电子钱包已与您的企业配对，将从付款人的 Masterpass 电子钱包检索卡类型。