- 集成指南
- 支持的功能（付款方式）
- Masterpass
Masterpass
Masterpass 是一项服务，允许付款人存储、管理其付款信息、送货地址和账单地址信息，并与其执行交易的网站和移动应用程序安全共享这些信息。如果您希望改善付款人的结账体验，同时降低 PCI 合规成本（因为电子钱包提供商负责保护付款人信息），那么此方法非常有用。
先决条件
若要通过 Spring by Citi 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：
- 使用返回的会话呈现订单确认页或将付款提交到 Spring by Citi Payment Gateway。请参见使用会话执行操作。
购物网站的 Masterpass 品牌要求
在您的网站上作为一个选项向付款人呈现 Masterpass 时，您必须遵守 Masterpass 关于用户界面的商标要求。要获取有关如何在结账页呈现用户界面元素的指南，请参见 Masterpass 品牌。
Masterpass 配对
Masterpass 配对是将付款人的 Masterpass 电子钱包账户与其购物网站/应用程序账户进行关联的流程。有关详细信息，请参见 Masterpass 配对。
高级结账
如果您通过 Masterpass 设置了高级结账付款人身份验证服务，那么 Masterpass 的 MPI 将推进 3D 验证 (3DS)。
3DS 验证结果将被添加到会话中，并在 Update Session From Wallet 响应中返回。建议在继续将付款提交到 Spring by Citi 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 电子钱包未与您的企业配对，Spring by Citi Payment Gateway 将从您的商家配置检索支持的卡类型，并确保在 Masterpass 仅这些卡类型可供选择。
如果付款人的 Masterpass 电子钱包已与您的企业配对，将从付款人的 Masterpass 电子钱包检索卡类型。