flintDocs

Payouts

A payment you collect lands in your pending balance. After the settlement delay it becomes available, and a payout moves available funds to your bank. Payouts run automatically on your payout schedule, or you can switch to manual and send them yourself. Each payout carries an arrival_at, the date the deposit is expected at your bank.

To match a deposit to the payments inside it, see Reconciliation.

All payout endpoints take a secret API key. Reads need money_movement.payouts.read or money_movement.payout_settings.read, and changes need the matching .write scope.

When funds become available#

Read your balance to see what is waiting and what can be paid out now:

cURL
curl "https://api.withflintpay.com/v1/balances" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Flint-Version: 2026-09-07"
  • pending_money is collected but not yet payable.
  • available_money can be paid out.
  • held_money is set aside and not payable, such as funds held for a payout in progress.
  • payouts_enabled is false until your account can receive payouts. Payments can succeed before then. The funds wait in your balance until the payout requirements clear, which Going live shows you how to check.

How long funds stay pending is delay_days on your payout settings. balance.updated fires when either amount changes, and balance_transaction.updated fires when a pending transaction becomes available.

Payout schedule#

Your schedule lives on payout settings:

cURL
curl "https://api.withflintpay.com/v1/payout-settings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Flint-Version: 2026-09-07"

interval decides when Flint sends available funds:

  • daily: once a day.
  • weekly: on the weekdays in weekly_payout_days, monday through friday.
  • monthly: on the days of the month in monthly_payout_days, 1 through 31.
  • manual: never on its own. You create each payout.

Change the schedule with PATCH. Send only the fields you are changing:

cURL
curl -X PATCH "https://api.withflintpay.com/v1/payout-settings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Flint-Version: 2026-09-07" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-schedule-weekly-2026-09" \
  -d '{
    "interval": "weekly",
    "weekly_payout_days": ["monday", "thursday"]
  }'

weekly_payout_days is required with weekly and rejected with any other interval. monthly_payout_days works the same way for monthly.

The other settings you can change:

  • delay_days_override: how many days, 0 through 31, a payment stays pending before it becomes available. It changes when funds become payable, not when payouts are sent. Send null to go back to the default. If your account's delay can't be changed, the request fails with PAYOUT_DELAY_PROVIDER_CONTROLLED.
  • minimum_balance_by_currency: an amount per currency to keep in your balance instead of paying it out, such as {"USD": {"amount": 50000, "currency": "USD"}}. Set one currency to null to remove its minimum.
  • statement_descriptor: the text on your bank statement, 22 characters or fewer.

status tells you whether payouts can run: enabled, disabled, blocked, or pending. When it is not enabled, blocked_reasons says why and next_actions says what to do.

A change usually applies right away. If the response is 200 with a PAYOUT_SETTINGS_RECONCILING entry in meta.warnings, the change is still being applied. Read the settings again, or wait for payout_settings.updated, before relying on it.

Bank destinations#

A payout destination is the bank account (or debit card) a payout goes to. Each currency has one default destination, marked default_for_currency: true. Scheduled payouts go to it, and so do manual payouts that don't name a destination.

Destinations are added and changed through embedded components, not a create endpoint:

  • The first bank account is collected during onboarding in the account_onboarding component.
  • Later additions, removals, and default changes use the payouts component.

Both run from a merchant account session. Sending default_payout_destinations to PATCH /v1/payout-settings returns DEFAULT_PAYOUT_DESTINATIONS_MANAGED_EXTERNALLY.

List destinations to see where money will go:

cURL
curl "https://api.withflintpay.com/v1/payout-settings/destinations?currency=USD" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Flint-Version: 2026-09-07"

Each destination shows bank_name, last4, currency, and a status:

status on payout destination
Final values do not change again
  • pending
    Added and not yet usable.
  • active
    Ready to receive payouts.
  • verification_required
    The bank account needs verification before payouts can use it. Complete it in the payouts component.
  • disabled
    Can't receive payouts. disabled_reason says why.
  • failed
    The bank rejected a payout to this account. Add a new account or correct this one.
  • deletedFinal
    Removed. Hidden from lists unless you pass include_deleted=true.

Through the API you can update a destination's metadata with PATCH /v1/payout-settings/destinations/{payout_destination_id} and remove one with DELETE. You can't delete the active default: make another account the default in the payouts component first, or the request fails with DEFAULT_PAYOUT_DESTINATION_REPLACEMENT_REQUIRED.

Manual payouts#

To choose when money leaves your balance, set interval to manual and create payouts yourself. A payout can't be created while an automatic schedule is on. That request fails with STANDARD_PAYOUT_REQUIRES_MANUAL_SCHEDULE, so each account is paid either on a schedule or manually, never both.

cURL
curl -X POST "https://api.withflintpay.com/v1/payouts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Flint-Version: 2026-09-07" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-2026-09-22" \
  -d '{
    "amount_money": {"amount": 250000, "currency": "USD"},
    "description": "September week 3",
    "external_reference_id": "treasury-2026-09-22"
  }'

The response is 201 with the payout in pending.

The amount can be anything above zero, up to your available balance minus funds already held for other payouts. Creating the payout holds the amount, so it stops counting as available. Over the limit, the request fails with INSUFFICIENT_AVAILABLE_BALANCE.

Omit payout_destination_id to pay the currency's default destination. A destination you name must be active and in the payout's currency. If your available funds come from more than one source, such as card and bank payments, set balance_source_type to choose which one to pay out. available_by_source_type on the balance shows the split. method is always standard.

