> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dimepayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Vendor Payouts

> Register the vendors you pay, check your balance, and send money to them.

## What Vendor Payouts is

Most merchants take payments and the money sweeps to their own bank account. See [Payouts](https://docs.dimepayments.com/guides/payouts.md).

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.

> [!NOTE]
>
> 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](https://docs.dimepayments.com/guides/authentication.md#token-abilities).

## 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.

> [!WARNING]
>
> **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.

```bash theme={null}
curl --request POST \
  --url https://app.dimepayments.com/api/vendors/create \
  --header 'Authorization: Bearer your-api-token' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": {
      "sid": "91828382",
      "name": "Northside Physiotherapy LLC",
      "type": "business",
      "external_vendor_id": "V-000417",
      "email": "ap@northsidephysio.example",
      "addr1": "1400 Peachtree St NE",
      "city": "Atlanta",
      "state": "GA",
      "zip": "30309"
    }
  }'
```

```json theme={null}
{
  "data": {
    "vid": "01a1a76f-b897-731d-a1f0-248d48b8be3b",
    "external_vendor_id": "V-000417",
    "name": "Northside Physiotherapy LLC",
    "type": "business",
    "status": "active",
    "email": "ap@northsidephysio.example",
    "phone": null,
    "addr1": "1400 Peachtree St NE",
    "addr2": null,
    "city": "Atlanta",
    "state": "GA",
    "zip": "30309",
    "country": null,
    "bank_account": null,
    "created_at": "2026-11-05T15:41:02-05:00",
    "updated_at": "2026-11-05T15:41:02-05:00"
  }
}
```

`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

```bash theme={null}
curl --request POST \
  --url https://app.dimepayments.com/api/vendors/bank-account \
  --header 'Authorization: Bearer your-api-token' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": {
      "vid": "01a1a76f-b897-731d-a1f0-248d48b8be3b",
      "sid": "91828382",
      "account_holder_name": "Northside Physiotherapy LLC",
      "account_type": "checking",
      "routing_number": "061000104",
      "account_number": "1234566789"
    }
  }'
```

The whole vendor comes back, with the new account on it as `pending_prenote` (the other vendor fields are unchanged and trimmed here):

```json theme={null}
{
  "data": {
    "vid": "01a1a76f-b897-731d-a1f0-248d48b8be3b",
    "bank_account": {
      "status": "pending_prenote",
      "account_type": "checking",
      "account_last4": "6789",
      "nacha_name": "NORTHSIDE PHYSIOTHERAP",
      "verification_method": "prenote",
      "prenote_sent_at": null,
      "verified_at": null,
      "failed_return_code": null
    }
  }
}
```

> [!WARNING]
>
> **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.

| `status` | Means |
| - | - |
| `pending_prenote` | Added, verification not sent yet |
| `prenote_sent` | Verification is with the bank; still cannot be paid |
| `verified` | Can be paid |
| `failed` | The bank rejected it. `failed_return_code` says why. Add a corrected account |

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

```bash theme={null}
curl --request GET \
  --url https://app.dimepayments.com/api/vendor-payouts/balance \
  --header 'Authorization: Bearer your-api-token' \
  --header 'Content-Type: application/json' \
  --data '{ "data": { "sid": "91828382" } }'
```

```json theme={null}
{
  "data": {
    "sid": "91828382",
    "available": "4748.50",
    "pending": "251.50",
    "young_ach": "1200.00",
    "young_ach_estimated": false,
    "available_without_young_ach": "3548.50",
    "payout_fee": "1.50"
  }
}
```

| Field | What it is |
| - | - |
| `available` | What a new payout can be made against. **Not** what is in the account |
| `pending` | Already taken off `available` by payouts that have not gone yet, fees included |
| `young_ach` | Bank payments credited in the last 7 days, which can still be returned |
| `young_ach_estimated` | `true` when part of `young_ach` is an estimate |
| `available_without_young_ach` | `available` less the young money, if you would rather not spend it yet |
| `payout_fee` | What the next payout will cost, on top of its amount |

**`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

