Tax documentation collection applies only to person and institution Identities in the Paxos Trust Company (PTC) population. Business-member Identities do not need to submit tax documentation. Beginning January 1, 2027, in-scope Identities without approved tax documentation will be blocked from taxable transactions.
W_9for a person or institution that is a US personW_8BENfor a non-US personW_8BEN_Efor a non-US institution
Your organization retains the executed substitute form. Submit the structured form values and certification metadata only. The API does not accept a PDF, image, signing transcript, IP address, or other evidence artifact.
Before you begin
You need:- An OAuth client with the
identity:write_identityscope to submit a form and theidentity:read_identityscope to retrieve the current form - The ID of an Identity owned by your organization
- A complete, signed substitute W-9, W-8BEN, or W-8BEN-E
person_details or institution_details, and updating those Identity details does not modify the current tax documentation. Submit every value the customer certified, even when the same value is already present on the Identity. When information must change in both resources, update each resource separately.
Submit tax documentation
➊ Select the form
Setform_type and include exactly one matching object inside tax_documentation.
Paxos rejects a request when the discriminator, nested object, and Identity type do not agree.
➋ Build the complete request
The following examples include optional and conditional fields so you can review the full proposed shape. Only include treaty fields when the customer claims treaty benefits. Each address follows the sharedIdentityMailingAddress contract: all six fields allow up to 255 characters without a character-pattern restriction. country, address1, city, and province are required; address2 is optional; and zip_code is required for countries that use postal codes.
- W-9
- W-8BEN
- W-8BEN-E
➌ POST the form for the Identity
➍ Handle acceptance
Paxos returns200 OK after authenticating the request, authorizing access to the Identity, validating the complete form, and storing it as the Identity’s current tax documentation. The response contains the same representation returned by the GET endpoint:
Retrieve the current form
Use GET to retrieve the latest tax documentation accepted for the Identity, regardless of form type.200 OK with the same representation returned by POST. If the Identity does not have accepted tax documentation, Paxos returns 404 Not Found. The response does not expose downstream tax-provider processing status. The returned values reflect the latest accepted form and can differ from the Identity’s current person_details or institution_details.
Respond to tax-documentation requirements
Usestatus_details.requirements on Get Identity or List Identities to identify an outstanding TAX_DOCUMENTATION requirement. When awaiting_action_from is CLIENT, submit another complete form through the same endpoint; there is no separate remediation endpoint.
For lifecycle states, reason codes, and the corresponding partner action, see Respond to tax-documentation requirements.
Correct or replace a form
POST another complete request to the same endpoint. A later accepted request becomes the current tax document for the Identity:- The same
form_typecorrects the current form. - A different
form_typereplaces the current form. - A rejected request leaves the previously accepted form current.
person_details or institution_details does not replace its current tax documentation. Submit another complete form through this endpoint when the certified tax documentation must change.