Tax Information Collection Flow

Feature Introduction

Merchants use APIs to generate hosted tax form links for payees. Payees open the link, complete the appropriate W-9 or W-8 form based on their tax residency, and submit the form for validation.

Onerway currently supports 6 standard IRS forms: W-9, W-8BEN, W-8BEN-E, W-8ECI, W-8EXP, and W-8IMY.

Business Flow

Step Explanation

1. Generate form link: call the Link Generation APITax API with merchantRefId and taxType.
2. Direct payee: embed the returned link in a withdrawal flow, email, or any other delivery channel.
3. Payee completes form: the payee selects the form type, fills in the fields, signs electronically, and submits the form.
4. Validation processing: W-9 forms go through automatic TIN verification. W-8 forms briefly enter validation status and then complete.
5. Result page: the payee sees a success, verifying, or failed page and can resubmit when needed.
6. Webhook notification: Onerway sends a status change notificationTax API to the merchant.
7. Query status: the merchant calls the Query APITax API to fetch the latest status.

Link Rules

• Each (merchant, merchantRefId, taxType) combination maps to one hosted link.
• Repeated calls return the existing link and behave idempotently.
• Hosted links do not expire.

Two Link Modes

• Generic link: no formType is specified, so the payee chooses the form type.
• Specific form link: for example formType=W9, which sends the payee directly into that form.

Form Status and Page Display