Skip to main content

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.
Reading needs 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

  1. Customers pay the merchant as usual.
  2. Each night the processor sweeps that day’s settled payments, net of fees, into the Dime account.
  3. The morning after, that sweep is credited to the merchant’s program balance.
  4. The merchant creates a payout to one of its vendors, which comes off the balance immediately.
  5. Dime staff approve the day’s payouts and send them to the bank.
  6. The vendor’s bank credits the account — or returns it, which puts the money back.
A payout comes off your balance the moment you create it, days before the money actually leaves. That is deliberate: two payouts made at the same time cannot both spend the same dollars. Cancelling a payout that has not gone yet 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

The whole vendor comes back, with the new account on it as pending_prenote (the other vendor fields are unchanged and trimmed here):
A new or changed account cannot be paid for about three banking days. We send a $0 verification entry to the bank first and wait for it to clear. That wait is the point: it is what stops a compromised key from quietly redirecting a vendor’s money. Changing an account always restarts it.
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 unique Idempotency-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: true header. 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.
Read the Idempotent-Replayed header, not data.replayed, to tell a retry from a fresh payout. A replayed create returns the original 201 verbatim, and that body says "replayed": false, because that is what the first answer said. Without the header there is no replay protection at all: a timed-out retry makes a second payout.

Step 5: Cancel, while you still can

Cancelling is only possible while the payout is 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.
The two lists date things differently, and will not tie out across a month boundary. list dates a payout when it was asked for, so a later return never moves it out of a month you have already reconciled. The ledger dates each line when it happened. So a payout made on 30 November and cancelled on 2 December is a November payout with a December credit.

Paging

Both lists page 500 rows at a time. When meta.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 to Vendor 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 readable data.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.
See Response Codes for the full table.

Next steps