```bash theme={null}
curl --request POST \
  --url https://app.dimepayments.com/api/vendor-payouts/create \
  --header 'Authorization: Bearer your-api-token' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: payout-2026-11-05-0417' \
  --data '{
    "data": {
      "sid": "91828382",
      "vid": "01a1a76f-b897-731d-a1f0-248d48b8be3b",
      "amount": 250.00,
      "reference": "INV-2026-0417",
      "description": "DIME PAY"
    }
  }'
```

```json theme={null}
{
  "data": {
    "sid": "91828382",
    "replayed": false,
    "payout": {
      "payout_id": "01a1ad76-36dd-73de-b138-edfb5eb7a8eb",
      "status": "pending",
      "amount": "250.00",
      "fee": "1.50",
      "total": "251.50",
      "reference": "INV-2026-0417",
      "description": "DIME PAY",
      "vendor": {
        "vid": "01a1a76f-b897-731d-a1f0-248d48b8be3b",
        "external_vendor_id": "V-000417",
        "name": "Northside Physiotherapy LLC"
      },
      "bank_account": { "account_last4": "6789", "account_type": "checking" },
      "trace_number": null,
      "return_code": null,
      "returned_at": null,
      "canceled_at": null,
      "created_at": "2026-11-05T15:46:08-05:00",
      "updated_at": "2026-11-05T15:46:08-05:00"
    }
  }
}
```

`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.

> [!NOTE]
>
> `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.

> [!WARNING]
>
> **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

```bash theme={null}
curl --request POST \
  --url https://app.dimepayments.com/api/vendor-payouts/cancel \
  --header 'Authorization: Bearer your-api-token' \
  --header 'Content-Type: application/json' \
  --data '{ "data": { "sid": "91828382", "payout_id": "01a1ad76-36dd-73de-b138-edfb5eb7a8eb" } }'
```

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

| `status` | Means |
| - | - |
| `pending` | Made, still cancellable |
| `approved` | In the batch going out; no longer cancellable |
| `sent` | In a file the bank took |
| `returned` | The vendor's bank rejected it and the money came back |
| `canceled` | Stopped before anything was sent |

`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

| Endpoint | What it answers |
| - | - |
| `GET /api/vendor-payouts/show` | One payout, by `payout_id` |
| `GET /api/vendor-payouts/list` | Payouts, filtered by date, `status`, and vendor |
| `GET /api/vendor-payouts/ledger` | Every line behind `available`, as a statement |
| `GET /api/vendors/list` | Your vendors, searchable, filtered by `status` |

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.

> [!WARNING]
>
> **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](https://docs.dimepayments.com/guides/webhooks.md#vendor-payout-events).

## Errors

Every refusal that comes from the payout itself carries a readable `data.code`:

| `code` | Status | Means |
| - | - | - |
| `payouts_paused` | 403 | Payouts are not available for this account. Contact your Dime representative |
| `vendor_inactive` | 422 | The vendor is deactivated, so it cannot be paid |
| `vendor_not_verified` | 422 | The vendor's bank account has not cleared verification yet |
| `invalid_amount` | 422 | Not more than \$0.00, or more than two decimal places |
| `invalid_reference` | 422 | Longer than 80 characters |
| `invalid_description` | 422 | Not 1 to 10 letters, numbers and spaces |
| `limit_exceeded` | 422 | Over the per-payout or per-day limit on your program |
| `insufficient_balance` | 422 | `amount + fee` is more than `available` |
| `not_cancelable` | 422 | Already approved into a batch |
| `not_found` | 404 | No such payout, or not yours |
| `busy` | 409 | Another payout for this account is being made. Retry in a moment |

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.

> [!NOTE]
>
> 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](https://docs.dimepayments.com/guides/response-codes.md#vendor-payouts) for the full table.

## Next steps

* [Webhooks](https://docs.dimepayments.com/guides/webhooks.md#vendor-payouts) -- hear when a payout is made or cancelled
* [Authentication](https://docs.dimepayments.com/guides/authentication.md#token-abilities) -- the four abilities these endpoints need
* [API Reference](https://docs.dimepayments.com/api-reference) -- every field on every endpoint


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.