What Vendor Payouts is
Most merchants take payments and the money sweeps to their own bank account. See Payouts. A merchant in the Vendor Payouts program works differently. Its payments settle into a Dime bank account rather than its own, and it then tells us which of its vendors to pay out of the resulting balance. Dime staff approve each day’s payouts and send them to the bank. That suits an organisation that collects money on someone else’s behalf and passes most of it on — a clinic network paying its providers, a marketplace paying its sellers.These endpoints only work for merchants in the program. For anyone else they answer
403 Vendor Payouts is not enabled for this merchant. rather than a misleading empty list. The program is enabled per merchant by Dime, and a merchant is always boarded into it from the start — an existing merchant is never converted, because its earlier payments and chargebacks would land in the program.vendor:read and payout:read; changing a vendor needs vendor:write, and making or cancelling a payout needs payout:create. They are separate on purpose, so a reconciliation key can watch the book without being able to move money. See Authentication.
How the money moves
- Customers pay the merchant as usual.
- Each night the processor sweeps that day’s settled payments, net of fees, into the Dime account.
- The morning after, that sweep is credited to the merchant’s program balance.
- The merchant creates a payout to one of its vendors, which comes off the balance immediately.
- Dime staff approve the day’s payouts and send them to the bank.
- The vendor’s bank credits the account — or returns it, which puts the money back.
Step 1: Register a vendor
A vendor needs a name and a type.business and individual decide which kind of bank entry we send, so get it right.
external_vendor_id is your own identifier for the vendor, unique within your account. You can use it anywhere vid is accepted, so you never have to store ours.
bank_account is null until you add one, which is the next step — a vendor with no account cannot be paid.
Reusing an external_vendor_id that is already live answers 422 with code: duplicate_external_vendor_id.
Step 2: Add the vendor’s bank account
pending_prenote (the other vendor fields are unchanged and trimmed here):
The full account number is never returned by anything.
account_last4 identifies it, and nacha_name is the name the payment will actually carry, cut to the 22 characters the bank file allows — so you can see any truncation before the vendor does.
Step 3: Check the balance
available answers “what can I spend”, not “what is in the bank”. A payout comes off it the moment it is made, days before the money leaves, so available + pending is what is really still sitting there.
young_ach never blocks a payout. It is there so you can decide for yourself whether to pay out money that could still come back. available can go negative if a deposit is returned or a day nets negative; new payouts are refused until it recovers.
Step 4: Make a payout
amount is what the vendor receives. fee is charged on top of it, so a payout needs amount + fee available, and total is what actually came off the balance.
reference is yours, echoed back untouched — an appointment or invoice id. description is the ten characters the vendor sees on their own statement, and defaults to the text on your program.
create and cancel wrap the payout in data.payout, with data.sid and data.replayed beside it. show and list return the payout at data directly. So it is data.payout.status from a create and data.status from a read.Always send an Idempotency-Key
A payout moves money, so send a uniqueIdempotency-Key header for every payout you intend to make, and the same value again if a request times out and you retry it.
- A retry with the same key returns the original response, with an
Idempotent-Replayed: trueheader. Nothing is paid twice. - A different request under the same key is refused with a
422. - A retry while the first is still running gets a
409. Wait and try again.
Step 5: Cancel, while you still can
pending. Once staff approve it into the day’s batch it is on its way to the bank, and cancel answers 422 with code: not_cancelable. Cancelling twice is safe and gives nothing back a second time.
A cancellation returns the fee as well as the amount, because nothing was sent. A payout the bank returns keeps its fee — the work was done. Reverse whatever you booked in both cases, but for different totals.
Payout status
trace_number is filled when the payout goes to the bank. return_code and returned_at are filled only if it comes back.
bank_account on a payout describes the account as it stood when the payout was made. A vendor changing their details later never rewrites a payout already sent.
Reading the book back
The ledger is the statement behind the balance: signed amounts that sum to
available, each with a type (deposit, payout, payout_fee, payout_canceled, payout_return, adjustment and so on) and a payout_id where the line belongs to one.
Paging
Both lists page 500 rows at a time. Whenmeta.next_cursor is set there is more, and it goes on the URL as ?cursor=... while the body stays exactly as it was. These are GET requests that read data and filters from the body, so following links.next on its own will not work.
Dates on list and ledger are YYYY-MM-DD, and any other format is refused rather than quietly matching nothing.
Hearing about it by webhook
Subscribe toVendor Payout Created and Vendor Payout Canceled to hear when a payout is made or stopped. Each carries the payout in the same shape show returns, plus company_sid and type, so a delivery and a read reconcile field for field. See Vendor payout events.
Errors
Every refusal that comes from the payout itself carries a readabledata.code:
A vendor that is not yours, or does not exist, answers
404 No such Vendor either way — we will not confirm whether someone else’s id is real.
The
422 for a reused idempotency key and the 409 while a key is still in flight come from the replay layer in front of these endpoints, so they carry a message with no code.Next steps
- Webhooks — hear when a payout is made or cancelled
- Authentication — the four abilities these endpoints need
- API Reference — every field on every endpoint

