交易流程​

本教程将阐述在交易流程中，SHOPLINE 平台是如何与支付应用的服务器互通，从而为商家和买家提供高质量的交易服务。

支付​

跳转支付模式​

使用跳转支付时，要在创建支付应用时选择 跳转。此模式一旦选择，不可修改。该模式下，买家在支付时将跳转至第三方支付页面完成支付。
以下流程说明了在跳转支付模式下，SHOPLINE 与支付应用间如何交互：

1. 买家点击完成订单按钮，触发付款请求（流程图中第 1 步）。
2. SHOPLINE 将向支付应用发起 付款请求，请求的地址为 支付应用扩展 中配置的付款 URL（流程图中第 2 步）。请求将携带重定向回 SHOPLINE 的 URL，买家在支付页面完成支付后，支付应用需要将其重定向到该地址。
3. 支付应用正常响应，并返回付款页面链接（流程图中第 3-4 步）。如果支付应用的接口响应不符合预期，此次支付将直接认为支付失败。
4. SHOPLINE 将买家重定向到付款页面链接（流程图中第 5-7 步）。
5. 买家在付款页面完成支付操作，支付应用根据买家行为（支付或取消支付），处理支付结果（流程图中第 8-9 步）。
6. 支付应用将买家重定向回 SHOPLINE，之后买家将在 SHOPLINE 的处理页等待最终支付结果（流程图中第 10-11 步）。
7. 最后，支付应用需要 同步支付结果 到 SHOPLINE（流程图中第 12 步）。

直连支付模式​

直连（一次性支付）​

使用直连（一次性支付）时，要在创建支付应用时选择 直连（一次性支付）。此模式一旦选择，不可修改。该模式下，买家将在 SHOPLINE 结账页内通过信用卡完成一次性支付。
以下流程说明了在直连（一次性支付）模式下，SHOPLINE 与支付应用间如何交互：

1. 买家在结账页面填写信用卡信息后，点击完成订单按钮（流程图中第 1 步）。
2. SHOPLINE 将向支付应用发起 付款请求，请求的地址为 支付应用扩展 中配置的付款 URL（流程图中第 2 步）。
   • 请求将携带买家在结账页面填写的信用卡信息，支付应用可以用这些信息处理支付。
   • 请求将携带重定向回 SHOPLINE 的 URL，买家在支付页面完成支付后，支付应用需要将其重定向到该地址。
3. 支付应用正常响应，并返回重定向链接（流程图中第 3-4 步）。
   • 如果本次交易需要进行 3D 验证，支付应用需要在此次响应结果中返回 3D 验证页面链接。SHOPLINE 会将买家重定向到该页面，以完成 3D 验证。支付应用需要确保买家完成 3D 验证后，能正确的重定向回 SHOPLINE（该流程类似于 跳转支付）。
   • 如果支付应用的接口响应不符合预期，此次支付将直接认为支付失败。
4. 买家将被重定向到 SHOPLINE 的处理页等待最终支付结果（流程图中第 5-6 步）。
5. 最后，支付应用需要 同步支付结果 到 SHOPLINE（流程图中第 7 步）。

直连（周期扣款）​

直连（周期扣款），允许买家在 SHOPLINE 结账页内完成信用卡授权，后续可通过支付工具周期性自动扣款。该模式下买家在 SHOPLINE 结账页内，交互流程类似直连（一次性支付）。

启用条件​

使用直连（周期扣款）时，要在创建支付应用时选择 直连（周期扣款）。此模式一旦选择，不可修改。
周期扣款分为 绑卡支付 和 代扣 两个流程：

1. 绑卡支付：在完成支付行为时，支付应用需要基于买家信用卡信息，生成支付工具并返回给 SHOPLINE。SHOPLINE 在后续的代扣流程中，将直接使用该支付工具进行扣款。
2. 代扣：SHOPLINE 将直接传递支付工具进行扣款，不会再传递买家信用卡信息。

绑卡支付​

此流程适用于首次支付或换绑场景（即更新后续自动扣款所使用的信用卡）。生成支付工具后，代扣时将使用该支付工具进行付款。
以下流程说明了在绑卡支付场景下，SHOPLINE 与支付应用间如何交互：

1. 买家在结账页面填写信用卡信息后，点击完成订单按钮（流程图中第 1 步）。
2. SHOPLINE 将向支付应用发起 付款请求，请求的地址为 支付应用扩展 中配置的付款 URL（流程图中第 2 步）。
   • 请求将携带买家在结账页面填写的信用卡信息，支付应用可以用这些信息处理支付。
   • 绑卡支付场景，将传递参数：recurringPayment=true 并且 userBehavior=bindPayment。
   • 请求将携带重定向回 SHOPLINE 的 URL，买家在支付页面完成支付后，支付应用需要将其重定向到该地址。
