查询收款方
概述
查询收款方用于查看并管理已创建的收款人信息。通过传入 beneficiaryId 或批量查询条件（如国家、币种、状态等），您可以从系统中获取收款方的详细信息（姓名、账户、地址、验证状态等）。
使用场景
这一步通常用于在付款前校验收款方信息是否仍有效，或在系统间同步已创建的收款人清单。
查询方式
方式一：单笔查询
精确查询：
- 通过 beneficiaryId 查询收款方详情查询接口
- 获取完整的收款方详情
- 适用于付款前验证
方式二：批量查询
列表查询：
- 支持条件筛选收款方列表查询接口
- 支持分页查询
- 适用于系统同步和对账
单笔查询
适用场景
单笔查询用于获取指定收款方的详细信息。
| 场景 | 说明 |
|---|---|
| 验证收款方 | 验证收款方是否创建成功并可用 |
| 付款前校验 | 在发起付款前，验证 beneficiaryId 对应的信息 |
| 审核状态检查 | 检查审核状态 |
操作流程
- 步骤 1：调用查询接口，传入 beneficiaryId 收款方详情查询接口
- 步骤 2：系统返回详细信息
- 基础信息（姓名、国家）
- 账户信息（银行账号、银行代码）
- 审核状态
- 创建时间、更新时间
- 步骤 3：根据状态决定操作
- PASS → 可以发起付款通过收款方ID发起付款接口
- PROCESS → 等待审核
- REJECT → 需要重新提交
示例场景
场景 1：财务人员核实信息
- 查询收款方详细信息
- 确认信息准确合规
- 决定是否批准付款
场景 2：系统自动验证
- 用户提交收款信息
- 系统自动验证创建成功
- 显示给运营人员确认
批量查询
适用场景
批量查询用于获取多个收款方的信息及列表，支持分页、筛选等参数传递。
| 场景 | 说明 |
|---|---|
| 系统同步 | 批量同步已创建收款方到外部账务系统 |
| 状态监控 | 定期查询收款方的审核状态和批量校验 |
| 财务对账 | 确认系统与 Onerway 平台信息一致 |
操作流程
- 步骤 1：调用批量查询接口收款方列表查询接口
- 可设置筛选条件：国家（Country）、币种（Currency）、收款方状态（payeeStatus）、分页参数（Size）
- 步骤 2：系统返回分页列表
- 每条记录包含：beneficiaryId、姓名账户信息、状态、创建时间
- 步骤 3：同步到内部系统
- 用于对账
- 用于批量发放
示例场景
场景 1：每日定时同步
- 每日凌晨执行批量查询
- 同步所有当天新创建的收款方
- 更新内部系统数据库
场景 2：状态监控
- 定期检查所有收款方的状态变化
- 识别：等待审核 → 已通过
- 触发后续业务流程
场景 3：跨团队协作
- 对跨团队共享的收款人库进行更新
- 确保所有团队信息一致
- 避免重复创建
查询方式对比
| 查询方式 | 适用场景 | 优点 | 建议使用频率 |
|---|---|---|---|
| 单笔查询 | 发起单笔付款前确认 | 即时、准确 | 实时调用 |
| 批量查询 | 日常维护与同步 | 全量、可追踪 | 每日或每周定期任务 |
注意事项
重要提示
只读操作
- 查询接口仅供读取功能，不影响收款方的使用状态
数据一致性
- 建议结合系统回调与定期查询，确保信息完整、最新
性能优化
- 批量查询时请使用分页，避免一次性加载过多数据
安全性
- 敏感信息（如银行账号）可能会被部分脱敏显示
常见问题
Q1：查询到的状态是 PROCESS，能否发起付款？
解答
不能。只有状态为 PASS 的收款方才能用于付款。PROCESS 状态表示正在审核中。
Q2：批量查询最多能查询多少条记录？
解答
建议单次查询不超过 100 条，可以通过分页多次查询获取全部数据。
Q3：查询接口有频率限制吗？
解答
有的，建议单笔查询不超过 100 次/分钟，批量查询不超过 10 次/分钟。