Guide

Integration Guide

Tax API provides merchants with payee tax information collection link generation, collection status retrieval, and asynchronous notifications. This guide helps you complete environment preparation, credential setup, webhook configuration, and integration testing.

Sandbox ReadyWebhook SupportedTax Info Collection

Environments

Environment	Base URL	Description
Sandbox	https://sandbox-api.onerway.com/tax	Recommended for integration testing, signature verification, and webhook testing
Production	https://api.onerway.com/tax	Used for live business traffic

Before You Start

• Provide your onboarding email address and outbound IP used in the test environment so Onerway can create a sandbox merchant account and configure the IP whitelist
• After receiving the onboarding email, log in to the merchant portal to obtain your merchant number, ApiKey, and webhook secret
• On first login, reset the initial password before reviewing and managing your integration settings
• Only whitelisted IP addresses can access the relevant APIs

Response Envelope

All APIs return a unified JSON response structure:

Field	Type	Description
respCode	string	Business response code. 20000 indicates success
respMsg	string	Response message. English is used by default
data	object / array / string / null	Business payload

Integration Credentials

After onboarding is completed, you will receive the following information:

Item	Description	Usage
Merchant No	Merchant identifier	Used to identify your merchant account
ApiKey	API access credential	Used for API request authentication
Webhook Secret	Webhook signing secret	Used to verify webhook signatures

Core Concept

merchantRefId

merchantRefId is the payee identifier passed by the merchant when calling Onerway Tax APIs. It represents the user ID in the merchant system and serves as the unique identifier of that payee within the Tax module. Subsequent status retrieval and webhook notifications are associated through this field.

• It must be unique within the same merchant scope
• It is recommended to use a stable user ID from the merchant system that does not change frequently

Integration Flow

1. Prepare Your Webhook URL

Before testing starts, make sure you have:

• A callback URL that can be reached by Onerway
• Signature verification logic implemented in your service
• Idempotent handling logic implemented in your service

Important

Please provide a stable public callback URL. If the callback address changes, contact the Onerway technical team to update the configuration in time.

2. Complete Integration Testing

The recommended sequence is:

1. Read Authentication and confirm the required request headers and invocation method
2. Read Webhook and complete callback verification and receiving logic
3. Read Enumerations and confirm the values used by tax information collection fields
4. Call Create Collection Link to create a tax information collection entry for the payee
5. Call Retrieve Form Details or receive the collection status result through webhook notifications

Business Flow

Collection Initiation

• The merchant calls the create collection link API and passes merchantRefId (the user ID in the merchant system)
• The platform returns a form entry link, or sends the link to the specified email address based on configuration
• After visiting the link, the payee selects a form based on their situation and submits the required tax information

Verification Processing

• After the form is submitted, the platform performs the corresponding verification and information validation flow based on the form type
• While verification is in progress, the form status is PENDING_VERIFICATION
• After verification is complete, the form status is updated to READY or FAILED

Status Retrieval

• The merchant can actively query the current collection status through the detail API
• The platform also pushes status changes through webhook notifications

Result Processing

• When the form status becomes READY, tax information collection and verification are complete, and downstream business processing can continue, such as allowing withdrawals
• When the form status becomes FAILED, guide the recipient to refill the form or handle it manually based on the result
• When the form status becomes EXPIRED, create a new collection link and start the process again

Related Documents

• Authentication
• Webhook
• Enumerations
• Create Collection Link
• Retrieve Form Details