3. 支付应用正常响应，并返回重定向链接和 支付工具信息（流程图中第 3-4 步）。
   • 如果本次交易需要进行 3D 验证，请在此次响应结果中返回 3D 验证页面链接。SHOPLINE 会将买家重定向到该页面，以完成 3D 验证。支付应用需要确保买家完成 3D 验证后，能正确的重定向回 SHOPLINE（该流程类似于 跳转支付）。
   • 如果支付应用的接口响应不符合预期，此次支付将直接认为支付失败。
4. SHOPLINE 将保存支付工具信息，用于后续的代扣场景（流程图中第 5 步）。
5. 买家将被重定向到 SHOPLINE 的处理页等待最终支付结果（流程图中第 6-7 步）。
6. 最后，支付应用需要 同步支付结果 到 SHOPLINE（流程图中第 8 步）。

代扣​

此流程适用于绑卡成功后的代扣支付。代扣时使用支付工具进行付款。
以下流程说明了在代扣场景下，SHOPLINE 与支付应用间如何交互：

1. SHOPLINE 基于自身业务场景，将向支付应用发起 付款请求，请求的地址为 支付应用扩展 中配置的付款 URL（流程图中第 1 步）。
   • 请求中不包含任何卡片信息，而是包含从绑卡支付的响应信息或查询接口获取的 支付工具信息，支付应用需要用这些信息处理完成扣款。
   • 代扣场景，将传递参数：recurringPayment=true 并且 userBehavior=Recurring。
2. 支付应用正常响应，返回处理结果（流程图中第 2-3 步）。
   • 响应不需要携带 paymentUrl 信息，代扣场景是 SHOPLINE 代买家支付，在该场景下，买家不会参与交互。
   • 如果支付应用的接口响应不符合预期，此次支付将直接认为支付失败。
3. 最后，支付应用需要 同步支付结果 到 SHOPLINE（流程图中第 4 步）。

Apple Pay 支付模式​

使用 Apple Pay 时，要在创建支付应用时选择 Apple Pay。此模式一旦选择，不可修改。该模式下，买家将可以在 SHOPLINE 通过 Apple Pay 完成一次性支付。
Apple Pay 支付模式，支持快速结账和普通结账两种场景：

• 快速结账：SHOPLINE 将在商详页、购物车、结账页通过 payment_button tag 展示快速结账按钮。买家点击此按钮后，可在 Apple Pay 支付弹窗中，完成所有的结算信息填写，最后通过 Apple Pay 完成支付。
• 普通结账：SHOPLINE 将在结账页的支付方式模块，展示当前结账支持的所有支付方式，买家可以在此处选择 Apple Pay 进行普通结账。
  

以下流程说明了在 Apple Pay 支付模式下，SHOPLINE 与支付应用间如何交互：

1. 买家进入 SHOPLINE 结账页，SHOPLINE 服务端将向支付应用发起 支付配置查询请求，获取当前店铺 Apple Pay 的支付配置信息，并将其返回给结账页用于渲染 Apple Pay 支付按钮（流程图中第 1-7 步）。
2. 买家点击 Apple Pay 支付按钮，SHOPLINE 结账页拉起 Apple Pay 支付弹窗。买家在弹窗内填写完整结账信息（流程图中第 8-10 步）。
3. 买家确认结账信息并完成支付授权，SHOPLINE 结账页将支付工具信息提交至服务端。服务端向支付应用发起 付款请求，请求的地址为 支付应用扩展 中配置的付款 URL（流程图中第 11-13 步）。该请求将携带 paymentMethodInstrument 字段及重定向回 SHOPLINE 的 URL。买家最终完成支付后，支付应用需要将其重定向到该地址。
4. 支付应用处理付款请求并正常响应，返回重定向页面链接。SHOPLINE 服务端将该链接返回至客户端，用于后续的跳转处理（流程图中第 14-17 步）。
   • 如果本次交易需要进行 3D 验证，请在此次响应结果中返回 3D 验证页面链接。
   • 如果支付应用的接口响应不符合预期，此次支付将直接认为支付失败。
5. 买家访问返回的重定向页面链接。若该链接为 3D 验证链接，买家需在页面内完成验证操作。验证完成后，支付应用会将买家重定向回 SHOPLINE（流程图中第 18-22 步）。
6. 买家在 SHOPLINE 的处理页等待最终支付结果（流程图中第 23 步）。
7. 最后，支付应用需要 同步支付结果 到 SHOPLINE（流程图中第 24 步）。

