Reference · STRIPE-SETUP-GUIDE.md

Stripe setup guide for tellatribe

For the person who administers our Stripe accounts. Written October 19, 2026. About an hour of work across two Stripe accounts, plus a January filing step each year. Nothing here touches how any product bills its customers.

What tellatribe is, in two sentences

tellatribe pays people (affiliates and creators) a commission when someone they referred buys one of our products — HealthyApp first, then booked.coach and WhoHire. Stripe plays two separate roles: it tells us when revenue happens (a webhook on each product's existing Stripe account) and it sends the money out to affiliates (a brand-new, dedicated Stripe account that we top up).

Those two roles live on two different Stripe accounts. Please keep them separate.

 HealthyApp's Stripe account (exists today)           NEW "tellatribe" Stripe account
 ───────────────────────────────────────────          ──────────────────────────────────────
 Customers pay HealthyApp as they do now.             Holds a balance we fund each month.
 One webhook sends us "a sale happened".     ──►      Pays affiliates through Stripe Connect
 Nothing else changes.                                (Express accounts, "transfers" only).

Part 1 — The new tellatribe Stripe account (payouts)

1.1 Create the account

1. In the Stripe Dashboard, open the account switcher (top-left) → New account.
2. Business name: tellatribe. Country: United States. Use the same business entity and tax ID we use for Near Zero Labs / The Sales Boss (whichever entity will be the payer of record — Jonathan has decided tellatribe itself pays every creator, so this account issues the 1099s).
3. Complete the business profile, bank account and identity verification until the account can send payouts and accept payments. Receiving payments is needed on this account: brands (publishers) top up their balance by card or ACH through Stripe Checkout, and that money is what the payouts draw on (decision 73). Turn on ACH Direct Debit under Settings → Payment methods; it is the cheap rail for top-ups (0.8 %, capped at $5) next to cards (2.9 % + 30¢).

1.2 Turn on Connect

1. Left nav → Connect → Get started.
2. Platform profile: we are a platform that pays out to third parties (our affiliates). Choose Express accounts. Loss liability: platform. When asked what our connected accounts will do, pick receive transfers only — they never charge customers.
3. Branding (Connect → Settings → Branding): name tellatribe, icon and the brand colour #4D7CFF. Affiliates see this on the Stripe-hosted onboarding page.
4. Under Connect → Settings → Payouts, leave the default (Stripe manages payout schedules on the Express accounts); we release funds to each affiliate once a month and Stripe pays their bank from there.

1.3 Create the API key

1. Developers → API keys → Create restricted key. Name it affiliate-coach-platform.
2. Permissions (Write unless noted): Connect → Accounts (write), Account Links (write), Transfers (write), Payouts (write), Balance (read), Balance transactions (read), Webhook endpoints (read); Payments → Checkout Sessions (write), PaymentIntents (read), Customers (write), Charges (read). Everything else: none. (The payments permissions are for brand top-ups, Part 6.)
3. Copy the key once. Do not paste it into email, Slack or a Google Doc. See Part 3 for the hand-off. → This becomes STRIPE_SECRET_KEY on the tellatribe API project.

1.4 Create the Connect webhook

1. Developers → Webhooks → Add endpoint.
2. Endpoint URL: https://api.tellatribe.com/api/stripe/connect
3. Listen to: Events on Connected accounts (this is the important toggle — not "events on your account").
4. Select exactly these events:
   • account.updated
   • account.application.deauthorized
   • payout.failed
5. Save, then reveal the Signing secret (whsec_…) once. → This becomes STRIPE_CONNECT_WEBHOOK_SECRET.

1.5 Fund it

• Payouts are sent from this account's balance. Two ways money arrives:
  • Brand top-ups (the normal way from now on, Part 6): a brand pays into its tellatribe balance by card or ACH through a Checkout page in the admin; the payment settles into this account's balance and the platform credits the brand's balance ledger.
  • Manual (fallback): Balance → Add to balance by bank transfer, for the house brands while their top-up flow is not yet in use.
• The admin's Payout runs screen shows the exact amount each run needs and refuses to release if the balance is short.
• Expect the first top-up to be small (the test ledger today holds about $1,400 of demo commissions that will be voided before launch).

1.6 Note the account id

• Settings → Business → Account details shows the id (acct_…). We store it as the workspace's payout account. Send it with the keys.

1.7 Create the funding webhook (events on THIS account)

1. Developers → Webhooks → Add endpoint. Endpoint URL: https://api.tellatribe.com/api/stripe/funding
2. Listen to: Events on your account (not connected accounts — this is the opposite toggle from 1.4).
3. Select exactly: checkout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed, charge.refunded, charge.dispute.created.
4. Reveal the signing secret once → STRIPE_FUNDING_WEBHOOK_SECRET (API project only).

Part 2 — HealthyApp's existing Stripe account (revenue signal)

This is a read-only addition to the account that already bills HealthyApp's customers. It does not change any product, price, checkout or payout.

2.1 Create the platform webhook

1. Switch to the HealthyApp Stripe account.
2. Developers → Webhooks → Add endpoint.
3. Endpoint URL: https://api.tellatribe.com/api/stripe/platform/healthyapp
4. Listen to: Events on your account (this one is not a Connect endpoint).
5. Select exactly these five events:
   • checkout.session.completed
   • invoice.paid
   • charge.refunded
   • charge.dispute.created
   • charge.dispute.closed
6. Save, reveal the Signing secret once. → This becomes HEALTHYAPP_WEBHOOK_SECRET.

2.2 Note the account id

• The HealthyApp account's acct_… id, from Settings → Business → Account details. We record it as the product's revenue account so events from any other account are ignored.

2.3 Nothing else

• No new products, prices, customers or Connect settings on this account. HealthyApp's own engineering adds two metadata fields to its checkout session (ac_click_id, ac_ref) on a code branch; that is their change, not a dashboard change.

2.4 Later: booked.coach and WhoHire

• Repeat 2.1–2.2 on each product's own Stripe account when we switch them on. The URL changes only in the last segment: /api/stripe/platform/booked, /api/stripe/platform/whohire.

Part 3 — Handing the secrets over

Five secrets and two ids come out of this:

• Put the two whsec_ values and the restricted key in 1Password (Sales Boss vault), item name "tellatribe Stripe", and share the item with Jonathan. Account ids are not secret and can go in the same item's notes.
• Where they land: the two webhook secrets go only on the API Vercel project. The restricted key is read by all three apps (API for webhooks and the monthly run, portal for affiliate onboarding, admin for the balance check and Release). It is entered once as a Vercel team-level shared environment variable on the sales-boss team (Team Settings → Environment Variables → attach to the three tellatribe projects), so a later roll is one edit.
• Do not send keys by email, Slack message or Google Doc. If one is ever exposed, roll it in Stripe (Developers → API keys → ⋯ → Roll key) and tell us; nothing breaks until we swap it.

Part 4 — How we will verify (you don't need to do anything here)

1. We set the env vars on the API project and redeploy.
2. Stripe Dashboard → Webhooks → the HealthyApp endpoint → Send test event invoice.paid: our endpoint answers 200 and the event shows under Admin → Programs → HealthyApp → Integration as "ignored (test mode)". That proves the signature and routing.
3. A real test-mode checkout on HealthyApp with an affiliate link produces a commission row in the ledger.
4. In the admin, Payouts stops saying "payout account not configured" and shows the balance; an affiliate can complete Stripe Express onboarding from the portal's Earnings → Payout method.
5. Brand funding: in the admin, Campaigns → Add funds opens a Checkout page; a test-mode payment comes back through the funding webhook (1.7) and the brand's balance strip moves from "pending settlement" to funded. We'll run this once with a test card and once with the ACH test account.
6. Tax reporting: Connect → Tax reporting shows the payer profile and the 1099-NEC form type (Part 5); the first affiliate past the threshold appears in its list and in Admin → Reports → Paid by recipient · tax year with the same total.

Part 5 — Tax identity and 1099 reporting

tellatribe is the payer of record for every affiliate and creator (Jonathan's decision, Oct 14). Brands fund tellatribe; tellatribe pays people. So this account, not any product's account, files the information returns. Commissions, two-tier overrides and flat campaign fees are all nonemployee compensation, reported on Form 1099-NEC (not 1099-K — affiliates receive transfers from us, they never take card payments from customers). Gifted product in a campaign counts at fair market value.

5.1 Threshold

• For payments made in 2026, the 1099-NEC threshold is $2,000 per recipient per calendar year (up from $600; indexed for inflation after 2026). The platform stores this as a setting, not a constant.
• Everyone under the threshold still owes tax on the income; the portal gives every affiliate a calendar-year earnings statement regardless.

5.2 Turn on Stripe's 1099 reporting for Connect

1. Connect → Tax reporting (in the Dashboard of the new tellatribe account) → Get started.
2. Form type: 1099-NEC. Payer: the entity that owns this account (name, EIN, address as they should print on the forms).
3. Calculation method: payments (cash paid in the calendar year, by payout date — not commissions earned). Approved-but-unpaid balances on Dec 31 roll to the next year.
4. Delivery: e-delivery through the Express dashboard (free), paper mail only for recipients who do not consent.
5. Filing: IRS e-file + state e-file. Stripe forwards state copies through the Combined Federal/State program where it can and tells us which states need a direct filing.
6. Stripe's published fees: $2.99 per form e-filed with the IRS, $1.49 per form filed directly with a state, $2.99 per mailed form; e-delivery is free. (Figures from Stripe's Connect 1099 pricing page; confirm on the US page when you turn it on.)
7. Stripe does not file automatically — in January someone (you) reviews the generated forms and clicks File. We'll remind you; the filing window closes January 31.

What Stripe then does for us: collects W-9 (US) or W-8BEN / W-8BEN-E (non-US) during Express onboarding, runs IRS TIN matching, totals payouts per connected account, generates and e-files the forms, and delivers them to the recipient. The affiliate never emails us a tax form.

5.3 Our side (built Oct 19)

• No verified tax identity, no payout. A missing or failed TIN would otherwise require 24 % backup withholding, which we do not want to operate. The balance simply holds until Stripe reports the account's tax details as verified.
• Collection happens at Express onboarding, before the first payout — not when someone approaches $2,000.
• Non-US creators: Stripe collects the W-8 and no 1099 is filed. At launch, payouts are restricted to US accounts; we widen country by country.
• The admin's Reports → Paid by recipient · tax year lists cash paid per person by payout date, flags who is at the 1099-NEC threshold and who still lacks a verified TIN, exports as CSV, and is the number to reconcile against Stripe's Tax reporting totals before you click File.
• Every affiliate downloads an annual earnings statement per calendar year from Earnings → Payouts, threshold or not; it states it is not a tax form and says "consult your tax advisor".

Part 6 — How a brand (publisher) funds its balance

A brand never pays creators directly. It funds a balance on tellatribe; accepted deals reserve escrow from it; verified work is paid from it; the platform fee comes off it. Mechanics:

1. In the admin, Campaigns → Balance → Add funds opens a Stripe Checkout session on this payout account (mode payment, card or ACH Direct Debit, amount the brand chooses, minimum $100). The session's metadata carries the workspace and product (brand) ids.
2. Stripe sends checkout.session.completed to the funding webhook (1.7). ACH settles later: the credit is written on async_payment_succeeded, so an ACH top-up shows as pending in the admin for 3–5 business days, a card top-up is immediate.
3. The platform writes one funding entry to the brand's balance ledger, keyed by the Checkout session id so a redelivered event cannot fund twice.
4. Processing fees are the brand's (decision 73): Checkout shows the amount and the fee line; the ledger credits the amount the brand chose. Encourage ACH for anything over about $500.
5. Refunds of unspent balance are a manual admin action (Stripe refund on the original payment → charge.refunded → negative adjustment entry). Escrowed money is never refundable until the deal is cancelled.

For the house brands (HealthyApp, booked.coach, WhoHire) the same page works: the product's own card on file tops up its tellatribe balance, and the manual bank transfer in 1.5 becomes the exception.

Part 7 — Why Stripe Connect and not PayPal Payouts

The other common way affiliate software pays people is PayPal Payouts (the API formerly called Mass Pay). We looked at it for the same job. Summary of how it works and why we are not starting there:

Where PayPal is genuinely better: it is cheaper per payout at small amounts, recipients need nothing new, and a non-US creator with a PayPal account is trivially payable. Where it costs us: the whole tax-identity and 1099 layer in Part 5 becomes our code, and "pay to an email" means a typo pays a stranger.

Decision recorded (DECISIONS-FOR-REVIEW #63): Stripe Connect is the launch rail; PayPal Payouts is a second rail for later, most useful for international creators and sub-threshold casual affiliates, and only once our own W-9/W-8 collection exists. The ledger's payout-method field is already an enum so adding paypal is additive. Nothing for you to set up on PayPal today.

FAQ

Why a separate account for payouts? So affiliate money never mixes with any product's revenue, so each product can be charged exactly what it owes, and so the 1099s come from one payer. It also means a problem on one product's account can't freeze affiliate payouts.

Will affiliates have to create a Stripe account? They complete a short Stripe Express onboarding (identity, bank, tax form) from inside tellatribe. Stripe handles W-9/W-8 collection and 1099 filing for Express accounts.

Does this add fees? Stripe Connect Express with platform-managed pricing is $2 per active connected account per month plus 0.25% + $0.25 per payout; instant payouts cost 1% (the affiliate pays that if they choose it). Webhooks are free.

What if HealthyApp's checkout code isn't live yet? The webhook can be created now; events simply won't carry an affiliate reference until the branch ships, and our handler records them as unattributed. Nothing is lost or double-paid.

Who files the 1099s and when? tellatribe (this payer account) files 1099-NEC for every US recipient paid $2,000 or more in a calendar year. Stripe builds the forms; you review and file them in January (Part 5.2).

Why not just PayPal everyone? See Part 7. Short version: PayPal is cheaper per payment but leaves tax-form collection and 1099 filing to us and lets a mistyped email pay the wrong person. It may become a second option later.

Rendered from STRIPE-SETUP-GUIDE.md. Edit the source, not this page.