通过收款方ID进行付款

概述

本节详细说明如何通过 API 调用进行完整的付款流程。付款流程由以下三个阶段组成：

• 阶段 1：预集成设置
• 阶段 2：收款方 ID 创建或复用（收集收款方信息，生成 payeeId）
• 阶段 3：发起付款（必须包含有效的 payeeId）

1 使用前准备

步骤 1：环境要求

环境要求

所有集成必须首先在 Sandbox 环境中进行测试。确保功能正确后再切换至 Production 环境。

环境	用途
Sandbox 环境	用于集成测试和调试
Production 环境	用于正式交易

提示

详细信息请参考 接入说明

步骤 2：接入签名

安全要求

在调用任何 API 之前，您必须生成一个签名（sign）并使用您的私钥（privateKey）来确保请求安全。

完整的签名说明请参见：

INFO

参考文档 接入签名

步骤 3：确认付款方式

在发起付款前，您应该根据业务需求选择合适的付款方式：

• LOCAL（本地转账）
• SWIFT（国际电汇）
• 数字钱包

可用的付款方式取决于目标国家、币种等因素。

INFO

参考文档 付款方式查询接口

步骤 4：确认收款方必填字段

根据以下参数获取必填字段信息：

• 国家
• 币种
• 主体类型（个人/企业）
• 付款方式

系统会根据这些参数返回完整的必填字段列表，确保付款方信息完整合规。

INFO

参考文档 收款方必填字段查询接口

步骤 5：以他人身份代付（可选）

如果您需要代表个人或实体（例如平台代创作者付款），您需先添加付款方信息。

代付场景：

• 平台以子商户名义向收款方付款

INFO

参考文档 付款人添加接口

2 收款方ID 的创建或复用

在发起付款前，您需要确认是否已拥有目标收款方的 payeeId。每一个收款方（账户）都由系统生成唯一的 payeeId，后续付款请求都需基于该 ID 进行提交。

操作流程与判断说明

1. 查询是否已有 payeeId

   • 首先建议直接调用 收款方创建接口，尝试按目标收款方信息（如账户、姓名、主体、收款方式等）主动发起收款方创建操作。
   • 如果接口返回正常，即创建成功，则接口会返回新的 payeeId，后续付款直接使用该 ID。
   • 如果接口返回报错，此时应调用 收款方列表查询接口，通过详细信息查找并获取已存在的 payeeId，然后继续后续付款。
     • 注意：不同币种、付款方式、主体类型可能要求补充不同的必填字段，确保提交信息完整合规。

2. 后续操作

   • 获取到的 payeeId 作为发起付款 API 的必填参数，在每笔付款时引用。
   • 同一个收款方仅需创建一次，后续再次付款只需复用对应的 payeeId。

场景	处理方式
收款方已存在	查询收款方，获取并复用其 payeeId。
收款方为全新信息	调用创建接口，获得新 payeeId 后使用。

总体流程可简化为："有则复用，无则创建"，确保每次付款请求都明确关联至唯一的收款方 ID。

3 发起一笔付款

接口说明

INFO

接口信息：通过收款方ID发起付款接口

提交前请确认

检查项	要求
付款方状态	付款方状态有效
账户余额	账户余额充足
扣费模式	扣费模式（固定金额或实际金额）已正确设置