- 集成指南
- 实施 Hosted Payment Session 集成
- Hosted Payment Session POST 模型
Hosted Payment Session POST 模型
此 Hosted Payment Session 模型需要构建服务器端集成代码来从 Mastercard Gateway 获取会话令牌，从而使用返回的会话令牌识别码来构建显示付款页所需的表单，以及解析来自 Mastercard Gateway 的表单响应。
最佳做法和建议
Hosted Payment Session 始终返回 "gatewayFormResponse" 字段，无论它是否作为表单发布字段包含在内。 在这种情况下，某些 Web 框架可能会出现错误或限制对该字段的访问。 如果您使用的 Web 框架要求表单发布字段与最初显示的表单中的字段相匹配，则应确保该字段包含在表单中。
创建付款单时，不要将会话标识符作为隐藏字段。 此字段仅应包含在表单 URL 中。 如果您希望将其存储在其他页面以供参考，那么将其存储在 HTTP 会话中更为合适。
限制表单输入字段的长度被视为一个最佳做法，有助于保持数据的完整性。 有些情况下，如果不限制字段长度，提交的数据可能被 Hosted Payment Session 截断。
字段名称可以带前缀，但必须以表单字段参考中定义的公认的字段名称结尾。 例如，"ctl00$MainContent$gatewayCardNumber" 是一个有效的字段名称，对它的处理将与名为 "gatewayCardNumber" 的字段完全相同。 这对于使用 .Net 平台的集成人员尤为有用。
HTTP 会话（不要与付款会话混淆）通常用于在付款人与网站交互期间跟踪付款人数据，例如，购物车信息。
维护会话的最常见方法是使用 Cookie。 请记住，如果付款人的浏览器（或您的 Web 服务器）上未启用 Cookie，您可能还需要支持 URL 重写以在 Cookie 中维护 HTTP 会话。 有关详细信息，请参阅您选择的 Web 框架的文档。
为了确保 Hosted Payment Session 正确处理使用默认 ISO-8859-1 以外的字符集编码的字符，您需要在表单 URL 中指定 "charset" 查询参数。 例如，要指定提交的表单使用字符集 UTF-8 进行编码，则表单 URL 将类似于：
https://paymentgateway.commbank.com.au/form/<formSessionIdentifier>?charset=UTF-8
这也将确保响应被正确编码。 支持的字符集可在此处找到。
通过自定义"继续"页面处理禁用 JavaScript 的浏览器。 当浏览器禁用 JavaScript 时，会向付款人显示一个页面，需要他们单击按钮来重定向回您的网站。 该页面的以下属性是可自定义的：
- 可以通过指定 "gatewayRedirectDisplayTitle" 字段的值来自定义/国际化页面标题。
- 可以通过指定 "gatewayRedirectDisplayContinueButtonText" 字段的值来自定义/国际化按钮文本。
- 可以通过指定 "gatewayRedirectDisplayBackgroundColor" 字段的值来自定义背景颜色。
如果没有提供，则将应用默认值。
虽然未严格要求与 Hosted Payment Session 解决方案集成，但由于付款人详细信息被发布到 SSL 下的 Hosted Payment Session，这将提供以下优点：
-
通过显示浏览器挂锁来增加付款人的信心
-
在从 Hosted Payment Session 安全网站转换为您的不安全网站时将阻止付款人看到安全警告弹出窗口。 安全警告弹出窗口询问付款人是否要继续发送信息。
Hosted Payment Session 信息流
下方说明了 Hosted Payment Session 模型的详细付款流。
- 您使用
Create Session操作向 Mastercard Gateway 发起 Mastercard GatewayAPI 调用。 这将创建会话，其中将保存付款人的卡详细信息。 请参见通过 API 请求会话。 - Mastercard Gateway 使用会话识别码作出响应。
- 您的网站将建立包含付款单的付款页。
- 付款单向等待输入卡详细信息及其他所需信息的付款人显示。
此表单仅用于收集卡详细信息，而不用于执行付款。
- 付款人输入卡详细信息并单击您网站上的“提交”按钮，这将对 Hosted Payment Session 服务执行 HTTPS POST。 您必须将会话标识符嵌入到表单的操作字段中。 请参阅构建付款单。
- Mastercard Gateway 收集、验证（使用基本验证）并处理卡详细信息，然后将验证/修改后的表单发送回浏览器。 卡号、卡过期时间以及 CSC/CVV 数据等卡详细信息将从表单中提取并被添加到会话中。
- 验证后的表单使用 Submit Form 请求中指定的返回 URL 从付款人浏览器发布给您。 经过验证的表单包括来自 Mastercard Gateway 的 Hosted Payment Session 服务的请求字段和响应字段。
您在表单请求中传递的任何商家特定字段都将被返回，而不会在表单响应中经过任何处理。
- 您的网站验证商家特定字段。
- 您的网站将解析 Mastercard Gateway 的 Hosted Payment Session 服务返回的任何错误，并在遇到错误时重新显示付款页面。
当所有错误都得到解决后，您可以根据您的业务工作流选择向付款人显示更多页面，或者在收集卡详细信息时执行存储或付款交易。
在执行付款交易前，您可以为动态货币兑换 (DCC) 提交费率报价请求来检索付款人货币以及使用该货币的订单金额。
在此阶段，您还可以使用 3D 验证服务对付款人进行身份验证。 请注意，如果付款人接受 DCC 出价，那么您必须在身份验证请求中提供 DCC 信息。 - 您通过使用以下一项或多项操作指定付款金额（仅针对付款交易）来执行 Mastercard GatewayAPI 调用以发起付款或存储交易： Authorize、Pay、Tokenization。 可以使用多个卡详细信息来源提供卡详细信息。 有关详细信息，请参见使用会话执行操作。
- Mastercard Gateway 将交易结果发回给您。 您可以在 Pay/Authorize 后会话过期前执行后续的 Save 交易。
疑难解答和常见问题
付款单可能会返回各种类型的错误。 请参阅错误处理。
当尝试提交错误的表单时将显示错误页面。 以下情况将导致显示错误页面：
- 表单方法不是 HTTP POST。
- 表单 URL 格式不正确。
- 表单 URL 中传递了除 "charset" 之外的查询参数。
- 不支持的字符集作为查询参数传入表单 URL。
- 未提供 "gatewayReturnURL" 强制字段。
- "gatewayReturnURL" 强制字段不是绝对 URL。
- 在付款单中使用了预留字段名称。 当前仅预留字段名称为 "submit"（区分大小写），其应设置为按钮的 name 属性。
- 提交的认可字段包含多个值。 当在表单中多次定义字段时通常会发生此情况。
有 "name" 属性设置为 "submit" 的字段将阻止表单通过 JavaScript 发布重定向回您的网站。 这是因为通过 JavaScript 发布使用 form.submit() 函数执行。 因此，如果存在名为 "submit" 的表单元素，那么 JavaScript 将错误地参考此字段而不是执行此函数。 这是一个众所周知的 JavaScript 问题，很难解决。
商家定义字段将在表单响应中返回，不进行处理或由 Hosted Payment Session 保存。
发生这种情况的原因是，浏览器必须在执行 JavaScript 以回发到您的网站之前呈现 HTML 页面。 闪现是指 JavaScript 执行之前此页面显示的一个极短暂的时刻。 为确保付款人获得无缝体验，建议将"继续"页面的可自定义属性设置为维护网站外观的值。 有关如何自定义"继续"页面的详细信息，请参阅“最佳做法和建议”。 这还将确保浏览器未启用 JavaScript 的付款人会看到与您的网站外观一致的"继续"页面。