Personal tax

Guides

Personal tax

Tax information collection and IRS reporting

Vivamo handles IRS tax reporting for your customers. When a payout or a recorded prize becomes reportable, Vivamo collects the tax information it needs directly from the customer and files the appropriate form.

Personal tax is configured per operator. Which form applies, and what makes a payout or prize reportable, is set up with Vivamo during onboarding to match current IRS rules. If your operator has no personal tax type configured, none of this applies and disbursements proceed without tax checks.

You don't need to build anything for tax collection. Vivamo captures the identity document, the customer's legal name and address, and the W-9 itself through the SDK. Webhooks are sent for your own records and reconciliation, not because any action is required from you.

Tax types

Tax type	IRS form	Use case
`1099`	1099-MISC	Standard payouts (sweepstakes, other income, etc.)
`bingo`	W-2G	Bingo hall operations
`horse_racing`	W-2G	Horse racing / pari-mutuel wagering

For 1099 operators, reporting is triggered by a customer's disbursement total over the tax year. For bingo and horse_racing, it's triggered by recording a qualifying prize. Thresholds follow IRS rules and are applied by Vivamo, so you don't need to track them yourself.

What Vivamo collects

When a customer first becomes reportable, Vivamo needs three things from them: a verified identity document, their legal name and mailing address, and a completed W-9. The SDK gathers whatever is still outstanding before letting the payout continue, pre-filling anything already on record.

The disbursement stays blocked until all of it is in. Once a customer has completed the W-9 for your operator, later payouts proceed normally without prompting again.

Identity verification comes first

A W-9 has to be backed by a verified identity document, so the customer completes identity verification before the W-9 form is offered. This applies regardless of your KYC settings, including when KYC is switched off or scoped to payments only, because the requirement comes from the tax filing rather than your KYC configuration. See KYC verification.

When tax details are missing

Reporting a customer to the IRS requires their legal name and mailing address. If those aren't on file when a W-9 is triggered, the SDK collects them before moving on to the W-9. No handling is needed on your side.

You can skip this step by supplying the customer's name and address up front, either when you create the customer or by updating the customer before the payout.

Webhooks

Two events cover tax collection, and both are informational:

Event	When it fires
`customer_w9_required`	The first time a customer needs a W-9 for your operator.
`customer_w9_completed`	The customer's W-9 has been completed.

customer_w9_required fires once per customer per operator. Later payouts that still need the W-9 don't re-send it.

See Webhooks for payloads, authentication and retry behaviour.

Prizes (W-2G)

Operators with the bingo or horse_racing tax type record qualifying winnings through the API. This is the one part of personal tax that needs work on your side, since only you know when a prize has been won.

Vivamo validates each prize against the IRS thresholds for your tax type and stores the record for W-2G filing. Prizes that don't qualify are rejected with a 400 and a message explaining why. Operators on the 1099 tax type do not file W-2G forms and should not record prizes.

Recording a prize also triggers W-9 collection for that customer if they haven't completed one. The response includes a w9CaptureUrl when that's the case, and omits it otherwise.

Recording a prize

Bingo example

const response = await fetch(
  "https://api.vivamo.co/v1/customers/user_123/prizes",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer your_secret_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      reportableWinnings: 1500.0,
      dateWon: "2026-02-15",
      typeOfWager: "bingo",
      ticketOrCardNumber: "TICKET-001",
    }),
  }
);

Horse racing example

const response = await fetch(
  "https://api.vivamo.co/v1/customers/user_123/prizes",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer your_secret_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      reportableWinnings: 5000.0,
      dateWon: "2026-02-15",
      typeOfWager: "horse_racing",
      race: "Kentucky Derby",
      wagerAmount: 10,
    }),
  }
);

Required fields by tax type

Bingo

Field	IRS Box	Description
`reportableWinnings`	Box 1	Amount won
`dateWon`	Box 2	ISO 8601 date
`typeOfWager`	Box 3	Must be `bingo`
`ticketOrCardNumber`	Box 5	Ticket or card number

Horse racing

Field	IRS Box	Description
`reportableWinnings`	Box 1	Amount won
`dateWon`	Box 2	ISO 8601 date
`typeOfWager`	Box 3	Type of wager
`race`	Box 6	Race name
`wagerAmount`	--	The wager placed. Used to validate the payout ratio.

Optional fields (both types)

Field	IRS Box	Description
`federalIncomeTaxWithheld`	Box 4	Defaults to `0`
`winningsFromIdenticalWagers`	Box 7	Winnings from identical wagers
`payerInitials`	Box 8	First person to initiate the payout
`payerLocation`	Box 10	Window or location of the payout
`cashierOrWindow`	--	Cashier or window identifier

Identification fields (IRS Boxes 11 and 12) are populated automatically from the customer's identity verification and W-9 data. These are stored for filing but not returned in API responses.

Retrieving prize records

Use the Get Customer Prizes endpoint to list a customer's prize records. Results default to the current tax year, sorted by date won (most recent first).

// Current year
const response = await fetch(
  "https://api.vivamo.co/v1/customers/user_123/prizes",
  {
    headers: { Authorization: "Bearer your_secret_key" },
  }
);

// Specific year
const response2025 = await fetch(
  "https://api.vivamo.co/v1/customers/user_123/prizes?taxYear=2025",
  {
    headers: { Authorization: "Bearer your_secret_key" },
  }
);

Prize record statuses

Status	Description
`recorded`	Prize recorded, awaiting tax filing.
`submitted`	W-2G form submitted to the tax filing service.
`filed`	W-2G form filed with the IRS.

Error cases

Prize recording returns a 400 with an explanatory message in these cases:

Scenario
The operator's tax type is `1099`, which doesn't file W-2G forms
Personal tax is not enabled for the operator
The winnings don't meet the IRS threshold for the tax type
The winnings don't meet the required payout ratio (horse racing)
A required field for the tax type is missing, such as `ticketOrCardNumber` (bingo) or `race` (horse racing)
The customer could not be found

Disbursements Vivamo SDK