Held Funds

What held funds are

For most merchants, settled money sweeps to their bank account automatically. See 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.

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.

Step 1: Check the balance

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" } }'

{
  "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:

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.

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.

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

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: how automatic deposits work for everyone else
API Reference: full request and response fields

Getting Started

SDKs

Payments

Going Live

Integrations

Reference

What held funds are

Step 1: Check the balance

Step 2 (optional): List releasable payments

Step 3: Release

Idempotency keys

Reading the result

Errors

Next steps

​What held funds are

​Step 1: Check the balance

​Step 2 (optional): List releasable payments

​Step 3: Release

​Idempotency keys

​Reading the result

​Errors

​Next steps

What held funds are

Step 1: Check the balance

Step 2 (optional): List releasable payments

Step 3: Release

Idempotency keys

Reading the result

Errors

Next steps