Payers

Ways to onboard a payee

Inviting a payee through Invite User is only one of four ways to onboard someone. You can also upload payouts in bulk by CSV, send a Payout Link, or create the payee through the API. Only direct API payouts require an already-verified payee; every other path starts onboarding for someone who has never used Dots.

Path

Where

What you need upfront

When the payee record is created

Invite User

Payees → Invite User

First name, last name, email, and phone number

At invitation

Bulk payouts via CSV

Send Payouts → Bulk

Recipient email, or phone number with country code, per row

When the recipient completes onboarding

Create Payout Link

Send Payouts → single payout, or the Payout Links page

An amount. Recipient details are optional

When the recipient claims the link

Create the user first, then pay out

API: POST /v2/users/

Email, country code, phone number, first and last name

At API call

Direct API payout

API: POST /v2/payouts/

An existing, verified connected user

Must already exist

For unknown recipients, the CSV and send-payout paths do not create a payee record when you send. They create a Payout Link with the details you supplied and deliver it. The payee record appears in Payees once the recipient completes onboarding and phone verification.

Bulk payouts by CSV

Send Payouts → Bulk opens the Bulk payouts via CSV flow. Download the template, fill one row per recipient, upload, review, and submit.

The template requires these headers:

  • first_name, last_name

  • email, country_code, phone_number: each row needs the email, or the country code and phone number together. The country code is the phone country code, digits only without +

  • delivery_method: email, sms, or link. If you leave it blank, Dots uses SMS when a phone number is present and email otherwise

  • amount_cents: a positive integer

  • memo

  • idempotency_key: a UUID

Two optional headers exist: metadata (a JSON object) and force_collect_compliance_information.

After you submit, the upload moves through created, submitted, processing, and completed. The results CSV adds success, payout_link_id, and error columns so you can see which rows went through. If a row's recipient has no Dots account yet, that row becomes a Payout Link delivered by the row's delivery method; the recipient onboards when they claim it.

A Payout Link is the only path that needs no recipient details at all: for a shareable link, the amount is the only required field. Create one from Send Payouts or the Payout Links page, then share it yourself or have Dots deliver it by email or SMS.

The recipient claims the link, enters their name, email, phone number, and country, verifies their phone, completes any required tax or compliance steps, and chooses a payout method. If the link was created with a specific phone number, the onboarding form pre-fills it and the link cannot be claimed with a different number.

See How to Claim a Payout Link for the recipient-side walkthrough.

API payouts

The API has three distinct payout behaviors, and mixing them up is the most common integration mistake:

  • POST /v2/users/ creates or reuses a payee and their app connection. It requires email, country_code, phone_number, first_name, and last_name. A new connection stays inactive until the payee is verified

  • POST /v2/payouts/ sends a direct payout and requires an existing, active connected user. An unknown user_id returns a not-found error, and an unverified user returns "User is unverified"

  • POST /v2/payouts/send-payout accepts either a user_id or an inline payee with country_code and phone_number (email optional). For an unknown payee, it creates and delivers a Payout Link instead of creating a user. If the email you supply conflicts with an existing user matched by phone, the request fails with "Email does not match the user associated with this phone number"

POST /v2/payout-links/ creates Payout Links and supports the same optional payee object.

Requiring onboarding steps on each path

The five checkboxes in Invite a payee and customize their onboarding apply to one invitation at a time. The other paths control steps differently:

  • CSV: the per-row force_collect_compliance_information column forces compliance collection for that recipient

  • API: payout and Payout Link requests accept an additional_steps parameter, with values such as compliance, id-verification, background-check, manage-payouts, and pdf-form-fill

  • App settings: tax settings apply to everyone. Require tax form collection forces tax collection on all payouts, Collect form W-8 BEN adds W-8BEN collection for non-US payees, and Default payouts to tax exempt skips tax collection unless it is otherwise required

There is no app-level default for the background check, document signature, or payout-setup steps; you set those per invitation or per API request.

Was this helpful?
Was this helpful?