Payout Rails

The platform values the Dots API accepts, which rails you can add over the API, and which can be set as a default.

A rail is the network a payout travels over — ACH, PayPal, a local bank transfer, and so on. Rails appear throughout the API as the platform field: on Create a Payout, on each item of a payout batch, and on every payout method returned for a user.

Which rails a user can use depends on their country. For availability, see Supported Countries and the Payout Coverage Map.

Choosing a platform value

Most integrations should send platform: "default" and let Dots route the payout to whatever method the user selected:

Create a payout on the user's default method

{
  "user_id": "fc54b468-bbb2-403f-be36-5627a8e3c7a4",
  "amount": 1000,
  "platform": "default"
}

default requires the user to have a default payout method. If they don’t have one, collect it first — a Flow with the manage-payouts step is the supported way to do this, because the API does not expose which rails are available to a particular user. See White-Labeled Payouts.

Name a specific rail only when your product needs to choose. If the user has more than one account on that rail, pass account_id to disambiguate.

Rail reference

Create Payout accepts paypal, venmo, ach, bank_transfer, cash_app, and default for platform. bank_transfer is the legacy API alias for the canonical intl_bank rail.

The canonical payout rails are:

Rail	Description	Addable over the API	Can be a default
`ach`	US bank account, via ACH or RTP where the account supports it.	✔️	✔️
`paypal`	PayPal account, identified by email.	✔️	✔️
`venmo`	Venmo account, identified by phone number or handle.	✔️	✔️
`cash_app`	Cash App account, identified by Cash Tag and account details.	✔️	✔️
`airtm`	Airtm account, identified by email.	✔️	✔️
`payoneer`	Payoneer account, identified by email.	✔️	✔️
`intl_bank`	Local bank or local wallet transfer outside the US.		✔️
`wire`	International wire transfer.		✔️
`crypto`	Stablecoin or crypto payout.		✔️
`push_to_card`	Push-to-card payout to an eligible debit card.		✔️
`rtp`	US real-time payments.

Addable over the API means Add a Payout Method accepts the rail. The remaining rails are added through a Flow, where Dots collects the rail-specific details and runs the checks each network requires.

Adding a payout method over the API

PUT /v2/users/{user_id}/payout-methods takes platform plus the fields that rail needs:

Rail	Required fields
`ach`	`routing_number`, `account_number`
`cash_app`	`routing_number`, `account_number`, `cash_tag`
`paypal`	`email`
`airtm`	`email`
`payoneer`	`email`, `routing_number`, `account_number`
`venmo`	`phone_number` or `handle`

Set is_default: true in the same request to make it the user’s default rail, which is what platform: "default" then resolves to.

Reading a user’s payout methods

GET /v2/users/{user_id}/payout-methods returns each saved method with its platform and rail-specific display and account fields. ACH methods include an id to pass as account_id, a mask, and rtp_enabled to indicate that the account can receive real-time payments. Other rails do not necessarily include id or mask; use the fields present for that rail.

Minimums and exclusions

Your App can carry a payout minimum. An amount below it is rejected with payout-minimum-unmet. Crypto payouts have their own floor and are rejected with the same code.

To stop offering a rail to your users, set payout_options_exclude_list on the App through Change App Settings. Excluded rails stop appearing in Flows for that App.

What’s next?

Supported Countries — rail availability by country.
White-Labeled Payouts — collecting a payout method and issuing a payout.
Error Codes — what to handle when a payout is rejected.