- 集成指南
- 支持的功能（付款选项）
- 付款链接
付款链接
付款链接是一种通过简单的付款链接 URL 接收付款的安全方法。 使用此方法，您可以提供额外的接受付款模式：生成付款链接 URL，然后通过各种通信渠道（如电子邮件、文本消息和 QR 码）与付款人共享此链接。 当付款人点击付款链接 URL 时，他们将被重定向到付款页面，可以在那里选择付款方式来完成交易。
主要优点
付款链接的主要优点有
- 简化付款流程
- 提升客户体验
- 加快付款速度，以及
- 允许您在交易失败或购物车被放弃后跟进客户。
使用付款链接
当付款人收到付款的唯一付款链接 URL 时，他们可以点击该链接完成付款。
下图显示了使用付款链接完成交易的不同步骤。
- 输入付款信息，如发票编号、总金额和生成付款链接 URL 的请求。
- 网关生成一个您可以与付款人共享的唯一链接。
- 当付款人点击链接时，他们将被重定向到 Hosted Checkout 页面。
- 付款人在 Hosted Checkout 页面输入付款信息并完成交易。
请求 Initiate Checkout 操作
先决条件
在发起结账操作之前，请确保为付款链接设置了以下属性：
- apiOperation： 将字段值设置为 INITIATE_CHECKOUT。
- checkoutMode： 将字段值设置为 PAYMENT_LINK。
- interaction.operation： 选择交易类型 AUTHORIZE 或 PURCHASE。
- interaction.merchant.name： 在结账页面向付款人显示的您的企业的名称。
- interaction.merchant.url： 您的企业网站的 URL。
- order.amount： 订单的总额。 等于净额加上所有附加费。
- order.currency： 订单货币。
- order.description： 订单内容的简短文字描述。
- paymentLink.errorUrl： 如果调用付款链接时出现错误（例如订单已支付、付款链接过期、付款链接无效等），您希望将付款人浏览器重定向到的 URL。
如果指定并且出现错误，网关将提供错误代码 (
errorCode) 和说明 (errorDescription) 作为查询字符串参数。 网关还将保留您可能包含在 errorUrl 中的任何查询字符串参数。例如，如果您将 paymentLink.errorUrl 指定为https://merchant.com/myPaymentLinkErrorPage.html，如果发生错误，此 errorUrl 将从网关接收以下查询字符串参数： https://merchant.com/myPaymentLinkErrorPage.html?errorCode=ERROR_CODE&errorDescription=Error+message。 请参见错误代码和说明部分了解更多信息。
此字段为可选字段。 如果未指定此字段，则付款人在发生错误时将被重定向到默认错误屏幕。 - order.id： 将此订单与您创建的所有其他订单区分开的唯一识别码。
- paymentLink.expiryDateTime： 此付款链接的过期日期和时间。 默认为 3 个月。
- paymentLink.numberOfAllowedAttempts： 在付款人无法再使用付款链接进行支付之前允许付款人尝试的次数。 默认为 25 次。
请求示例
要创建付款链接 URL，您必须请求具有 payment link 模式的 Initiate Checkout 操作。 下面是 Initiate Checkout 操作的一个示例代码段。
{
"apiOperation": "INITIATE_CHECKOUT",
"checkoutMode": "PAYMENT_LINK",
"interaction": {
"operation": "AUTHORIZE",
"merchant": {
"name": "<your_merchant_name>",
"url": "<website_url>"
}
},
"order": {
"currency": "USD",
"amount": 1234,
"id": "<order_ID>",
"description": "Ordered goods"
},
"paymentLink": {
"expiryDateTime": "2021-12-10T02:16:00.993Z",
"numberOfAllowedAttempts": "3"
}
}
Initiate Checkout API 参考 [REST][NVP]
此操作的成功响应包含付款链接 URL 和付款链接 ID 参数，这些信息可以与客户共享来完成付款。
响应示例
{
"checkoutMode": "PAYMENT_LINK",
"merchant": "<your_merchant_id>",
"paymentLink": {
"expiryDateTime": "2021-12-10T02:16:00.993Z",
"id": "PAYLINK0001060519617G19059484L2",
"numberOfAllowedAttempts": 3,
"url": https://network.gateway.mastercard.com/pbl/PAYLINK0001060519617G19059484L2
},
"result": "SUCCESS",
"successIndicator": "c89f62baad174e12"
}
分享付款链接
商家通过电子邮件、文本消息和 QR 码等各种通信渠道与付款人共享付款链接。 付款人点击付款链接后将被重定向到浏览器中的 Hosted Checkout 付款页，然后使用其中一种可用的付款方式完成交易。
删除付款链接
如果付款人已将付款下线或不再需要付款，您可以使用 Delete Payment Link 操作明确删除付款链接或使其无效。
| URL | https://network.gateway.mastercard.com/api/rest/version/64/merchant/{merchantId}/link/{linkId} |
| HTTP 方法 | DELETE |
Delete Payment Link API 参考 [REST][NVP]
出现以下情况时，网关会自动将会话作为过期处理：
- 付款链接生成后 3 个月内未进行付款，付款人将无法再使用该付款链接付款
- 尝试付款的次数超过 25 次，付款人将无法再访问该付款链接完成交易
- 使用付款链接的付款已完成，或
- 商家发起删除请求。
测试付款链接
在设置账户并构建集成后，您应使用测试商家配置文件（商家 ID 以“TEST”开头）测试付款链接。 网关会提供一个测试 Hosted Checkout 页面来验证付款链接。
- 通过 INITIATE_CHECKOUT 操作输入付款详细信息并请求付款链接。 当 INITIATE CHECKOUT 操作成功时将返回一个付款链接 URL。
- 使用卡交易测试详细信息中列出的测试卡完成付款。
Webhook 通知
建议您选择通知服务来在付款成功时接收 Webhook 通知。 有关 Webhook 通知和配置的更多信息，请参阅 Webhook 通知。
错误代码和说明
此表列出了错误代码及说明。
| 错误代码 | 说明 |
|---|---|
| EXPIRED | 付款链接已过期。 请联系付款请求者。 |
| 已支付 | 与此付款链接关联的订单已支付。 请联系付款请求者 |
| USAGE_COUNT_EXCEEDED | 已超出允许的最大尝试次数。 请联系付款请求者 |
| DOES_NOT_EXIST | 此付款链接无效。 请联系付款请求者 |
| UNEXPECTED_ERROR | 发生意外错误。 请联系付款请求者 |
| DELETED | 此付款链接已删除。 请联系付款请求者 |