API Reference

Status Notification

When the status of a tax information collection form changes, the platform sends an asynchronous callback to the merchant's configured webhook endpoint. The current notification is used to deliver form status changes.

POST

PathMerchant Webhook URL

Authenticationx-signature

Delivery Method

Item	Description
HTTP Method	POST
Content-Type	application/json;charset=UTF-8
Event Type	tax.form.status.change

Request Headers

Header Key	Type	Required	Description	Format / Constraint
Content-Type	string	Yes	Fixed as application/json;charset=UTF-8	Fixed value
x-timestamp	string	Yes	Unix timestamp	Seconds-level timestamp string
x-signature	string	Yes	Hex signature generated with webhook_secret	64-character hex string

For authentication and the standard request structure, see Webhook.

Trigger Scenarios

The platform sends a status notification when the tax information collection form status changes to one of the following values:

• READY
• FAILED
• EXPIRED

Note

The PENDING_VERIFICATION status does not trigger webhook notifications. If you need to retrieve this status, call the detail query API actively.

eventType

tax.form.status.change

Request Body

Top-level Fields

Field	Type	Description	Format / Constraint
requestId	string	Notification request ID	-
eventType	string	Fixed as tax.form.status.change	Fixed value
createdAt	string	Notification creation time	Time string in YYYY-MM-DD HH:mm:ss format
version	string	Currently fixed as v1.0	Fixed value, length 4
data	object	Tax information collection form payload	See the structure below

data Fields

Field	Type	Description	Format / Constraint
merchantNo	string	Merchant number	-
merchantRefId	string	Unique identifier for the recipient in your system	Originates from the merchant request; maximum length 128
taxType	string	Tax type. See taxType	Enum value
formType	string	Tax information collection form type. See formType	Enum value
formStatus	string	Latest form status. See formStatus	Enum value
submitTime	string(datetime) / null	Form submission time	Time string in YYYY-MM-DD HH:mm:ss format, or null

Callback Example

POST /notify/10001 HTTP/1.1
Content-Type: application/json;charset=UTF-8
x-timestamp: 1777012345
x-signature: 4d2f...

{
  "requestId": "1987654321123456789",
  "eventType": "tax.form.status.change",
  "createdAt": "2026-04-27 17:20:31",
  "version": "v1.0",
  "data": {
    "merchantNo": "10001",
    "merchantRefId": "payee_10001",
    "taxType": "TAX1099NEC",
    "formType": "W9",
    "formStatus": "READY",
    "submitTime": "2026-04-27 17:18:01"
  }
}

Field Notes

formStatus

Value	Description
READY	Tax information collection and verification are complete, and downstream business processing can continue, such as allowing withdrawals
FAILED	The form verification failed and the payee should refill the form or it should be handled manually
EXPIRED	The form has expired and a new collection link is recommended

For the full definition, see Enumerations.

Merchant Handling Recommendations

• Verify the signature before processing business logic
• Use requestId for notification-level idempotency control
• It is recommended to use merchantRefId + formStatus + submitTime as an additional business-side deduplication key
• When the status is FAILED or EXPIRED, continue processing according to the query API result or your business rules