API Reference

查询表单信息

查询指定收款人当前税务信息采集表单的最新状态、表单类型和回填结果，可作为状态同步与回调兜底的查询手段。

GET

Path/taxForm/v1/api/detail

AuthenticationApiKey

请求头

Header Key	必填	说明	格式 / 长度约束
ApiKey	是	Onerway 提供给商户的访问密钥	必须传入

Query 参数

字段	类型	必填	说明	校验规则
merchantRefId	string	是	商户系统中的用户ID	不可为空白；最大长度 64
taxType	string	是	报税类型	取值见 taxType

请求示例

GET /taxForm/v1/api/detail?merchantRefId=payee_10001&taxType=TAX1099NEC

响应参数

字段	类型	说明
taxType	string	报税类型，取值见 taxType
formType	string	创建链接时指定的表单类型，可能为真实表单类型、UNKNOWN 或 UNION
availableFormTypes	array[string]	当 formType=UNION 时，返回当前链接下收款人可选择的表单类型列表
formDetailType	string	用户实际填写并提交的真实表单类型
formStatus	string	当前表单状态，取值见 formStatus
submitTime	string(datetime)	提交时间，示例格式为 YYYY-MM-DD HH:mm:ss
formDetail	string	表单详情 JSON 字符串
feeDetail	array[object]	当前表单产生的费用记录；未产生费用时返回空数组
formFileUrl	string	可供下载的表单相关文件链接；通常仅 READY 状态的表单可能返回该字段，如 READY 但字段为空，表示相关文件仍在生成中
failReason	string	表单失败原因；当 formStatus=FAILED 时可能返回该字段

feeDetail 字段说明

每条费用记录包含以下字段：

字段	类型	说明
id	string	动账流水号
amount	number	费用金额
currency	string	费用币种，例如 USD
chargeTime	string(datetime)	费用扣费时间，示例格式为 YYYY-MM-DD HH:mm:ss
feeType	string	费用类型

响应示例

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "taxType": "TAX1099NEC",
    "formType": "UNION",
    "availableFormTypes": ["W9", "W8IMY"],
    "formDetailType": "W8IMY",
    "formStatus": "READY",
    "submitTime": "2026-04-25 19:43:03",
    "formDetail": "{\"orgName\":\"sgszdx\",\"incorporationCountry\":\"Benin\",\"incorporationCountryCode\":\"BJ\",\"disregardedEntity\":\"\",\"chapter3Status\":\"Territory financial institution\"}",
    "feeDetail": [
      {
        "id": "2068968158832234497",
        "amount": 3.00,
        "currency": "USD",
        "chargeTime": "2026-06-22 16:03:51",
        "feeType": "TIN_MATCH"
      }
    ],
    "formFileUrl": "https://storage.onerway.com/tax/form_example.pdf",
    "failReason": "TIN mismatch"
  }
}

状态说明

• formType 表示创建链接时指定的表单类型，取值定义见 formType
• availableFormTypes 在 formType=UNION 时返回，表示商户为当前链接配置的可选表单类型列表
• formDetailType 表示用户实际填写并提交的真实表单类型，永远不会是 UNKNOWN 或 UNION
• formStatus 的取值定义见 formStatus
• 当仅创建了链接、尚未提交表单时，formStatus 返回 MISSING
• 当表单已提交且验证进行中时，formStatus 返回 PENDING_VERIFICATION
• 当税务信息采集和验证完成时，formStatus 返回 READY 或 FAILED
• feeDetail 返回当前表单关联的TIN验证费用记录
• 当 formStatus=FAILED 时，failReason 返回失败原因
• 当表单校验失败或已过期时，商户应结合 Webhook 或业务规则引导后续处理

错误码映射

业务码	message 示例	场景说明
95005	form link not found	根据 merchantRefId + taxType 未查询到采集记录
95001	System error	系统内部异常

使用建议

• 查询接口适合作为 Webhook 的兜底手段，不建议高频轮询
• formDetail 为 JSON 字符串，商户侧如需结构化处理，请先解析
• formFileUrl 适用于需要展示或下载表单相关文件的场景