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_date, the calendar date (YYYY-MM-DD) 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. A platform's partner app token can make the reads for an installed merchant when its grant holds the read scope, but not the changes; see Read money and answer disputes.
Inbound payouts#
If refunds or disputes take your Flint balance below zero, Flint can withdraw funds from your bank to cover it. This is a payout with direction: "inbound" and initiated_by: "platform". The bank account being debited is payout_destination_id.
amount_money is always positive. net_money is positive for an inbound payout and negative for an outbound payout. Inbound payouts offer no supported actions and cannot be canceled through the API. They have no itemized contents: filtering balance transactions by their payout_id returns 409 ACTION_NOT_ALLOWED with reason not_itemized. Match the withdrawal to its inbound_payout balance transaction instead.
An inbound payout follows the same statuses and events as an outbound payout. A bank return can change it from succeeded to failed; its inbound_payout_failure row removes the money from your balance again.
When funds become available#
Read your balance to see what is waiting and what can be paid out now:
curl "https://api.withflintpay.com/v1/balances" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Flint-Version: 2026-09-07"
pending_moneyis collected but not yet payable.available_moneycan be paid out. Funds held for payouts you created are already left out.held_moneyis set aside for payouts you created that haven't been debited from your balance yet. It isn't payable. The amount leavesheld_moneywhen the payout'spayoutbalance transaction posts, which usually happens before the create request returns. If your processor rejects the payout, the amount goes back toavailable_money. If Flint can't tell whether the processor created it, such as after a timeout, the amount stays inheld_moneyuntil Flint finds out.reserve_moneyis held in reserve. It doesn't overlapavailable_moneyorheld_money.available_by_source_typeandpending_by_source_typesplit the available and pending amounts by balance source. Thecardbucket includes both card payments and ACH debits.bank_accountis a separate bucket that some accounts have; treat the keys as an open set. A payout draws from one source, soavailable_by_source_typealso limits how much one payout can send.observed_atis when Flint observed these amounts.payouts_enabledisfalseuntil 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.
delay_days on your payout settings is the normal settlement delay. A new account's first payments can stay pending longer than that, because your processor can hold them. To forecast when a payment's funds become available, read available_at on its balance transaction instead of counting delay_days. 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 "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 inweekly_payout_days,mondaythroughfriday.monthly: on the days of the month inmonthly_payout_days,1through31.manual: never on its own. You create each payout.
Change the schedule with PATCH. Send only the fields you are changing. Payout settings have a version that increases with each change, and a PATCH that sends weekly_payout_days, monthly_payout_days, or minimum_balance_currency_options must include the version you read as expected_version, because each of those fields replaces its whole list or map. Keep data.version from the GET response with your draft. With version 3 from the read above:
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 '{
"expected_version": 3,
"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.
Leaving out expected_version while sending one of those fields returns 400 INVALID_REQUEST with detail code REQUIRED and param: "expected_version", even for an empty list or a null that clears a value. Changing only interval, delay_days_override, or statement_descriptor doesn't need it, but accepts it. If the settings changed after your read, nothing changes and the request returns 409 VERSION_CONFLICT with the current version in details[0].current_version. Keep the schedule you were editing, read the settings again, compare them with your draft, and send the reconciled change with the new version and a new Idempotency-Key.
The other settings you can change:
delay_days_override: the normal settlement delay in days,0through31, in place of the default. A payment'savailable_atcan still be later, such as for a new account's first payments. It changes when funds become payable, not when payouts are sent. Sendnullto go back to the default. If your account's delay can't be changed, the request fails withACTION_NOT_ALLOWEDand reasonmanaged_externally.minimum_balance_currency_options: an amount per currency to keep in your balance instead of paying it out, such as{"USD": {"amount": 50000, "currency": "USD"}}. Set one currency tonullto 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, your payment processor may have applied only part of the change. The warning identifies the settings with resource_type: "payout_settings" and resource_id. About two minutes after the change started, the next read or change of your payout settings, or the next change to an affected destination, records what your processor holds. Until then, other changes return 409 OPERATION_IN_PROGRESS. After that, read the settings again and send any part that's still missing with a new Idempotency-Key.
If a change fails with a 5xx error, send it again unchanged with the same Idempotency-Key. Flint sends the same requests to your processor, so nothing applies twice, and returns the settings. If your processor refuses again, or another change already recorded the earlier one, the response is 200 with the payout_settings_reconciling warning.
If Flint places a review pause on your account, it holds your live payouts. Your live schedule is set to manual, so no scheduled payouts are sent, and GET /v1/payout-settings shows manual until the review ends. Changes to interval, weekly_payout_days, or monthly_payout_days fail with MERCHANT_NOT_READY with reason platform_review until Flint has put back the schedule you had. The next scheduled payout then includes the balance that built up. Test mode keeps its schedule during a review.
When payout receipt readiness reports platform_review or billing_suspended, GET /v1/payout-settings returns status: blocked and lists the same code in blocked_reasons. A payout creation request returns 409 MERCHANT_NOT_READY with the same reason in details[0].reason.
Scheduled payouts follow your payout schedule once payments settle. API-created payouts may be unavailable in the selected mode even when scheduled payouts are enabled. In that state, readiness.payouts and receive_payouts are ready, while create_standard_payouts is blocked with status_reason: processing_not_enabled and no next action. Payout settings remain enabled with empty blocked_reasons and next_actions, and balances with an active default destination have payouts_enabled: true. You can still change the schedule within your account's payout terms. This state is not an account review or suspension.
New accounts#
For its first 60 days in live mode, a new account is paid out weekly, on Mondays unless you change the day. During that time a schedule change must pay out at most once a week: weekly with one day in weekly_payout_days, or monthly with one day in monthly_payout_days. daily, manual, and a delay_days_override below the default delay_days fail with ACTION_NOT_ALLOWED and reason payout_frequency or payout_delay, and the error's details[0].payout_terms_expires_at says when the terms end. When the terms end, Flint switches an account that is still on weekly payouts to daily, and you can choose any schedule. Test accounts get the same weekly default schedule, but the 60-day restrictions and the switch to daily payouts apply only in live mode. Your processor's test timing can still differ from delay_days.
readiness.payouts.status is ready only when account readiness permits payouts and the payout currency has an active default destination. Each balance's payouts_enabled applies that rule to its own currency. An active destination alone does not enable payouts if the account is still pending or blocked.
Sandbox preparation creates a test bank account and confirms that it is active and the default for its currency. Preparation remains pending until those conditions hold; no manual bank verification is needed for the normal test bank.
Bank destinations#
A payout destination is the bank account (or debit card) a payout goes to. Each currency can have one default destination, marked is_default_for_currency: true. Scheduled payouts go to it, and so do manual payouts that don't name a destination.
Add a bank account#
The account owner enters bank details in an embedded component. Flint never takes account or routing numbers through the API:
- The first bank account is collected during onboarding in the
account_onboardingcomponent. - Later accounts are added, and existing ones fixed or removed, in the
payoutscomponent.
Both run from a merchant account session. To send the owner to add an account, create a session for the payouts component on your server with a merchant credential, then mount it in the browser:
curl -X POST https://api.withflintpay.com/v1/merchant-account-sessions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"components": ["payouts"]}'
The payouts component asks the owner to confirm their identity before a bank account changes. When they add one, it appears in the destination list and Flint sends payout_destination.created. Partner app tokens can't open the payouts component, change payout settings, or choose a default destination.
Choose the default#
Payout settings show the defaults in default_payout_destinations, a map from currency to payout_destination_id. The map is always present and is {} when there are no defaults. To change one, send the map with the settings' version as expected_version:
curl -X PATCH https://api.withflintpay.com/v1/payout-settings \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: make-checking-default" \
-H "Content-Type: application/json" \
-d '{"expected_version": 4, "default_payout_destinations": {"USD": "pdest_01JABCDEFGHJKMNPQRSTVWXYZ0"}}'
If a default bank account fails, payout settings say a replacement is required and offer a replace_default_payout_destination action. Choose another active destination in Dashboard under Balances → Payout methods, or send the update above.
Each listed destination becomes the default for its currency, and currencies you leave out keep theirs. The destination must be active and in that currency. A default can't be removed, only replaced, so a null map or value returns 400 INVALID_REQUEST. The response shows the new map, and both the new default and the destination that lost the default show their new is_default_for_currency and a higher version; naming the current default changes neither. Owners can also change the default in the payouts component. Changing a default through the API needs the manage_payout_destinations capability in readiness.capabilities on GET /v1/merchant, like the destination routes.
List destinations to see where money will go:
curl "https://api.withflintpay.com/v1/payout-destinations?currency=USD" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Flint-Version: 2026-09-07"
Narrow the list with type (bank_account or debit_card), status, is_default_for_currency=true, or available_payout_methods, which takes standard. Repeat a filter or send comma-separated values to match any of them. The singular available_payout_method is rejected with 400 INVALID_REQUEST and param: available_payout_method.
Each destination shows bank_name, last4, currency, and a status:
status on payout destinationstatus reports your processor's checks on the account. Payout bank accounts have no verification step for the owner to complete, such as micro-deposits, so a newly added account is usually active right away.
Read one destination with GET /v1/payout-destinations/{payout_destination_id}. Through the API you can update a destination's metadata with PATCH /v1/payout-destinations/{payout_destination_id} and remove one with DELETE /v1/payout-destinations/{payout_destination_id}:
curl -X DELETE "https://api.withflintpay.com/v1/payout-destinations/pdest_01JABCDEFGHJKMNPQRSTVWXYZ0" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Flint-Version: 2026-09-07" \
-H "Idempotency-Key: remove-old-checking-account"
DELETE takes no request body and always archives: it sets the destination's status to archived, returns the destination, and sends payout_destination.archived. It never disables a destination instead. If the deletion fails, the request returns the error and the destination's status doesn't change. payout_destination.disabled comes only from your processor disabling a destination.
You can't delete the active default: make another destination the default first, or the request fails with ACTION_NOT_ALLOWED and reason configuration_required.
Each destination has its own version, which increases when you change it and when the account's bank details change it, such as a new default or a disabled account. Both PATCH and DELETE accept the version you read as expected_version: in the PATCH body, or as ?expected_version= on DELETE. A stale value returns 409 VERSION_CONFLICT, and the destination stays as it is.
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 ACTION_NOT_ALLOWED and reason configuration_required, so each account is paid either on a schedule or manually, never both.
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.
Each payout draws from one balance source, such as card or bank_account. These are balance buckets, not payment methods: ACH debit funds are in card. The amount can be anything above zero, up to what one source has available in available_by_source_type, which already leaves out funds held for your other payouts. Creating the payout takes the amount out of available_money and that source, and debits your balance with a payout balance transaction.
Omit balance_source_type and Flint chooses the source: card when that bucket covers the amount, otherwise bank_account. Set it to pay out from one source on purpose. The payout's balance_source_type shows the source it draws from, and a retry with the same Idempotency-Key returns that same payout and source.
If no single source covers the amount, or the source you named doesn't, the request fails with LIMIT_EXCEEDED, and details[0].available_by_source_type lists what each source has available. To pay out more than one source holds, create one payout per source, each within that source's amount.
Omit payout_destination_id to pay the currency's default destination. A destination you name must be active and in the payout's currency. Payouts Flint sends, by API, Dashboard or schedule, always use method standard. Flint doesn't offer instant payouts. instant appears only on a payout Flint recorded from the processor that was sent outside Flint; other means a method Flint doesn't map.
Idempotency-Key is required, so that a retry after a timeout returns the same payout instead of creating a second one, however late it arrives. 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. readiness.payouts on GET /v1/merchant shows the same readiness before you try.
Canceling a payout#
Read supported_actions before canceling. It contains cancel while a manual payout is pending, and is [] when cancellation is unavailable. The list is independent of your credential; canceling still needs money_movement.payouts.write. In a webhook, the list reflects the payout when Flint recorded the change.
Cancel with POST /v1/payouts/{payout_id}/cancel:
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, a payout_cancellation balance transaction returns the amount to available_money, and payout.canceled fires.
Once a payout is in_transit, it can't be canceled and the request returns ACTION_NOT_ALLOWED with reason unsupported_state and the actual current_status and supported_actions. Payouts sent by your schedule (initiated_by: "scheduled") can't be canceled either and return ACTION_NOT_ALLOWED with reason not_offered. To stop future ones, switch interval to manual.
Tracking a payout#
GET /v1/payouts lists both directions. Filter with direction=outbound for deposits or direction=inbound for withdrawals. Repeat the filter or send comma-separated values to include either direction.
List recent payouts, or narrow the list by status, destination, or arrival date:
curl "https://api.withflintpay.com/v1/payouts?status=failed&arrival_date_from=2026-09-01&arrival_date_to=2026-10-01" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Flint-Version: 2026-09-07"
arrival_date_from and arrival_date_to accept strict YYYY-MM-DD dates in UTC. The lower date is inclusive and the upper date is exclusive: the example selects September arrivals, including every time on September 30 and excluding October 1. Equal dates select an empty window. Timestamps and timezone offsets are rejected. Use created_after and created_before to filter the payout's created_at instead.
Filter recorded payouts by method: standard, instant, or other. Send several to match any of them, such as method=standard,instant:
curl "https://api.withflintpay.com/v1/payouts?method=standard,instant" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Flint-Version: 2026-09-07"
Add expand=payout_destination to inline each payout's destination. On a reversal, expand=original_payout inlines the payout it reverses; on a reversed payout, expand=reversed_by_payout inlines the reversal. Each row without that link returns the field as null. payout_destination also needs money_movement.payout_settings.read; see Expanding responses.
status on payoutA succeeded 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. A payout Flint imports from your processor, rather than creating it, follows the processor: scheduled when the processor sent it automatically and manual when it didn't. trace_id.status is pending, available, or unsupported. When it is available, trace_id.value holds the bank's trace number. Give that value to your bank to locate a deposit that is late. trace_id is absent when Flint has no trace information.
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. The payout's contents don't change: see After a failure or reversal.
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:
- Check the destination with
GET /v1/payout-destinations/{payout_destination_id}. Afailed,disabled, orverification_requiredstatus means it needs attention. - Correct or replace the bank account in the
payoutscomponent. - 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 succeeded 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. Until completion, reversal_status stays none.
When Flint has a separate payout for the reversal, original_payout_id on that payout points to the original, and reversed_by_payout_id on the original points to the reversal payout. Each reference is present only when Flint has the matching payout. A reversal reference can appear before completion, so use reversal_status to check whether the money has returned.
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. The payout's contents don't change. If you use manual payouts, you can create another payout after the funds are available.
What's in a payout#
Filter balance transactions by payout_id to list the ones a payout carried:
curl "https://api.withflintpay.com/v1/balance-transactions?payout_id=po_01JABCDEFGHJKMNPQRSTVWXYZ0&page_size=100" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Flint-Version: 2026-09-07"
Each row is a full balance transaction: its type (payment, refund, dispute, adjustment, and so on), amount_money, fee_money, net_money, order_id, and related_resource. Rows come newest first, like the rest of the list. Refunds and disputes are negative, and the rows' net_money adds up to the payout's amount_money. The payout's own payout row isn't included. Add expand=order to inline each row's order, or combine payout_id with type to total one kind of movement.
When the contents are ready#
Flint prepares a payout's contents once, when your processor reports that it has finished reconciling the payout. For a payout your schedule sends, that is usually within minutes of the payout being created, so you can read the contents before the money reaches your bank. It doesn't depend on the payout's status: once prepared, the contents can be listed while the payout is pending, in_transit, succeeded, or failed, and after a reversal.
Flint publishes the contents only when all of them tie out: every balance transaction exists, none already belongs to another payout, and their net_money adds up to the payout's amount_money. If any check fails, Flint publishes none of them, and the payout stays unprepared. You never see part of a payout's contents.
Preparing the contents sets payout_id on each balance transaction in the same step. A transaction's payout_id is set once and never changes after that, including when the payout later fails or is reversed. Flint never adds, removes, or replaces rows in contents it has prepared, so a page_token stays valid while you page, even if the payout's status changes in between.
Setting payout_id sends balance_transaction.updated for each transaction assigned to the payout. Use the payout_id filter to read the payout's complete contents.
503 and 409 responses#
503 SERVICE_UNAVAILABLEwithRetry-After: 60: the contents aren't prepared yet. This isn't an empty payout. Until the contents are prepared, no balance transaction has this payout'spayout_id, so a transaction withoutpayout_idmight still belong to it. Retry after the delay and record the payout's contents only from a successful response. If the503persists, contact Flint support with therequest_id.409 ACTION_NOT_ALLOWEDwithdetails[0].reasonnot_itemizedandparampayout_id: the payout doesn't list the balance transactions inside it. Flint learns this from your processor, and it applies to manual payouts, such as ones you create withPOST /v1/payouts. It doesn't depend on the payout'sstatus, the error has nodetails[0].current_status, andremediation.retryisnone: the same request always returns it. Don't retry.
To account for a payout that isn't itemized, use its own payout balance transaction, whose related_resource is the payout:
curl "https://api.withflintpay.com/v1/balance-transactions?type=payout&related_resource_type=payout&related_resource_id=po_01JABCDEFGHJKMNPQRSTVWXYZ0" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Flint-Version: 2026-09-07"
That row is the amount that left your Flint balance. The balance transactions that funded it don't get its payout_id.
After a failure or reversal#
A failure and a reversal both return the money to your balance, and neither changes the payout's contents or the payout_id on the balance transactions it carried. A failed payout's status becomes failed, and a payout_failure balance transaction returns the amount to available_money. A reversed payout's status stays succeeded and its reversal_status becomes reversed, and a payout_reversal balance transaction returns the amount.
The returned funds are a new balance transaction with its own balance_transaction_id, and it has no payout_id until a later payout carries it. The transactions the original payout carried keep its payout_id and never move to a later payout. If a later payout carries the returned funds, its contents list the payout_failure or payout_reversal row, not the original transactions.
For matching rows 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, including direction. Read it to distinguish a deposit from an inbound withdrawal.
A move to succeeded, failed, or canceled sends its specific event, without payout.updated alongside it. Other public changes send payout.updated. Observing the same state again sends no new event. 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 succeeded. Handle it separately from payout.succeeded.
Changes to destinations and settings have their own events: payout_destination.created, payout_destination.updated, payout_destination.disabled, payout_destination.archived, and payout_settings.updated. Each carries the payout destination or payout settings in data.object; see Webhook event payloads.
Errors#
On POST /v1/payouts:
On POST /v1/payouts/{payout_id}/cancel:
On GET /v1/balance-transactions with payout_id:
On PATCH /v1/payout-settings:
On DELETE /v1/payout-destinations/{payout_destination_id}:
Next steps#
- Reconciliation: match a deposit to the balance transactions that funded it.
- Reports: payout and balance transaction reports as CSV.
- Webhook event payloads: payout, destination, and balance event payloads.
- Merchant billing: what Flint collects from your balance.
- Money Movement API reference: balances, payouts, payout settings, and destinations.