W-9 Implementation Guide

Do you already collect certified W-8 and W-9 forms?

All you need to do is upload them via https://docs.zerohash.com/reference/post_participants-documents with the appropriate document type and you're done. Make sure to do this for pre-existing customers and on an ongoing basis for new customers.

If the above doesn't apply to you, see the below instructions. If you're already onboarding US customers via zerohash APIs, you're 90% there.

Collect the W-9 fields in your UX

Collect these new data points in your customer journey:

Their TIN/SSN (9 digits, no dashes)
Their typed name as the signature
Their optional exemption codes:
- payee_exemption field that captures enum values for any applicable payee exemption codes 1 - 13 on the IRS form W-9
- fatca_reporting_exemption field that captures enum values for any applicable fatca exemption codes A - Mon the IRS form W-9
A checkbox confirming the W-9 attestations (user is not subject to backup withholding, no B-Notice on file)
- What is a B-Notice? A B-notice is an IRS letter telling a payer (like zerohash) that a customer's name and taxpayer ID don't match IRS records. This triggers a requirement to collect a corrected W-9
- Platforms should show IRS attestation language to display alongside the checkbox to collect a proper attestation (see certification language in Section 2 of W-9 here)

If you are also onboarding NNPs (entities), you should also collect:

The entity DBA (doing-business-as) name, the public-facing trade name an entity operates under, when it's different from its legal registered name

Send the data to zerohash

Platforms can use the same endpoints they're already integrated with provide the required tax data:

If you are onboarding net new individual participants

Example POST /participants/customers/new request:

{
  "first_name": "John",
  "last_name": "Smith",
  "email": "[email protected]",
  "address_one": "123 Main St.",
  "address_two": "Suite 1000",
  "city": "Chicago",
  "zip": "12345",
  "jurisdiction_code": "US-IL",
  "phone_number": "15557778888",
  "date_of_birth": "1985-09-02",
  "id_number_type": "us_passport",
  "id_number": "123456789",
  "citizenship_code": "US",
  "country": "USA",
  "tax_id": "000-00-0000",
  "risk_rating": null,
  "signed_timestamp": 1603378501286,
  "kyc": "pass",
  "kyc_timestamp": 1603378501286,
  "onboarded_location": "US-FL",
  "sanction_screening": "pass",
  "sanction_screening_timestamp": 1603378501286,
  "idv": "pass",
  "employment_status": "full_time",
  "industry": "adult_entertainment",
  "source_of_funds": "salary",
  "signed_agreements": [
    {
      "type": "user_agreement",
      "region": "us",
      "signed_timestamp": 1603378501286
    }
  ],
  "b_notice_receipt": false,
  "w_form_certification": 1667504636159,
  "signature": "signature_data",
  "signature_timestamp": 1667504636159,
  "payee_exemption": "NONE",
  "fatca_reporting_exemption": "NONE",
  "is_not_subject_backup_withholding": true,
  "is_w_form_certified": true
}

If you are updating already-created individual participants

Example PATCH /participants/customers/{participant_code} request:

{ 
 "b_notice_receipt": false,
 "is_w_form_certified": true,
 "w_form_certification": 1667504636159,
 "signature": "signature_data",
 "signature_timestamp": 1667504636159,
 "payee_exemption": "NONE",
 "fatca_reporting_exemption": "NONE",
 "is_not_subject_backup_withholding": true,
,
}

Entity Participants

If you are onboarding net new entity participants

Example POST /participants-entity-new request:

