- 集成指南
- 支持的功能（付款方式）
- 礼品卡
礼品卡
Mastercard Gateway 允许您将礼品卡作为付款人的付款方式。
先决条件
- 您必须已注册第三方提供商以使用这些卡。
- Your payment service provider 必须使用您在第三方提供商处的账户详细信息来配置您的 Mastercard Gateway 商家配置文件。
将礼品卡添加到您的集成中
网关提供三种将礼品卡集成到付款页的选项：
通过 Hosted Checkout 使用礼品卡
如果您有现有的 Hosted Checkout 集成，则可以使用 Hosted Checkout 来验证礼品卡详细信息。
您可以通过在 Create Checkout Session 请求中设置 interaction.operation=VERIFY 来执行此操作。Hosted Checkout 作为付款选项向付款人显示礼品卡。 付款人输入的数据使用配置收单行支持的验证方法进行验证。
您可以通过比较 resultIndicator 和 successIndicator 来确定验证操作是否成功。 如果交互未成功，Hosted Checkout 将显示指示验证失败的消息，并提示付款人重试。
通过 Hosted Session 使用礼品卡
如果您有自己的付款页面，那么您可以选择 Hosted Session 集成选项，让 Mastercard Gateway 安全地捕获礼品卡详细信息并将其存储到付款会话中。
<html>
<head>
<!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY -->
<script src="https://na.gateway.mastercard.com/form/version/72/merchant/<MERCHANTID>/session.js"></script>
<!-- APPLY CLICK-JACKING STYLING AND HIDE CONTENTS OF THE PAGE -->
<style id="antiClickjack">body{display:none !important;}</style>
</head>
<body>
<!-- CREATE THE HTML FOR THE PAYMENT PAGE -->
<div>Please enter your Gift Card details:</div>
<div>Card Number: <input type="text" id="gift-card-number" class="input-field" value="" readonly></div>
<div>Pin:<input type="text" id="gift-card-pin" class="input-field" value="" readonly></div>
<div><button id="payButton" onclick="pay();">Pay Now</button></div>
<!-- JAVASCRIPT FRAME-BREAKER CODE TO PROVIDE PROTECTION AGAINST IFRAME CLICK-JACKING -->
<script type="text/javascript">
if (self === top) {
var antiClickjack = document.getElementById("antiClickjack");
antiClickjack.parentNode.removeChild(antiClickjack);
} else {
top.location = self.location;
}
PaymentSession.configure({
fields: {
// ATTACH HOSTED FIELDS TO YOUR PAYMENT PAGE FOR A GIFT CARD
giftCard: {
number: "#gift-card-number",
pin: "#gift-card-pin",
}
},
//SPECIFY YOUR MITIGATION OPTION HERE
frameEmbeddingMitigation: ["javascript"],
callbacks: {
initialized: function(response) {
// HANDLE INITIALIZATION RESPONSE
},
formSessionUpdate: function(response) {
// HANDLE RESPONSE FOR UPDATE SESSION
if (response.status) {
if ("ok" == response.status) {
console.log("Session updated with data: " + response.session.id);
} else if ("fields_in_error" == response.status) {
console.log("Session update failed with field errors.");
if (response.errors.number) {
console.log("Gift card number invalid or missing");
}
if (response.errors.pin) {
console.log("Pin invalid.");
}
} else if ("request_timeout" == response.status) {
console.log("Session update failed with request timeout: " + response.errors.message);
} else if ("system_error" == response.status) {
console.log("Session update failed with system error: " + response.errors.message);
}
} else {
console.log("Session update failed: " + response);
}
}
}
});
function pay() {
// UPDATE THE SESSION WITH THE INPUT FROM HOSTED FIELDS
PaymentSession.updateSessionFromForm('giftCard', '<localCardBrand>');
}
</script>
</body>
</html>
- 在付款页包括网关托管的
session.js客户端 JavaScript 库。 此文件的路径包括 api 版本和会话的商家识别码。 - 创建包含礼品卡字段的付款页的 HTML。
为阻止向服务器提交敏感数据，请确保敏感数据字段为readonly且不具有name属性。 - 调用
PaymentSession.configure(configuration)函数。
configuration对象允许您将托管字段附加到付款页。 您需要提供以下项：
- 会话（可选），如果未提供，客户端库将创建付款会话。
- 礼品卡字段的字段选择器，如果提供将替换 Mastercard Gateway 托管的内嵌框架中嵌入的相应代理字段。 代理字段具有与替换字段相同的外观。
- 阻止点阅绑架的缓解选项
点阅绑架又称“UI 纠正攻击”：用户打算点击最上层页面时，攻击者使用多个透明或不透明层欺骗用户点击另一页面上的按钮或链接。 若要使用 Hosted Session，您必须实施以下针对点阅绑架攻击的一项或多项防范。
框架缓解选项 实施 javascript在付款页中包括“框架式截断符”JavaScript。 x-frame-options您的服务器应返回 X 框架选项 HTTP 响应标头。 csp您的服务器应返回包含框架继承指令的 Content-Security-Policy HTTP 响应标头。 您必须通过
frameEmbeddingMitigation调用中的PaymentSession.configure(configuration)参数指定实施哪些防御措施。 有关防范点阅绑架攻击的信息，请参阅 OWASP 外部网站的点阅绑架防范备忘单。 - Hosted Session 交互期间处理各个事件的回调
initialized( ): 当托管字段附加到付款页时调用。formSessionUpdate( ): 响应PaymentSession.updateSessionFromForm('giftCard', <localCardBrand>)函数而调用（参见下一步）
- 调用
PaymentSession.updateSessionFromForm('giftCard', <localCardBrand>)，将收集到的礼品卡详细信息存储到付款会话中。 操作完成后，将调用formSessionUpdate( )回调，其中包含结果参数。 您必须检查result.status值以确定操作是否成功。 请参见处理回调响应。 - 您可以使用返回的付款会话 (session.id) 来执行令牌化或付款交易（如果需要）。 有关详细信息，请参见使用会话执行操作。
session.js 参考[JavaScript]
通过 Direct Payment 使用礼品卡
如果您希望在付款页完全控制礼品卡交互，您可以选择 Direct Payment 选项。
使用礼品卡请求授权或付款
您需要在 Authorize 请求中提供以下字段：
sourceOfFunds.type=GIFT_CARDsourceOfFunds.provided.giftCard.number: 礼品卡号。sourceOfFunds.provided.giftCard.pin: 礼品卡 PIN。 （有时不强制提供，取决于礼品卡本身。）order.amount: 待付金额。order.currency: 付款货币。order.acceptPartialAmount: （可选）指示您是否准备好接受该卡执行全部金额的部分付款。 此字段的默认值为FALSE。
除标准字段外，成功授权还会返回以下字段：
sourceOfFunds.type:GIFT_CARD，反映您的请求。sourceOfFunds.provided.giftCard.number: 礼品卡号（隐藏）。sourceOfFunds.provided.giftCard.pin: 礼品卡 PIN（完全隐藏）。sourceOfFunds.provided.giftCard.scheme: 拥有礼品卡品牌并定义其使用操作规则的组织。sourceOfFunds.provided.giftCard.brand: 用于描述全球认可和接受的礼品卡的品牌名称。 对于很多主要卡类型，此字符串将与组织名称匹配。sourceOfFunds.provided.giftCard.localBrand: 用于描述礼品卡的品牌名称，由网关根据卡的 BIN 范围确定。availableBalance.funds.amount: 付款人使用此礼品卡执行此次付款后卡内剩余的可用金额。 （是否提供此信息取决于第三方提供商。）availableBalance.funds.currency: 卡中用于显示可用余额的表示为 ISO 4217 字母码的货币，例如，USD。order.amount: 接受的金额。 请注意，如果卡内没有足够资金且您设置了order.acceptPartialAmount=TRUE，此金额可能少于请求的金额。transaction.requestedAmount: 如果交易部分通过审批 (response.gatewayCode=PARTIALLY_APPROVED)，此信息包含原始请求金额。
如果您设置了order.acceptPartialAmount=TRUE，transaction.amount和order.amount将设置为实际审批的金额。
验证礼品卡
您可以通过提交 APIVERIFY 请求来验证具有所提供卡号（和 PIN）的礼品卡是否是提供商发放的有效礼品卡。
余额查询
您可以通过提交 API BALANCE_INQUIRY 请求来查询礼品卡的可用余额。 您需要在请求中提供以下信息：
sourceOfFunds.type=GIFT_CARDsourceOfFunds.provided.card.number: 您请求其余额信息的礼品卡号。
Balance Inquiry API 参考[REST][NVP]
管理部分审批
如果您准备好使用礼品卡接受部分交易金额的审批，您必须在请求中提交 order.acceptPartialAmount=TRUE。 在这种情况下，您有责任使用其他付款方式为未偿余额创建另一笔交易。
如果您未做好准备，请在请求中设置 order.acceptPartialAmount=FALSE。 如果礼品卡中的可用资金不足，Mastercard Gateway 将使用 response.gatewayCode=INSUFFICIENT_FUNDS 作出响应。