Google Pay 支付模式​

使用 Google Pay 时，要在创建支付应用时选择 Google Pay。此模式一旦选择，不可修改。该模式下，买家将可以在 SHOPLINE 通过 Google Pay 完成一次性支付。
Google Pay 支付模式，支持快速结账和普通结账两种场景：

• 快速结账：SHOPLINE 将在商详页、购物车、结账页通过 payment_button tag 展示快速结账按钮。买家点击此按钮后，可在 Google Pay 支付弹窗中，完成所有的结算信息填写，最后通过 Google Pay 完成支付。
• 普通结账：SHOPLINE 将在结账页的支付方式模块，展示当前结账支持的所有支付方式，买家可以在此处选择 Google Pay 进行普通结账。
  

以下流程说明了在 Google Pay 支付模式下，SHOPLINE 与支付应用间如何交互：

1. 买家进入 SHOPLINE 结账页，SHOPLINE 服务端将向支付应用发起 支付配置查询请求，获取当前店铺 Google Pay 的支付配置信息，并将其返回给结账页用于渲染 Google Pay 支付按钮（流程图中第 1-7 步）。
2. 买家点击 Google Pay 支付按钮，SHOPLINE 结账页拉起 Google Pay 支付弹窗。买家在弹窗内填写完整结账信息（流程图中第 8-10 步）。
3. 买家确认结账信息并完成支付授权，SHOPLINE 结账页将支付工具信息提交至服务端。服务端向支付应用发起 付款请求，请求的地址为 支付应用扩展 中配置的付款 URL（流程图中第 11-13 步）。该请求将携带 paymentMethodInstrument 字段及重定向回 SHOPLINE 的 URL。买家最终完成支付后，支付应用需要将其重定向到该地址。
4. 支付应用处理付款请求并正常响应，返回重定向页面链接。SHOPLINE 服务端将该链接返回至客户端，用于后续的跳转处理（流程图中第 14-17 步）。
   • 如果本次交易需要进行 3D 验证，请在此次响应结果中返回 3D 验证页面链接。
   • 如果支付应用的接口响应不符合预期，此次支付将直接认为支付失败。
5. 买家访问返回的重定向页面链接。若该链接为 3D 验证链接，买家需在页面内完成验证操作。验证完成后，支付应用会将买家重定向回 SHOPLINE（流程图中第 18-22 步）。
6. 买家在 SHOPLINE 的处理页等待最终支付结果（流程图中第 23 步）。
7. 最后，支付应用需要 同步支付结果 到 SHOPLINE（流程图中第 24 步）。

手动入账模式​

手动入账模式允许商家先冻结买家资金，再根据实际情况（如发货后）手动完成扣款。

1. 启用条件​

手动入账模式的启用，需同时满足以下两个条件：

• 应用配置：如果你在 支付应用扩展 中配置了 Capture 接口 请求 URL 和 Void 接口 请求 URL，SHOPLINE 将认为该支付应用支持手动入账能力。
• 商家配置：商家在 SHOPLINE 商家后台 > 设置 > 收款 > 收款入账设置 中选择了 手动入账 模式。该模式才会对商家生效。

2. 授权请求​

当上述条件均满足时，SHOPLINE 发起的付款请求将包含 kind=authorization（具体字段请查看 付款请求接口文档），表明此次支付为授权类型。在授权类型的支付请求下，支付应用在确认买家授权后，不应该主动捕获授权金额；直到等待 SHOPLINE 请求 Capture 接口 或 Void 接口。

3. 请款或取消请款​

买家授权成功后，SHOPLINE 将根据商家操作，调用如下接口：

• Capture 接口：用于实际扣款。
  • 根据请款金额不同，将分为以下两种场景：
    • 全额入账：一次性扣款全部授权金额。
      • 示例：授权 100 USD，Capture 100 USD，此时代表一次性请款全部金额；
    • 部分入账：仅扣款部分金额，剩余授权金额必须被自动释放，返还给买家。
      • 示例：授权 100 USD，Capture 80 USD，则支付应用必须释放剩余的 20 USD。
  • 限制：每笔支付仅允许成功执行一次 Capture 操作。
• Void 接口：用于取消授权，释放全部冻结资金。

4. 结果同步​

Capture 和 Void 都是针对某笔支付的操作，最终的结果都需要支付应用 同步支付结果 到 SHOPLINE。

