# 集成流程

> 按四阶段流程完成 Transfer 集成，从前置准备到结果闭环。

Transfer 接入可分为四个阶段：前置准备、发起打款、获取结果和交易结束。

## 概述

<tip>

发起打款前，请先确认收款方字段要求。必填字段会随着国家、币种、打款方式和主体类型的不同而变化。

</tip>

## 第一阶段：前置准备

### 确认收款方字段要求

可使用以下方式之一：

- 调用 `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 打款处理流程

完成这一步后，交易就进入处理阶段。同步响应只能说明请求已被系统接收，不代表最终结果已经确认。

### 实时路径

<note>

实时打款需要由 Onerway 预先开通。

</note>

#### 1. 动态提交收款方信息

- 调用 `POST /api/v2/txn/remittance`
- 在请求体中直接提交收款方信息
- 无需预先创建 `beneficiaryId`

#### 2. 发起打款

- 提交请求
- 交易直接进入打款处理流程

相比默认路径，实时路径少了一步“预创建收款方”。这条路径有开通前提，不能默认认为所有商户都可以直接使用。

## 第三阶段：获取结果

可以通过以下两种方式获取打款结果：

1. 主动查询：`POST /api/v1/txn/query`
2. 异步通知：webhook 回调

### 结果获取方式

结果获取分成“主动查询”和“异步推送”两条线：

- 主动查询适合补偿确认、对账或排查问题
- 异步推送适合作为生产环境里的主结果通道

### 推送内容包括

回调报文中通常包含：

- 交易状态
- 失败时的错误码
- 失败时的错误描述

这也是为什么同步响应成功后仍然要继续跟踪最终状态。

## 第四阶段：交易结束

### 打款成功

- 调用 `POST /api/v1/txn/queryVoucher` 获取电子回单

### 打款未成功

- 查询失败原因
- 按内部流程进入人工处理或重试

这一阶段的重点是：

- 成功单据进入留痕、回单下载和对账流程
- 非成功单据需要按错误原因进入重试或人工处理流程
- 只有完成结果确认和后续动作，交易链路才算真正闭环

## 推荐操作方式

生产环境建议采用以下模式：

- 以 webhook 作为主结果通道
- 保留查询接口，用于对账、重试判断和兜底确认
- 在信息仍然有效时复用已有收款方记录

## 注意事项

- 未开通实时路径时，应优先走默认路径，不要直接提交实时打款请求
- 使用默认路径时，请妥善保存 `beneficiaryId`，避免重复创建收款方
- 打款请求成功受理后，仍需通过 webhook 或查询接口确认最终结果
- 交易成功后如需留痕或提供凭证，应继续调用电子回单接口

## 继续阅读

- [环境准备](/zh/transfer/get-started)
- [请求签名](/zh/transfer/get-started/request-signing)
- [测试与上线](/zh/transfer/get-started/testing-and-go-live)