{
  "platform_code": "PLAT01",
  "entity_name": "Entity Name",
  "legal_name": "Legal Name",
  "contact_number": "15557778888",
  "website": "company.com",
  "date_established": "1985-09-02",
  "entity_type": "llc",
  "address_one": "123 Main St.",
  "address_two": "Suite 1000",
  "city": "Chicago",
  "postal_code": "12345",
  "tax_id": "000-00-0000",
  "id_issuing_authority": null,
  "risk_rating": null,
  "sanction_screening": "pass",
  "sanction_screening_timestamp": 1603378501286,
  "self_certification_timestamp": 1667504636159,
  "signed_timestamp": 1603378501286,
  "signed_agreements": [
    {
      "type": "user_agreement",
      "region": "us",
      "signed_timestamp": 1603378501286
    }
  ],
  "submitter_email": "[email protected]",
  "submitter_first_name": "Jon",
  "submitter_last_name": "Doe",
  "submitter_title": "Mr.",
  "control_persons": [
    {
      "name": "John Smith",
      "email": "[email protected]",
      "address_one": "123 Main St.",
      "address_two": "Suite 1000",
      "city": "Chicago",
      "postal_code": "12345",
      "jurisdiction_code": "US-IL",
      "date_of_birth": "1985-09-02",
      "phone_number": "15557778888",
      "citizenship_code": "US",
      "tax_id": "000-00-0000",
      "id_number_type": "us_passport",
      "id_number": "123456789",
      "id_issuing_authority": null,
      "sanction_screening": "pass",
      "sanction_screening_timestamp": 1603378501286,
      "kyc": "pass",
      "kyc_timestamp": 1603378501286,
      "control_person": 1
    }
  ],
  "beneficial_owners": [
    {
      "name": "John Smith",
      "email": "[email protected]",
      "address_one": "123 Main St.",
      "address_two": "Suite 1000",
      "city": "Chicago",
      "postal_code": "12345",
      "jurisdiction_code": "US-IL",
      "date_of_birth": "1985-09-02",
      "phone_number": "15557778888",
      "citizenship_code": "US",
      "tax_id": "000-00-0000",
      "id_number_type": "us_passport",
      "id_number": "123456789",
      "id_issuing_authority": null,
      "sanction_screening": "pass",
      "sanction_screening_timestamp": 1603378501286,
      "kyc": "pass",
      "kyc_timestamp": 1603378501286,
      "beneficial_owner": 1,
      "role": ""
    }
  ],
  "incorporation_address": {
    "address_one": "string",
    "address_two": "string",
    "city": "string",
    "jurisdiction_code": "IT-25",
    "postal_code": "string"
  },
  "b_notice_receipt": false,
  "is_w_form_certified": true,
  "w_form_certification": 1667504636159,
  "signature": "signature_data",
  "signature_timestamp": 1667504636159,
  "payee_exemption": "NONE",
  "fatca_reporting_exemption": "NONE",
  "is_not_subject_backup_withholding": true,
  "dba_name": "ABC Trading Co",
  "other_entity_type": "Trust",
  "jurisdiction_code": "US-IL"
}

If you are updating already-created entity participants

Example PATCH /participants/entity/{participant_code} request:

{ 
 "b_notice_receipt": false,
 "is_w_form_certified": true,
 "w_form_certification": 1667504636159,
 "signature": "signature_data",
 "signature_timestamp": 1667504636159,
 "payee_exemption": "NONE",
 "fatca_reporting_exemption": "NONE",
 "is_not_subject_backup_withholding": true,
 "dba_name": "ABC Trading Co",
 "other_entity_type": "Trust",
}

Send account updates as you do today

If a user updates their tax info later, just PATCH the same endpoint with the new values. zerohash handles re-certification on our side.

What you need to know about W-9 Certification

Always pair certification with a timestamp

Whenever you send is_w_form_certified, send w_form_certification (the time the user attested) alongside it. Same for signature and signature_timestamp

Exemptions are rare

Most retail users don't have a payee_exemption or fatca_reporting_exemption. Leave them blank unless the user indicates otherwise

When anything changes, just send an update

In the event of a name change, address change, re-certification, or B-Notice resolution, PATCH the customer endpoint with the new values. zerohash handles re-validation

Please reference the US Tax Guidelines section here for more details on each of the new fields listed above and what they mean