支付结果同步​

不管支付应用接入哪种支付方式，SHOPLINE 都将按以下方式获取支付结果：

• 支付应用主动通知：支付应用在支付达到 终态 后，应当调用 SHOPLINE 提供的 付款状态通知 API。SHOPLINE 接收到请求后，将调用 付款查询接口 确认最终的支付结果。SHOPLINE 在发起 付款请求 时，会在请求中携带 notifyUrl 参数，该参数是该笔支付的完整的 付款状态通知 API 的访问链接。
• SHOPLINE 主动查询：SHOPLINE 将在发起付款请求后的 24 小时内，以一定的频率向你在 支付应用扩展 中配置的付款查询 URL 发起 付款查询请求，直到获取到 终态 或者是超过最大请求次数。

支付状态​

SHOPLINE 支付将在以下状态中流转，如果某次支付已到达终态，SHOPLINE 将认为此次支付已完成，不会再同步任何新的状态；请谨慎对待支付状态的流程，以免造成不好的用户体验。
如果无法在发起付款请求 24 小时内达到以下两种特定状态，SHOPLINE 将不承认该订单的有效性，并认为该笔支付最终结果为 EXPIRED：

• 对于 Sale 类型的支付，需要在 24 小时内推动到 SUCCEEDED。
• 对于 Authorization 类型的支付，需要在 24 小时内推动到 AUTHORIZED。

常见问题​

问题一：完成支付后，发现页面一直停留在处理页。

答案一：此种情况，一般代表 SHOPLINE 无法从支付应用同步到 特定状态。此时，请检查是否有进行 支付结果同步。
问题二：支付应用在接收到付款请求时，没返回明确失败的情况下，结账页展示支付失败：

答案二：在发起付款请求时，如果支付应用的响应存在以下情况之一，该次支付将直接认为是支付失败：

• 没有任何响应体。
• 响应体签名验证不通过。
• 响应体中 returnCode 不为 SUCCESS。
  若出现上述情况，请检查请求参数是否符合 付款请求接口文档 。

退款​

退款流程​

以下流程说明了在商家进行退款时，SHOPLINE 与支付应用间如何交互。

1. 商家请求退款（流程图中第 1 步）。
2. SHOPLINE 将向支付应用发起 退款请求，请求地址为 支付应用扩展 中配置的退款 URL（流程图中第 2 步）。
3. 支付应用程序处理并响应接收成功（流程图中第 3-4 步）。调用该接口时，如果 SHOPLINE 无法获取到响应，或者响应验签失败，SHOPLINE 将在 24 小时内以同样的参数重试多次，直到返回格式正确或超过最大重试次数，请做好幂等处理。
4. 最后，支付应用需要 同步退款结果 到 SHOPLINE（流程图中第 5 步）。

退款结果同步​

不管支付应用接入哪种支付方式，SHOPLINE 都将按以下方式获取退款结果：

• 支付应用主动通知：支付应用在退款达到 终态 后，应当调用 SHOPLINE 提供的 退款状态通知 API。SHOPLINE 接收到请求后，将调用 退款查询接口 确认最终的退款结果。SHOPLINE 在发起 退款请求 时，会在请求中携带 notifyUrl 参数，该参数是该笔退款的完整的 退款状态通知 API 的访问链接。
• SHOPLINE 主动查询：SHOPLINE 将在发起退款请求后的 7 天内，以一定的频率向你在 支付应用扩展 中配置的退款查询 URL 发起 退款查询请求，直到获取到 终态 或者是超过最大请求次数。

退款状态​

SHOPLINE 退款将在以下状态中流转，如果某次退款已到达终态，SHOPLINE 将认为此次退款已完成，不会再同步任何新的状态；请谨慎对待退款状态的流程，以免造成不好的用户体验。

上报物流信息​

如果你在 支付应用扩展 中配置了物流上报接口地址，SHOPLINE 将认为该支付应用需要获取订单的物流信息。
以下流程说明了在商家进行发货时，SHOPLINE 与支付应用间如何交互。

1. 商家操作发货（流程图中第 1 步）。
2. SHOPLINE 将向支付应用发起 物流上报请求，请求地址为 支付应用扩展 中配置的物流上报 URL（流程图中第 2 步）。
3. 支付应用程序处理并响应接收成功（流程图中第 3-4 步）。调用该接口时，如果 SHOPLINE 无法获取到响应，或者响应验签失败，SHOPLINE 将在 24 小时内以同样的参数重试多次，直到返回格式正确或超过最大重试次数，请做好幂等处理。