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 128
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. See formType
formDetailType	string	Form type actually completed and submitted by the user. See formType
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
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

Response Example

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "taxType": "TAX1099NEC",
    "formType": "UNKNOWN",
    "formDetailType": "W8IMY",
    "formStatus": "READY",
    "submitTime": "2026-04-25 19:43:03",
    "formDetail": "{\"orgName\":\"sgszdx\",\"incorporationCountry\":\"Benin\",\"incorporationCountryCode\":\"BJ\",\"disregardedEntity\":\"\",\"chapter3Status\":\"Territory financial institution\",\"ein\":\"\",\"hasFtin\":\"NO\",\"ftin\":\"\",\"reference\":\"\",\"certNotQi\":false,\"certTransmit\":false,\"certPool\":false,\"certQsl\":false,\"certAltStmt\":false,\"certQiEntity\":false,\"certQiPrimary\":false,\"certQiSection1446f\":false,\"certQiNominee\":false,\"withholdingCertificate\":\"\",\"withholdingStatement\":\"\",\"certQiQsl\":false,\"certQiInterest\":false,\"certQiForm1099\":false,\"certQiNoForm1099\":false,\"certQiPool\":false,\"certQiFlowThrough\":false,\"certQiQdd\":false,\"certTfiA\":true,\"certTfiB\":true,\"certTfiC\":true,\"certTfiD\":true,\"certTfiE\":true,\"certTfiF\":true,\"certUsbA\":false,\"certUsbB\":false,\"certUsbC\":false,\"certUsbD\":false,\"certUsbE\":false,\"certUsbF\":false,\"certWfp\":false,\"certNwfpA\":false,\"certNwfpB\":false,\"certNwfpC\":false,\"certNwfpD\":false,\"certNwfpE\":false,\"certNwfpF\":false,\"permCountry\":\"Madagascar\",\"permCountryCode\":\"MG\",\"permAddress1\":\"sgszdx\",\"permAddress2\":\"sgszdx\",\"permProvince\":\"sgszdx\",\"permProvinceCode\":\"\",\"permCity\":\"sgszdx\",\"permPostal\":\"12334\",\"mailCountry\":\"Reunion\",\"mailCountryCode\":\"RE\",\"mailAddress1\":\"dfgd\",\"mailAddress2\":\"sgszdx\",\"mailProvince\":\"sgszdx\",\"mailProvinceCode\":\"\",\"mailCity\":\"Saint-Louis\",\"mailPostal\":\"123\",\"capacityCert\":true,\"signature\":\"esdfds\",\"signDate\":\"2026-04-25\"}",
    "formFileUrl": "https://storage.onerway.com/tax/form_example.pdf"
  }
}

Status Notes

• formType represents the form type specified when the collection link was created. See formType
• formDetailType represents the form type actually completed and submitted by the user. It uses the same definition as formType
• For the meaning of formStatus, see formStatus
• When only the link has been created and no form has been submitted yet, formStatus may return MISSING
• When the form has been submitted and verification is in progress, formStatus may return PENDING_VERIFICATION
• When tax information collection and verification are complete, formStatus may return READY
• 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