API Reference

Retrieve Form Details

Retrieve the latest status, form type, and submission result of the tax information collection form for a specified payee. This API can be used for status synchronization and webhook fallback queries.

GET

Path/taxForm/v1/api/detail

AuthenticationApiKey

Request Headers

Header Key	Required	Description	Format / Constraint
ApiKey	Yes	Access credential issued by Onerway to the merchant	Must be provided

Query Parameters

Field	Type	Required	Description	Validation Rule
merchantRefId	string	Yes	Unique identifier for the recipient in your system	Cannot be blank; maximum length 64
taxType	string	Yes	Tax type	See taxType

Request Example

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

Response Parameters

Field	Type	Description
taxType	string	Tax type. See taxType
formType	string	Form type specified when the collection link was created. This field may be a real form type, UNKNOWN, or UNION
availableFormTypes	array[string]	List of form types the payee can choose from for this link when formType=UNION
formDetailType	string	Form type actually completed and submitted by the user. This field is always a real form type
formStatus	string	Current form status. See formStatus
submitTime	string(datetime)	Submission time in YYYY-MM-DD HH:mm:ss format
formDetail	string	Form detail JSON string
feeDetail	array[object]	Fee records generated for this form. Returns an empty array when no fee has been charged
formFileUrl	string	Download link for a form-related file. This field is typically available only for forms in READY status. If the form is already READY but this field is empty, the related file is still being generated
failReason	string	Reason why the form failed. This field may be returned when formStatus=FAILED

feeDetail Field Details

Each fee record contains the following fields:

Field	Type	Description
id	string	Transaction flow number
amount	number	Fee amount
currency	string	Fee currency, for example USD
chargeTime	string(datetime)	Fee charge time in YYYY-MM-DD HH:mm:ss format
feeType	string	Fee type

Response Example

{
  "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"
  }
}

Status Notes

• formType represents the form type specified when the collection link was created. See formType
• availableFormTypes is returned when formType=UNION and represents the list of form types configured by the merchant for this link
• formDetailType represents the form type actually completed and submitted by the user. It is always a real form type and never UNKNOWN or UNION
• For the meaning of formStatus, see formStatus
• When only the link has been created and no form has been submitted yet, formStatus returns MISSING
• When the form has been submitted and verification is in progress, formStatus returns PENDING_VERIFICATION
• When tax information collection and verification are complete, formStatus returns READY or FAILED
• feeDetail returns the TIN verification fee records related to the current form
• When formStatus=FAILED, failReason returns the failure reason
• When the form verification fails or the form has expired, the merchant should handle the next step based on webhook results or business rules

Error Code Mapping

Business Code	Sample Message	Scenario
95005	form link not found	No collection record is found based on merchantRefId + taxType
95001	System error	Internal system error

Usage Recommendations

• This API is suitable as a fallback for webhook delivery and is not recommended for high-frequency polling
• formDetail is a JSON string. Parse it before structured processing if needed
• formFileUrl is suitable for scenarios where the merchant needs to display or download form-related files