接入指南
Transfer 接入可分为四个阶段：前置准备、发起打款、获取结果和交易结束。
概述
发起打款前，请先确认收款方字段要求。必填字段会随着国家、币种、打款方式和主体类型的不同而变化。
第一阶段：前置准备
确认收款方字段要求
可使用以下方式之一：
- 调用
POST /api/v1/acct/queryPaymentFeild查询必填字段 - 联系客户经理，获取目标国家、币种、打款方式和主体类型对应的字段模板
准备收款方信息
拿到字段要求后，请按返回结果或模板收集并校验收款方信息。
这一阶段的重点是：
- 先确认目标国家和币种下支持的打款方式
- 再确认该打款方式下的必填字段
- 按字段模板准备收款方、地址和账户信息
如果前置字段没有确认完整，后续无论是创建收款方还是直接发起打款，都容易因为字段缺失或格式不符而失败。
第二阶段：发起打款
判断使用哪条路径
| 条件 | 路径 |
|---|---|
| 已由 Onerway 开通实时打款 | 实时路径 |
| 未开通实时打款 | 默认路径 |
- 已开通实时路径时，可以在一次请求中直接提交收款方信息并发起打款
- 未开通实时路径时，需要先维护收款方，再通过
beneficiaryId发起打款
默认路径
1. 创建收款人 ID
- 录入或导入收款方信息
- 调用
POST /api/v1/beneficiary/add - 保存返回的
beneficiaryId
这一步是默认路径的起点。默认路径不是“边填边打款”，而是先把收款方资料沉淀成可复用的记录。
2. 收款方复用逻辑
- 判断已有
beneficiaryId是否可以继续复用 - 如信息一致，可直接继续使用已有
beneficiaryId - 如信息不一致，先调用
POST /api/v1/beneficiary/edit更新，再继续使用原beneficiaryId
这里需要优先复用已有收款方记录。如果收款方信息仍然有效，优先复用原记录；只有信息发生变化时，才先更新再继续下发。
3. 发起打款请求
- 调用
POST /api/v1/txn/remittance - 交易进入 Onerway 打款处理流程
完成这一步后，交易就进入处理阶段。同步响应只能说明请求已被系统接收，不代表最终结果已经确认。
实时路径
实时打款需要由 Onerway 预先开通。
1. 动态提交收款方信息
- 调用
POST /api/v2/txn/remittance - 在请求体中直接提交收款方信息
- 无需预先创建
beneficiaryId
2. 发起打款
- 提交请求
- 交易直接进入打款处理流程
相比默认路径，实时路径少了一步“预创建收款方”。这条路径有开通前提，不能默认认为所有商户都可以直接使用。
第三阶段：获取结果
可以通过以下两种方式获取打款结果：
- 主动查询：
POST /api/v1/txn/query - 异步通知：webhook 回调
结果获取方式
结果获取分成“主动查询”和“异步推送”两条线：
- 主动查询适合补偿确认、对账或排查问题
- 异步推送适合作为生产环境里的主结果通道
推送内容包括
回调报文中通常包含：
- 交易状态
- 失败时的错误码
- 失败时的错误描述
这也是为什么同步响应成功后仍然要继续跟踪最终状态。
第四阶段：交易结束
打款成功
- 调用
POST /api/v1/txn/queryVoucher获取电子回单
打款未成功
- 查询失败原因
- 按内部流程进入人工处理或重试
这一阶段的重点是：
- 成功单据进入留痕、回单下载和对账流程
- 非成功单据需要按错误原因进入重试或人工处理流程
- 只有完成结果确认和后续动作，交易链路才算真正闭环
推荐操作方式
生产环境建议采用以下模式：
- 以 webhook 作为主结果通道
- 保留查询接口，用于对账、重试判断和兜底确认
- 在信息仍然有效时复用已有收款方记录
注意事项
- 未开通实时路径时，应优先走默认路径，不要直接提交实时打款请求
- 使用默认路径时，请妥善保存
beneficiaryId，避免重复创建收款方 - 打款请求成功受理后，仍需通过 webhook 或查询接口确认最终结果
- 交易成功后如需留痕或提供凭证，应继续调用电子回单接口