- 集成指南
- 实施 <<checkout>> 集成
实施 <<checkout>> 集成
先决条件
强制:
请确保已为 <<checkout>> 服务启用商家配置文件。如果未启用,请与您的服务提供商联系。要为商家配置文件启用 Hosted Checkout,请参见 Merchant Manager 门户和 Merchant Manager 用户指南。可选:
如果付款成功,建议您选择“通知”服务,通过电子邮件或 Webhook 接收通知。选择此服务,您可以让网关代表您向付款人发送电子邮件通知。建议:
在开始集成 Hosted Checkout 功能之前,您必须参阅最佳做法和建议。
请求 <<checkout>> 交互
选择以下步骤请求 <<checkout>> 交互:
使用 Initiate Checkout
操作请求结账会话。
请求应包括付款和交互数据以及完成指令。以下是 Initiate Checkout
操作的示例代码段。
curl https://qnbalahli.test.gateway.mastercard.com/api/nvp/version/73 \ -d "apiOperation=INITIATE_CHECKOUT" \ -d "apiPassword=$PWD" \ -d "apiUsername=merchant.<your_merchant_id>" \ -d "merchant=<your_merchant_id>" \ -d "interaction.operation=AUTHORIZE" \ -d "interaction.merchant.name=<your_merchant_name>" \ -d "order.id=<unique_order_id>" \ -d "order.amount=100.00" \ -d "order.currency=USD" \ -d "order.description=<description_of_order>"
对此操作的成功响应将包含 session.id
和 successIndicator
参数。您可以将 successIndicator
参数中返回的值保存到您的商店系统内来验证付款是成功还是失败。请参见获取付款结果。
参考网关服务器的 checkout.min.js 文件。这会将 Checkout
对象放到全局范围内。
<script src="https://qnbalahli.test.gateway.mastercard.com/static/checkout/checkout.min.js" data-error="errorCallback" data-cancel="cancelCallback"></script>
checkout.js 参考[JavaScript]
调用 Checkout.configure()
,传入包含返回的 session.id
及其他请求参数的 JSON 对象。
Checkout.configure({ session: { id: '<your_initiate_checkout_ID>' } });
Checkout.configure()
的数据绝不会覆盖您在 Initiate Checkout
操作中提供的数据。通过调用以下流程之一开始付款流程。
Checkout.showEmbeddedPage('#embed-target')
Checkout.showPaymentPage()
请求结账交互的 HTML 代码示例
<html> <head> <script src="https://qnbalahli.test.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>
Checkout.configure()
:- 文字 – 例如,
quantity : 300
- 返回值的函数,例如,
quantity : function() { return 100 + 200 }
。
函数在触发付款流程时执行。
模拟模态结账交互的 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://qnbalahli.test.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>
Hosted Checkout 的功能
回调
提供的回调用于处理付款交互期间可能发生的事件。
是否使用回调是可选的,但您必须定义引用 checkout.js 的同一个<script>
标签的主体需要的回调。
所有定义的回调必须一一实施。当触发相关事件时,这些回调将被调用。
<script src="https://qnbalahli.test.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
:付款人取消付款交互时。“取消回调”只能用于付款页,不能用于嵌入页面。error
:发生错误时。complete
:付款人完成付款交互时。timeout
:在可供付款人付款的持续时间内完成付款时。
这些可能是函数或 URL。如果您在回调中提供 URL 而不是函数,当触发事件时,付款人将被重定向到此 URL。
由于 <<checkout>> 支持需要将付款人重定向到其他网站以推进付款(例如,PayPal)的付款交互,需要提供回调来管理重定向前以及返回到 <<checkout>> 后发生的事件以完成交易处理。
beforeRedirect
:在向付款人呈现付款界面前。返回所需数据以恢复供afterRedirect
使用的页面状态。afterRedirect
:当付款人从完成付款交互返回时。使用beforeRedirect
保存的数据返回保存的付款界面状态。
Checkout
对象还提供两个函数来帮助您实现 beforeRedirect
和 afterRedirect
回调:
saveFormFields
:保存供restoreFormFields
使用的所有当前的表单字段。在beforeRedirect
实现中使用或作为Checkout.saveFormFields
实现beforeRedirect
。restoreFormFields
:恢复saveFormFields
保存的表单字段。在afterRedirect
实现中使用或作为Checkout.restoreFormFields
实现afterRedirect
。
checkout.js 参考[JavaScript]
获取付款结果
在完成付款交互后,您可以将付款人返回到您的购物网站并向付款人呈现您自己的收据页。您还可以使用付款详细信息更新您的商店系统。
若要将付款人返回到您的购物网站,您必须:
- 在
Initiate Checkout
操作中提供interaction.returnUrl
,或 - 在 <<checkout>> 请求中定义
complete
回调。这既适用于基本回调,也适用于重定向回调。请参见回调。
网关发送 resultIndicator
参数中的付款结果,即:
- 附加到用于将付款人返回到您的购物网站的 URL (
interaction.returnUrl
),或 - 作为输入参数向
complete
回调中提供的函数提供,或附加到complete
回调中提供的 URL。
您可以通过比较 resultIndicator
参数与 Initiate Checkout
响应中返回的 successIndicator
参数来确定付款是否成功。匹配表示付款成功。
resultIndicator
参数中的值绝不能用作收据号。如果成功,在您的购物网站上向付款人呈现付款收据,并使用付款详细信息更新您的商店系统。您可以使用 Retrieve Order
操作检索这些数据。
通过 Merchant Administration
付款详情记录在 Merchant Administration 中的订单和交易详细信息页。您可以搜索付款并执行后续操作。
使用 <<reportingAPI>>
如果您订阅了 <<reportingAPI>>,您可以从 QNB ALAHLI 的确定格式的报告中下载 <<checkout>> 付款数据。
通过电子邮件或 Webhook 通知
如果您在 Merchant Administration 中订阅了电子邮件通知,您将在每次成功付款时收到电子邮件通知。
自定义付款体验
<<checkout>> 允许您控制要显示的业务相关信息,以及使用 Initiate Checkout
操作与付款人的交互。
URL | https://qnbalahli.test.gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/session |
HTTP 方法 | POST |
{ "apiOperation": "INITIATE_CHECKOUT", "interaction": { "merchant": { "name": "The Company Co", "url": "https://www.merchant-site.com", "logo": "https://upload.wikimedia.org/wikipedia/commons/2/21/Verlagsgruppe_Random_House_Logo_2016.png" }, "displayControl": { "billingAddress": "MANDATORY", "customerEmail": "MANDATORY" }, "timeout": 1800, "timeoutUrl": "https://www.google.com", "cancelUrl": "http://www.google.com", "operation": "PURCHASE", "style": { "accentColor": "#30cbe3" } }, "billing": { "address": { "city": "St Louis", "stateProvince": "MO", "country": "USA", "postcodeZip": "63102", "street": "11 N 4th St", "street2": "The Gateway Arch" } }, "order": { "amount": "123.60", "currency": "EUR", "description": "This is the order description", "id": "ORDER-4142773a-ac2e" }, "customer": { "email": "peteMorris@mail.us.com", "firstName": "John", "lastName": "Doe", "mobilePhone": "+1 5557891230", "phone": "+1 1234567890" } }
interaction.merchant
参数组中提供的字段将仅在托管付款页集成的收据页上显示,嵌入页面的收据页上不会显示。您可以使用以下选项自定义付款体验:
- 显示品牌信息
包括您的徽标和详细联系信息。
请参见:所有参数:发起结账提供以下详细信息:
- 徽标参考
- 商家信息字段
- 管理付款人账单和电子邮件地址的显示
在从付款人处收集到账单和电子邮件地址后,您可以通过将
interaction.displayControl.billingAddress
和interaction.displayControl.customerEmail
字段进行以下一种设置来显示这些信息并控制这些信息是否可编辑:HIDE
:如果您不希望 <<checkout>> 显示这些字段。MANDATORY
:如果您希望 <<checkout>> 显示这些字段并强制付款人进行数据输入。OPTIONAL
:如果您希望 <<checkout>> 显示这些字段,但允许付款人选择不在字段中输入数据。READ_ONLY
:如果您希望 <<checkout>> 显示这些字段,但不允许付款人编辑字段。
- 管理送货详细信息的显示
在从付款人处收集到送货详细信息后,您可以通过将
interaction.displayControl.shipping
字段进行以下一种设置来控制这些信息的显示:HIDE
:如果您不希望 <<checkout>> 显示这些字段。READ_ONLY
:如果您希望 <<checkout>> 显示这些字段,但不允许付款人编辑字段。
付款人将无法编辑之前提供的任何送货详细信息。
如果未提供所需送货详细信息,与送货地址相同复选框的功能将不可用。 - 管理语言和主题
默认情况下,<<checkout>> 显示的语言由付款人浏览器确定。不过,您可以通过指定
locale
字段内的语言识别码或 IETF 语言标签来覆盖此行为;例如,en_US
、es
、fr_CA
。如果 QNB ALAHLI 不支持您指定的语言,<<checkout>> 显示为最佳匹配语言。默认情况下,支付服务提供商设置的默认主题控制 <<checkout>> 的外观。如果支付服务提供商支持多个主题,您可以通过在请求中提供
interaction.style.theme
字段选择覆盖默认主题。目前您可以使用的主题为
<<hppThemes>>
。 - 订单 ID
建议您在请求中包含
order.id
,以便轻松识别从 <<checkout>> 发起的付款。您可以使用购物车生成的识别码,也可以提供您自己的识别码。但请确保识别码具有唯一性。 - 卡号
当付款人选择使用卡支付时,他们可以在结账交互期间输入信用卡或借记卡详细信息。但是,如果您的收单行中至少有一家支持组合卡,即卡既可以用作借记卡也可以用作信用卡,则付款人需要在付款页上选择付款方式 — 借记卡或信用卡 — 指定卡在此付款中应采用的运行模式。
3DS 支付验证
要在 Hosted Checkout 集成中使用 3DS 支付验证,请与您的支付服务提供商联系,为您的商家账户启用必要的权限。
要测试您的集成是否能够正常使用 3DS 支付验证,您可以在生产环境中使用测试商家配置文件。
使用以下测试卡测试集成
卡类型 | 身份验证状态 | 测试卡 |
---|---|---|
Mastercard | 3DS2 - 质询 | 5123450000000008 |
Mastercard | 3DS1 - 未注册 3DS2,导致回退到 3DS1 | 5506900140100305 |
Visa | 3DS2 - 质询 | 4440000009900010 |
Visa | 3DS1 - 未注册 3DS2,导致回退到 3DS1 | 4508750015741019 |
有关身份验证的更多信息,请参见身份验证常见问题。
启用 EMV 3DS
EMV 3-D 验证 (EMV 3DS) 是一项全球行业标准,旨在帮助商家和发卡机构对无卡交易进行身份验证。最新一代 EMVCo 行业标准(称为 EMV 3-D 验证或 EMV 3-D 验证 2.0),是一种比当前版本(3-D 验证 1)更强大的协议和更强的身份验证。启用 EMV 3DS 可以减少欺诈、错误拒绝和不必要的摩擦,从而改善您的数字支付体验。
商家先决条件(仅印度和孟加拉国)
- 商家的收单行需要完成收单行的先决条件。
- 对于收单行支持的每个方案,需要在支付网关中的商家配置文件上进行额外配置。
- Mastercard、Visa 和 Amex 需要额外的商家权限。这可以在 Merchant Manager 门户内的“商家配置文件页面 > 付款详细信息页面 > 持卡人验证”部分配置。
商家集成
- 与 Web 服务 API (WS-API) v57 及以上版本集成。
- 请按照下方帮助页上描述的步骤操作:
- 在 Merchant Administration 中通过导航到以下位置启用 EMV 3DS:管理 > 集成设置 > Hosted Checkout
达到 WCAG(Web 内容可访问性指南)合规要求
<<checkout>> 可以配置为符合 WCAG 2.0 级别 AA 要求的用户体验。请参见 WCAG 2.0 指南,并确保您的网站达到这项技术标准。
设置 lang 属性
将语言属性添加到 html 元素中。
<html lang="en"> <head></head> <body></body> </html>
提供付款方案
如果您在商家配置文件中配置了付款方案,默认情况下,商家配置中的所有付款方案都会在 <<checkout>> 期间向付款人显示。不过,付款方案是否对付款人可用将由付款人输入的卡号以及订单货币确定。
您可以通过按交易指定付款方案约束来限制报价可以使用的付款方案。如果您希望确保向付款人提供的付款选项符合预先定义的条件,从而在付款人篡改付款方案数据时阻止对付款的处理,那么此方法非常有用。您可以在请求中使用以下字段来指定约束:
constraints.paymentPlans.supported[n]
:为此交易提供的付款方案。constraints.paymentPlans.numberOfPayments
:付款方案允许的分期付款次数。constraints.paymentPlans.numberOfDeferrals
:付款方案允许的延期月数。
默认情况下,付款方案的付款条款(如果有)显示在 <<checkout>> 中。您可以通过设置 Checkout.configure()
中的 interaction.displayControl.paymentTerms=HIDE
来隐藏这些条款。
付款详细信息验证支持
对于礼品卡和 <<ach>> 付款,<<checkout>> 仅支持付款详细信息验证。
您可以通过在 Initiate Checkout 请求中设置 interaction.operation=VERIFY
来执行此操作。
<<checkout>> 使用配置收单行支持的验证方法以及请求中提供的数据。
您可以通过比较 resultIndicator
和 successIndicator
来确定验证操作是否成功。
如果交互未成功,<<checkout>> 将显示指示验证失败的消息,并提示付款人重试。
支持非电子商务集成
您可以对商家配置文件中配置的任何交易来源使用 <<checkout>>(互联网、呼叫中心、电话订单等)。
您可以通过在 Initiate Checkout 请求中提供 transaction.source
来执行此操作。
如果通过 transaction.source
而不是 INTERNET
请求 <<checkout>>,将不支持需要呈现付款人的付款选项。
如果您未在请求中提供 transaction.source
:
- 将默认为
INTERNET
(如果商家收单行链接支持)。 - 如果不支持,将默认为商家配置文件中的交易来源。
控制卡安全码
您可以通过将 Initiate Checkout 请求中的 interaction.displayControl.cardSecurityCode
设置为以下值之一来控制是否需要付款人提供卡安全码才能够处理付款:
OPTIONAL
:如果您希望 <<checkout>> 显示“卡安全码”输入字段,但对是否输入此字段不做强制要求。MANDATORY
(默认):如果您希望 <<checkout>> 显示“卡安全码”输入字段,并强制输入。
绕过安全功能
如果您被配置为使用 3DS 支付验证或风险管理服务,您可以选择绕过这些功能(如果您希望如此)。
- 绕过支付身份验证:在 Initiate Checkout 请求中设置
interaction.action.3DSecure=BYPASS
。 - 绕过:不向付款人提供 3DS 身份验证。
- 强制:向付款人提供 3DS 身份验证(如果可用)。
- 绕过风险评估:在 Initiate Checkout 请求中设置
risk.bypassMerchantRiskRules=ALL
。
CREATE_CHECKOUT_SESSION
请求中的 interaction.action.3DSecure
字段可以使用以下值:
Click To Pay
要在 Hosted Checkout 集成中使用 Click To Pay,请与您的支付服务提供商联系,为您的商家账户启用必要的权限。
启用 Click To Pay
Click to Pay 是一个智能的免密码在线结账选项,可提供快速、轻松的结账体验,目的是让所有设备上的“来宾结账”更快、更轻松。Click to Pay 为所有相关卡组织提供标准化的结账流。Click to Pay 基于 EMVCo 的 SRC 规范构建,取代了 Masterpass、Visa Checkout 和 Amex Express Checkout。
如果您使用网关的付款页 (Hosted Checkout),并且已为商家配置文件激活 Click to Pay,将会自动向您的付款人提供 Click to Pay。
商家先决条件
- 商家的收单行需要完成收单行的先决条件。
- 通过 Merchant Administration 注册 Click To Pay。请参见此处的详细信息。
- 与 Web 服务 API (WS-API) v63 及以上版本集成。
其他注意事项
- 送货地址:付款人在 Click to Pay 交互期间无法选择送货地址,如果需要送货地址,商家必须在启动 Hosted Checkout 之前提示输入此信息。
- 账单地址:在 Click to Pay 交互过程中始终会收集账单地址。
- 3DS 支付验证:如果您配置了 3DS 支付验证 (3DS),Hosted Checkout 会在 Click to Pay 交互之后自动执行 3DS 身份验证。
在发送使用 Hosted Checkout 的 Click to Pay Initiate Checkout 请求时,需要考虑其他一些参数。
使用 Hosted Checkout 的 Click to Pay 发起结账参数:
字段 | 说明 | 必需 |
---|---|---|
interaction.country |
对于 SRC 交互,交互国家/地区确定在 SRC 交互过程中呈现给付款人的特定于国家/地区的内容,如条款和条件。默认使用在网关中根据您的商家配置文件配置的值。如果您要在此交互中覆盖此值,将 interaction.country 字段添加到 Initiate Checkout 请求中。 | 可选 |
interaction.locale |
对于 SRC 交互,交互区域设置确定显示语言。默认情况下,使用付款人浏览器中配置的语言。如果付款人的语言无法确定或不受支持,将使用 en_US。如果您要覆盖此值,将 interaction.locale 字段添加到 Initiate Checkout 请求中。目前,支持的语言有英语(英国)(en_UK)、西班牙语(西班牙)(es_ES)、法语(加拿大)(fr_CA)、葡萄牙语(巴西)(pt_BR) 和中文(中国香港)(zh_HK)。 | 可选 |
merchant.name |
提供您的交易名称,如付款人已知的名称。此名称可能会在 SRC 交互过程中显示。 | 必需 |
merchant.url |
提供付款人正在使用的网站的 URL。此 URL 可能会在 SRC 交互过程中显示。 | 必需 |
customer.email |
在 SRC 交互过程中始终会收集付款人的电子邮件地址。如果您已经知道付款人的电子邮件地址,添加 customer.email:将“your payer email address”添加到 Initiate Checkout 请求中,以允许付款人在 SRC 交互期间绕过输入电子邮件地址的步骤。 | 可选 |
有关 Click To Pay 的更多信息,请参见常见问题。
测试您的集成
在投入使用前,您必须测试您的集成以确保功能正确。
测试您的 Click To Pay 集成
在投入使用前,您必须测试您的集成以确保功能正确。
疑难解答和常见问题
<<checkout>> 可能返回一些集成错误。请参见测试您的集成。
当尝试提交不正确的 <<checkout>> 请求时将提供错误页面。常见错误原因包括:
- 未提供强制字段。
- 请求中提供的 URL 不是绝对的。
如果付款人两次提交"支付"按钮,不会对您或付款人银行重复执行交易。
是,支持 EDGE 113。
最佳做法和建议
<<checkout>> 模型很安全,因为它需要您向网关进行身份验证,而且在付款页收集的付款详细信息将从付款人浏览器直接提交到网关。
文件大小或徽标宽度没有限制。高度方面,建议最低为 144 像素。
可以,您可以在任何提供程序上托管徽标图像,但是,URL 必须是安全的 (HTTPS)。如果您的托管提供程序不支持安全 URL,以下列表中的提供程序可以为您提供免费的 HTTPS 托管:https://www.google.com.au/search?q=secure+image+hosting+providers
仅当送货地址内的所有必填字段全部提供时,此复选框才可见。您必须确保付款人已填写这些字段,或您提供缺少字段(如 shipping.country
(如果商品不是国际运送))。
如果您希望为客户提供良好的移动体验,包括优化移动设备上的 <<checkout>> 体验,最佳做法是在您的站点页面上添加“视窗”标签。例如,
<meta name="viewport" content="width=device-width, initial-scale=1">
请注意,为页面选择正确的视窗值并在执行这些更改后对自己的站点进行测试非常重要。