Payee Identifier

merchantRefId is the payee identifier supplied by the merchant when calling Onerway Tax APIs. It represents the payee's unique ID in the merchant's own system, such as a customer ID, username, or account ID.

Where to provide it

When merchants call the Generate Form LinkTax API API, they pass merchantRefId in the request body. Onerway uses this field as the unique payee identifier in the Tax module.

Why it matters

merchantRefId is the key identifier across the full tax filing workflow:

1. Form collection: the hosted form link is bound to merchantRefId, so submitted W-9 or W-8 data is attached to the right payee record.
2. Status query: merchants can queryTax API form status and TIN verification results by merchantRefId.
3. Payment aggregation: beneficiary accounts in the Onerway payment module map back to the same payee record, allowing annual payment amounts to accumulate under one identifier.
4. 1099 filing: once annual volume reaches the threshold, Onerway aggregates payment data by merchantRefId to prepare the 1099-NEC filing workflow.

Key rules

• merchantRefId must be unique within the same merchant scope.
• One merchantRefId can correspond to multiple beneficiary accounts, such as different currencies or bank accounts.
• In the Tax module, one merchantRefId maps to only one payee record.

Historical Payee Migration

If a payee already received payments through Onerway before the Tax module was integrated, the merchant needs to provide a mapping file that links each merchantRefId to the corresponding beneficiary ID in the Onerway payment system.

Onerway imports this mapping so historical payment records can be associated with the correct tax record. This is a one-time setup task during initial integration. After the import is complete, later transactions continue to link automatically through merchantRefId.