Personal tax

Guides

Personal tax

Tax information collection, 1099 reporting, and W-2G prize filing

Vivamo handles IRS tax reporting for your customers. Depending on your operator's personal tax type, Vivamo will collect customer tax information and file either 1099s (for disbursements) or W-2Gs (for gambling winnings).

Tax types

Your operator is configured with one of three personal tax types:

Tax type	IRS form	W-9 trigger	Use case
`1099`	1099-MISC	Customer's year-to-date disbursements reach $2,000	Standard payouts (sweepstakes, other income, etc.)
`bingo`	W-2G	Customer's first qualifying prize is recorded	Bingo hall operations
`horse_racing`	W-2G	Customer's first qualifying prize is recorded	Horse racing / pari-mutuel wagering

If your operator has no personal tax type configured, none of this applies and disbursements proceed without tax checks.

1099 reporting

Operators with the 1099 tax type must collect necessary information from customers who receive $2,000 or more in disbursements during a calendar year. This information capture is triggered automatically when a disbursement flow is created.

How it works

When you create a disbursement intent, Vivamo checks the customer's year-to-date disbursement total (including the current request). If the total reaches $2,000:

The disbursement intent is created with a requires-tax-data status instead of the usual created status.
The response includes a w9CaptureUrl field with a link to a hosted tax information form.
The first time this happens for a given customer, Vivamo sends a customer.w9_required webhook to your registered URL.

The Vivamo SDK handles this step through the embedded widget.

Disbursement intent response with W-9 required

{
  "success": true,
  "disbursementIntentId": "65f1a2b3c4d5e6f7a8b9c0d1",
  "amount": {
    "initialAmount": "150.00",
    "totalAmount": "150.00",
    "stateTax": "0",
    "countyTax": "0",
    "cityTax": "0",
    "additionalTax": "0",
    "totalTax": "0"
  },
  "currency": "USD",
  "externalCustomerId": "user_123",
  "externalDisbursementIntentId": "payout_456",
  "clientSecretKey": "cs_di_abc123",
  "clientSecretKeyValidTill": "2026-02-15T16:30:00.000Z",
  "expirationTime": "2026-02-15T16:30:00.000Z",
  "w9CaptureUrl": "https://example.com/w9/capture/abc123"
}

When w9CaptureUrl is present, the customer must complete the tax information form before the disbursement can proceed. Once they submit, Vivamo marks the form as complete. Subsequent disbursement intents for that customer will return created status as normal.

Year-to-date calculation

The $2,000 threshold is calculated per calendar year (January 1 through December 31). Both successful and pending-approval disbursements count toward the total. If your operator is part of a connected operators group, disbursements across all connected operators are aggregated when checking the threshold.

Prizes (W-2G)

Operators with the bingo or horse_racing tax type can record qualifying gambling winnings. Vivamo validates each prize against IRS filing thresholds and stores the record for W-2G filing.

Filing thresholds

Tax type	Threshold
Bingo	$1,200 or more
Horse racing	Over $600 and at least 300x the wager amount

Prizes below these thresholds are rejected with a 400 error. Operators only required to file a 1099 should not record prizes.

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,
    }),
  }
);

Response

{
  "message": "Prize recorded successfully",
  "prizeRecord": {
    "personalTaxType": "bingo",
    "taxYear": 2026,
    "status": "recorded",
    "reportableWinnings": 1500,
    "dateWon": "2026-02-15T00:00:00.000Z",
    "typeOfWager": "bingo",
    "ticketOrCardNumber": "TICKET-001",
    "createdAt": "2026-02-15T14:30:00.000Z"
  },
  "w9CaptureUrl": "https://example.com/w9/capture/abc123"
}

If the customer has already completed their W-9, w9CaptureUrl is omitted.

Required fields by tax type

Bingo

Field	IRS Box	Required	Description
`reportableWinnings`	Box 1	Yes	Must be $1,200 or more
`dateWon`	Box 2	Yes	ISO 8601 date
`typeOfWager`	Box 3	Yes	Must be `bingo`
`ticketOrCardNumber`	Box 5	Yes	Ticket or card number

Horse racing

Field	IRS Box	Required	Description
`reportableWinnings`	Box 1	Yes	Must exceed $600 and be at least 300x `wagerAmount`
`dateWon`	Box 2	Yes	ISO 8601 date
`typeOfWager`	Box 3	Yes	Type of wager
`race`	Box 6	Yes	Race name
`wagerAmount`	--	Yes	Used for the 300x multiplier validation

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 KYC verification and W-9 data. These fields are stored for W-2G filing but are not included in API responses.

Retrieving prize records

Use the Get Customer Prizes endpoint to list a customer's prize records. Results default to the current calendar 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.

W-9 collection

Regardless of tax type, W-9 collection works the same way. When a customer first needs a W-9 (by crossing the $2,000 disbursement threshold or having a qualifying prize recorded), Vivamo returns a w9CaptureUrl in the API response.

You can present this URL to the customer in your application by embedding it in an iframe or redirecting them to it. Once the customer submits the W-9, Vivamo receives a callback and marks the form as complete. After that, the w9CaptureUrl field is no longer included in subsequent responses.

`customer.w9_required`webhook

The first time a customer triggers W-9 collection for your operator, Vivamo sends a webhook:

{
  "event": "customer.w9_required",
  "externalCustomerId": "user_123",
  "customerId": "65f1a2b3c4d5e6f7a8b9c0d1",
  "w9CaptureUrl": "https://example.com/w9/capture/abc123"
}

This webhook fires once per customer per operator. Subsequent requests that still require W-9 completion will return the w9CaptureUrl in the API response but will not re-send the webhook.

Error cases

Prize recording errors

Scenario	HTTP status	Error message
Operator tax type is `1099`	400	1099 operators do not file W-2G forms.
Personal tax not enabled	400	Personal tax is not enabled for this operator.
Bingo prize below $1,200	400	Bingo prizes must have reportable winnings of at least $1,200.
Missing `ticketOrCardNumber` for bingo	400	Bingo prizes require a ticketOrCardNumber (IRS Box 5).
Horse racing prize at or below $600	400	Horse racing prizes must have reportable winnings greater than $600.
Horse racing below 300x wager	400	Horse racing prizes must have reportable winnings of at least 300 times the wager amount.
Missing `race` for horse racing	400	Horse racing prizes require a race (IRS Box 6).
Customer not found	400	Customer not found.

Disbursements Vivamo SDK

Personal tax

Tax information collection, 1099 reporting, and W-2G prize filing

Tax types

1099 reporting

How it works

Disbursement intent response with W-9 required

Year-to-date calculation

Prizes (W-2G)

Filing thresholds

Recording a prize

Bingo example

Horse racing example

Response

Required fields by tax type

Bingo

Horse racing

Optional fields (both types)

Retrieving prize records

Prize record statuses

W-9 collection

customer.w9_requiredwebhook

Error cases

Prize recording errors

`customer.w9_required`webhook