Send an Idempotency-Key so that a retry after a timeout returns the same payout instead of creating a second one. See Idempotency.

Your account must be able to receive payouts. If it can't, the request fails with a 409 that names the reason, listed under Errors. GET /v1/capabilities shows the same readiness before you try.

Canceling a payout#

Cancel a manual payout while it is still pending:

cURL
curl -X POST "https://api.withflintpay.com/v1/payouts/po_01JABCDEFGHJKMNPQRSTVWXYZ0/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Flint-Version: 2026-09-07" \
  -H "Content-Type: application/json" \
  -d '{}'

The payout moves to canceled, the held amount goes back to your available balance, and payout.canceled fires.

Once a payout is in_transit, it can't be canceled and the request returns PAYOUT_NOT_CANCELABLE. Payouts sent by your schedule (initiated_by: "scheduled") can't be canceled either and return AUTOMATIC_PAYOUT_NOT_CANCELABLE. To stop future ones, switch interval to manual.

Tracking a payout#

List recent payouts, or narrow the list by status, destination, or arrival date:

cURL
curl "https://api.withflintpay.com/v1/payouts?status=failed&arrival_after=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Flint-Version: 2026-09-07"
status on payout
Final values do not change again
  • pending
    Created and waiting to be sent. Only a manual payout in this status can be canceled.
  • in_transit
    Sent to your bank. arrival_at is the expected deposit date.
  • paid
    The bank accepted the deposit.
  • failedFinal
    The deposit didn't land. The funds are back in your available balance.
  • canceledFinal
    Canceled before it was sent. The funds are back in your available balance.
Warning:

A paid payout can still move to failed if the bank returns the deposit afterward. Keep handling payout.failed for payouts you already marked as received.

initiated_by tells you where a payout came from: scheduled for your payout schedule, manual for one you created, and platform for one Flint created on your behalf. trace_id holds the bank's trace number once it is available. Give it to your bank to locate a deposit that is late.

When a payout fails#

A failed payout has a failure_code and a failure_message you can show to the person fixing it. The amount returns to your available balance as a payout_failure balance transaction, and nothing is lost.

Most failures are about the bank account:

  • account_closed, no_account, invalid_account_number: the account doesn't exist or can't take deposits.
  • account_frozen, bank_account_restricted, bank_ownership_changed: the bank is blocking deposits to the account.
  • incorrect_account_holder_name, incorrect_account_holder_address, incorrect_account_holder_tax_id: the account details don't match the bank's records.
  • declined, debit_not_authorized, insufficient_funds, invalid_currency, unsupported_card, could_not_process: the bank or card network refused the transfer.
  • payout_failed: any other failure.

To recover:

  1. Check the destination with GET /v1/payout-settings/destinations/{payout_destination_id}. A failed, disabled, or verification_required status means it needs attention.
  2. Correct or replace the bank account in the payouts component.
  3. On a schedule, the next payout includes the returned funds. On manual, create a new payout.

When a paid payout is reversed#

A paid payout can be reversed after the bank accepts it. Once the reversal completes, its status stays paid and reversal_status becomes reversed. Flint then sends payout.reversed and records a payout_reversal balance transaction that returns the amount to your available balance.

When payout.reversed arrives, fetch the payout and check reversal_status. Match the bank debit to the original deposit, and use the payout_reversal balance transaction to account for the returned funds. If you use manual payouts, you can create another payout after the funds are available.

What's in a payout#

A payout's entries list the balance transactions it paid out:

cURL
curl "https://api.withflintpay.com/v1/payouts/po_01JABCDEFGHJKMNPQRSTVWXYZ0/entries?page_size=100" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Flint-Version: 2026-09-07"

Each entry has a type (payment, refund, dispute, adjustment, and so on), a signed amount_money, occurred_at, and the balance_transaction_id to look up for detail. Entries come oldest first. Refunds and disputes are negative, and the entries always add up to the payout's amount_money.

Entries are available once a payout is paid. Before that the list is empty. A 503 PAYOUT_ENTRIES_UNAVAILABLE on a paid payout means its entries are still being prepared, so retry after the Retry-After header. For matching entries to orders and bank lines, see Reconciliation. For the same data as a CSV, see Reports.

Payout events#

Subscribe to these to follow payouts without polling. Each carries the payout.

  1. What happens: Your schedule runs, or you create a payout
  2. Flint sends: payout.created
    A payout to the merchant's bank was created.
  3. What happens: The payout is sent to your bank
  4. Flint sends: payout.updated
    Status is in_transit.
  5. What happens: The bank responds
  6. Flint sends: payout.updated
    A payout changed state.
  7. Flint sends: payout.paidorpayout.failed
    Paid, or failed with the funds returned to your balance.

Every status change sends payout.updated. A move to paid, failed, or canceled also sends the specific event, so handle one or the other for each change, not both. When an event arrives, fetch the payout with GET /v1/payouts/{payout_id} and act on its current status. Events can arrive more than once or out of order. See Webhooks.

payout.reversed changes reversal_status while status remains paid. Handle it separately from payout.paid.

Changes to destinations and settings have their own events: payout_destination.created, payout_destination.updated, payout_destination.disabled, payout_destination.deleted, and payout_settings.updated. Payload details are in Webhook event payloads.

Errors#

On POST /v1/payouts:

On POST /v1/payouts/{payout_id}/cancel:

On PATCH /v1/payout-settings:

Next steps#

Was this helpful?