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

# Held Funds

> Check a held balance and release funds to the merchant's bank account.

## What held funds are

For most merchants, settled money sweeps to their bank account automatically. See [Payouts](/guides/payouts).

Merchants on a **held funds** setup work differently. Their settled money stays at the processor until it is released. The Held Funds endpoints let you see what's available and send it to the bank account on file, either as a dollar amount or as a specific set of payments.

<Note>
  These endpoints only work for merchants on a held funds setup. For anyone else they return `422 This merchant's funds are not held; they settle automatically.` rather than a misleading zero. They're also **affiliate keys only**: releasing held money is the affiliate's call, so merchant tokens can't use them. The key needs `funds:read` to check balances and `funds:release` to release. See [Authentication](/guides/authentication#affiliate-key-scopes).
</Note>

## Step 1: Check the balance

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

```json theme={null}
{
  "data": {
    "sid": "91828382",
    "available": 6492.87,
    "pending": 0,
    "reserve": 0,
    "at_risk": 1250,
    "owed_to_split": 40.15,
    "unresolved": 0,
    "release_fee": 30,
    "releasable": 5172.72,
    "ach_settlement_days": 7,
    "ach_out_enabled": true,
    "ach_out_limit_remaining": 19999999.99
  }
}
```

**`releasable` is the number that matters.** It's what can actually be released right now, and it's what every release is checked against. It starts from `available` and subtracts:

| Field | What it is | How it clears |
| - | - | - |
| `at_risk` | ACH payments that have funded but can still be returned by the customer's bank | Waiting. `ach_settlement_days` says how long |
| `owed_to_split` | A share already promised to another account and not yet moved | Overnight, on its own |
| `unresolved` | Releases already requested but not yet confirmed | Once each release is confirmed |
| `release_fee` | What the release itself costs | Charged on each release |

`releasable` is never below zero and never above `ach_out_limit_remaining`.

## Step 2 (optional): List releasable payments

If you want to release specific payments rather than a dollar amount, get the list of what qualifies:

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

A payment appears here once the processor reports it funded (usually the next day), it's past the 7 day return window if it's ACH, it has had no refund, return, or chargeback, and it hasn't already been released. Each entry's `amount` is its net amount less any split owed on it.

The list is newest first and capped at 500. `truncated: true` means there are more than that.

<Note>
  A payment appearing in this list doesn't guarantee it can be released on its own. Every release is still capped by `releasable` from the balance endpoint.
</Note>

## Step 3: Release

Name what to release in **one** of two ways:

* `amount`: a dollar figure, when you keep your own record of what has cleared
* `transaction_info_ids`: up to 100 payments from the list in Step 2

```bash theme={null}
curl --request POST \
  --url https://app.dimepayments.com/api/funds/release \
  --header 'Authorization: Bearer your-api-token' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": {
      "sid": "91828382",
      "amount": 1500.00,
      "idempotency_key": "payout-2026-09-25-0001"
    }
  }'
```

**Releasing by payments is all or nothing.** If any one payment doesn't qualify, nothing is released, and `data.ineligible` lists which ones and why. Each payment can only ever be released once.

The amount, whether given or totaled, is checked against a freshly calculated `releasable`, not a number you read earlier. It's never reduced to fit. If it's too much, you get a `422` with the current `releasable` so you can try again.

## Idempotency keys

Always send a fresh `idempotency_key` for each release you intend to make, and **reuse the same key when retrying** that release.

This matters because a release that times out on your end may still have gone through. Retrying with the same key returns the original release instead of sending the money twice, with `replayed: true`. Reusing a key with a different amount or different payments is refused with `409`.

## Reading the result

Check `release.status`, not just the HTTP code:

| `status` | HTTP | Meaning |
| - | - | - |
| `released` | `201` | Sent |
| `failed` | `422` | Declined, nothing moved. `failure_reason` says why |
| `unknown` | `202` | No confirmation came back, and it may have gone through |

An `unknown` release is held back from `releasable` until it's reconciled. That means retrying with a **new** key can't send the same money twice, and retrying with the **same** key returns the same `unknown` record. Check the balance again later to see how it resolved.

Only one release per merchant is processed at a time. A second request while one is in progress gets `409 Another release for this merchant is in progress.` Wait a moment and retry.

## Errors

| Status | Message | What to do |
| - | - | - |
| `409` | Idempotency key already used for a different release | Use a new key for a new release |
| `409` | Another release for this merchant is in progress | Retry shortly |
| `422` | `This merchant's funds are not held; they settle automatically.` | This merchant doesn't use held funds |
| `422` | `One of those transactions cannot be released. Nothing was released.` | Check `data.ineligible`, remove those payments, and retry |
| `422` | `That is more than is releasable.` | Use the `releasable` figure returned |
| `503` | `The processor could not be reached.` | Nothing was released. Retry shortly |

## Next steps

* [Payouts](/guides/payouts): how automatic deposits work for everyone else
* [API Reference](/api-reference): full request and response fields


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