接入说明

环境说明

• 生产环境和沙盒环境的请求地址仅域名有所不同。您可以首先在沙盒环境中测试 Onerway API，测试完成后通过更改请求域名和配置参数切换到生产环境。

• 提供一个开户邮箱和对接测试环境的域名，用于创建沙盒环境测试商户 收到邮件后，根据邮件里的链接登入商户客户端，获取商户号、秘钥 选择合适的接入方式，开始接入

• 邮箱会用来创建沙盒账户 我们会给提交的域名添加白名单，只有添加了白名单的域名才能调用 Onerway API

• 获取商户信息 首次登录商户后台需重置密码，重置密码后，获取商户号、秘钥

环境配置

环境域名

环境	域名
沙盒环境	https://sandbox-api.onerway.com/payout
生产环境	https://api.onerway.com/payout

字段说明

必填规则

标识	说明
M	必填项
C	条件必填
N	选填项

付款流程（四阶段）

1️⃣ 启动与前置准备阶段

节点：开始 → 前置准备

收款方字段查询：

• 方法1： 通过 API 查询必填字段 POST /api/v1/acct/queryPaymentFeild
• 方法2： 联系客户经理，获取对应国家、币种、付款方式、主体类型下的必填字段模板

收款方字段准备：

• 按提板要求收集收款方信息

2️⃣ 发起付款阶段

分支判断：是否已通过时支付通道

条件	进入路径
✅ 已开通实时支付(联系Onerway开通)	实时支付路径
❌ 未开通实时支付	默认支付路径

🅰️ 默认支付路径

(1) 创建收款方ID

• 导入或录入收款方信息
• 调用接口：POST /api/v1/beneficiary/add；
• 返回：beneficiaryId。

(2) 收款方复用逻辑

• 判断 beneficiaryId 是否需复用：
  • ✅ 若可复用 → 直接使用旧用 beneficiaryId；
  • ❌ 若信息不一致 → 调用 POST /api/v1/beneficiary/edit 更新后使用旧 beneficiaryId。

(3) 发起付款请求

• 调用接口：POST /api/v1/txn/remittance；
• 进入付款交易处理。

---

🅱️ 实时支付路径

(1) 动态收款方信息提交

• 调用接口：POST /api/v2/txn/remittance；
• 请求体中包含实时填写的收款方信息（无需预创建 beneficiaryId）。

(2) 发起付款请求

• 系统直接进入付款交易处理。

3️⃣获取交易结果阶段

​获取交易结果阶段

结果获取方式：

1. 主动查询 调用接口：POST /api/v1/txn/query
2. 异步推送 系统通过 Webhook 推送交易结果

推送内容包括：

• 交易状态（成功 / 失败 / 处理中）
• 错误码及错误描述（如失败）

4️⃣ 交易结束阶段

判断交易状态：

• ✅ 成功

  • 获取电子回单 调用接口：POST /api/v1/txn/queryVoucher

• ❌ 非成功

  • 查询失败原因；
  • 可进人工处理或发起重试。