Guide

接入说明

Tax API 面向商户提供收款方税务信息采集链接生成、采集状态查询与异步通知能力。本文档用于帮助您快速完成环境准备、密钥获取、回调配置与联调流程。

Sandbox ReadyWebhook SupportedTax Info Collection

环境配置

环境	请求地址	说明
沙盒环境	https://sandbox-api.onerway.com/tax	建议先完成联调、验签与回调测试
生产环境	https://api.onerway.com/tax	用于正式业务调用

接入前准备

• 提供开户邮箱和测试环境使用的出口 IP，用于创建沙盒测试商户并配置 IP 白名单
• 收到邮件后，登录商户客户端获取商户号、ApiKey 和 Webhook Secret
• 首次登录商户后台需重置密码，完成后即可查看和管理接入信息
• 仅已加入白名单的 IP 可访问相关接口

返回结构

所有接口均返回统一 JSON 结构：

字段	类型	说明
respCode	string	业务返回码，20000 表示成功
respMsg	string	返回信息，默认使用英文文案
data	object / array / string / null	业务数据

接入信息

完成开户后，您将获得以下信息：

信息项	说明	用途
Merchant No	商户号	用于标识商户身份
ApiKey	接口访问密钥	用于接口请求鉴权
Webhook Secret	回调验签密钥	用于校验异步通知签名

核心概念

merchantRefId

merchantRefId 是商户在调用 Onerway Tax 接口时传入的收款人标识，代表商户系统中的用户ID。该字段将作为该收款人在 Tax 模块中的唯一标识，后续状态查询、异步通知等能力都会通过该字段进行关联。

• 在同一商户范围内必须唯一
• 建议使用商户系统中稳定且不会频繁变化的用户ID

接入流程

1. 准备回调地址

在联调前，请准备好以下能力：

• 可被 Onerway 访问的通知接收地址
• 商户系统内部的验签逻辑
• 商户系统内部的幂等处理逻辑

注意

请确保回调地址稳定且可公网访问。如地址发生变更，请及时联系 Onerway 技术团队更新配置。

2. 完成联调

推荐按以下顺序接入：

1. 阅读 鉴权说明，确认请求头传参与调用方式
2. 阅读 Webhook 接入，完成回调校验与接收逻辑
3. 阅读 枚举定义，确认税务信息采集相关字段取值
4. 调用 生成表单采集链接，为收款人创建税务信息采集填写入口
5. 调用 查询表单信息 或通过 Webhook 获取采集状态结果

业务流程

信息采集发起

• 商户调用生成表单采集链接接口，传入 merchantRefId（商户系统中的用户ID）
• 平台返回填写链接，或按配置发送到指定邮箱
• 收款人访问链接后，根据自身情况自行选择表单并完成税务信息填写与提交

验证处理

• 表单提交后，平台会根据表单类型执行相应的验证与信息校验流程
• 验证进行中时，表单状态为 PENDING_VERIFICATION
• 验证完成后，表单状态将更新为 READY 或 FAILED

状态获取

• 商户可通过查询接口主动获取采集状态
• 平台也会通过 Webhook 推送状态变化结果

结果处理

• 当表单状态为 READY 时，表示税务信息采集和验证完成，可进入后续业务处理流程（如允许提现）
• 当表单状态为 FAILED 时，应根据结果引导重新填写或人工处理
• 当表单状态为 EXPIRED 时，可重新生成表单采集链接并再次发起填写

相关文档

• 鉴权说明
• Webhook 接入
• 枚举定义
• 生成表单采集链接
• 查询表单信息