API Reference

Create Collection Link

Generate a tax information collection link for a specified payee. The merchant can distribute the link directly, or let the platform send the form entry to a specified email address.

POST

Path/taxForm/v1/api/link

AuthenticationApiKey

Request Headers

Header Key	Required	Description	Format / Constraint
Content-Type	Yes	Fixed as application/json	Fixed value
ApiKey	Yes	Access credential issued by Onerway to the merchant	Must be provided

Request 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. Currently only TAX1099NEC is supported
formType	string	No	Tax information collection form type	See formType. Defaults to UNKNOWN
deliveryMode	string	No	Delivery mode	See deliveryMode. Defaults to LINK
recipientEmail	string	No	Recipient email address	Required when deliveryMode=EMAIL; must be a valid email address; maximum length 255

Request Example

{
  "merchantRefId": "payee_10001",
  "taxType": "TAX1099NEC",
  "formType": "W9",
  "deliveryMode": "LINK"
}

Response Parameters

Field	Type	Description
url	string	Collection link
taxType	string	Tax type
formType	string	Tax information collection form type

Response Example

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "url": "https://tax.example.com/form/abc123",
    "taxType": "TAX1099NEC",
    "formType": "W9"
  }
}

Error Code Mapping

Business Code	Sample Message	Scenario
95004	merchantRefId: merchantRefId is required	merchantRefId is missing
95004	taxType: taxType is required	taxType is missing
95004	invalid taxType	taxType is invalid
95004	invalid formType	formType is invalid
95004	invalid deliveryMode	deliveryMode is invalid
95004	recipientEmail is required	recipientEmail is missing when deliveryMode=EMAIL
95004	invalid recipientEmail	recipientEmail is not a valid email address
95006	Duplicate or concurrent request	Duplicate submission or concurrent creation conflict
95001	System error	Internal system error

Usage Recommendations

• If only one active collection form should exist for the same payee, it is recommended that the merchant enforce idempotency based on merchantRefId
• When EMAIL mode is used, validate the email address before calling the API
• Keep the mapping between merchantRefId and the returned link for later retrieval and troubleshooting