Skip to content

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
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. Funds held for payouts you created are already left out.
  • held_money is set aside for payouts you created that haven't been debited from your balance yet. It isn't payable. The amount leaves held_money when the payout's payout balance transaction posts, which usually happens before the create request returns. If your processor rejects the payout, the amount goes back to available_money. If Flint can't tell whether the processor created it, such as after a timeout, the amount stays in held_money until Flint finds out.
  • reserve_money is held in reserve. It doesn't overlap available_money or held_money.
  • available_by_source_type and pending_by_source_type split the available and pending amounts by balance source. The card bucket includes both card payments and ACH debits. bank_account is a separate bucket that some accounts have; treat the keys as an open set. A payout draws from one source, so available_by_source_type also limits how much one payout can send.
  • observed_at is when Flint observed these amounts.
  • 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.

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
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. 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
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, 0 through 31, in place of the default. A payment's available_at can still be later, such as for a new account's first payments. 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 ACTION_NOT_ALLOWED and reason managed_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 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, 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_onboarding component.
  • Later accounts are added, and existing ones fixed or removed, in the payouts component.

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
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
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
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 destination
Final values do not change again
  • pending
    Added and not yet usable.
  • active
    Usable for payouts. A destination can be active without being the default for its currency.
  • verification_required
    Your processor's checks on the bank account failed. The owner corrects or replaces it in the payouts component before it can receive payouts.
  • 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.
  • archivedFinal
    Deleted, and still readable by ID. Left out of the destination list unless status names archived.

status 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
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
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
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
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
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 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_date is the expected deposit date.
  • succeeded
    The transfer succeeded.
  • failedFinal
    The deposit didn't land. For an outbound payout, the funds are back in your available balance.
  • canceledFinal
    Canceled before it was sent. For an outbound payout, the funds are back in your available balance.
Warning:

A 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:

  1. Check the destination with GET /v1/payout-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 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
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_UNAVAILABLE with Retry-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's payout_id, so a transaction without payout_id might still belong to it. Retry after the delay and record the payout's contents only from a successful response. If the 503 persists, contact Flint support with the request_id.
  • 409 ACTION_NOT_ALLOWED with details[0].reason not_itemized and param payout_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 with POST /v1/payouts. It doesn't depend on the payout's status, the error has no details[0].current_status, and remediation.retry is none: 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
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.

  1. What happens: Your schedule runs, or you create a payout
  2. Flint sends: payout.created
    A payout was created. Its direction identifies a bank deposit or a debit to cover a negative balance.
  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.succeededorpayout.failed
    Paid, or failed with the funds returned to your balance.

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:

  • HTTP 400
    param names the field: amount_money or amount_money.currency is missing, method is not standard, or balance_source_type is not card or bank_account; amount_money.amount is not above zero; the currency is not a supported three-letter code; statement_descriptor is longer than 22 characters; or external_reference_id is empty or longer than 255 characters.
  • HTTP 404
    No destination with that payout_destination_id, which param names.
  • HTTP 409
    Reason configuration_required means your schedule is automatic. details[0].current_interval shows the current interval. Set it to manual first.
  • HTTP 409
    No single source covers the amount, or the source you named doesn't. details[0].available_by_source_type lists what each source has available, after funds held for your other payouts. Create one payout per source, each within that source's amount.
  • HTTP 409
    Reason configuration_required means no destination was given and the currency has no default.
  • HTTP 409
    Reason configuration_required means the destination is not active, is in another currency, or cannot receive the payout.
  • HTTP 409
    The key was already used for a different payout request. See Replay, conflict, or in progress.
  • HTTP 409
    Read details[0].reason. Complete onboarding for onboarding_required. For capability_not_requested, contact Flint support to add payouts. For billing_suspended, platform_review, or processing_not_enabled, follow the actions under Merchant readiness. Do not retry until the readiness condition clears.
  • HTTP 409
    Reason capability_unavailable with capability receive_payouts means payouts are turned off for the account. readiness.payouts on GET /v1/merchant lists what to complete.
  • HTTP 409
    Reason capability_unavailable with capability create_standard_payouts means standard payouts are turned off for the account. Check create_standard_payouts in readiness.capabilities on GET /v1/merchant.

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

  • HTTP 404
    No payout with that ID exists in this environment. param is payout_id.
  • HTTP 409
    Reason unsupported_state means the payout is past pending. details[0].current_status is its status.
  • HTTP 409
    Reason not_offered means your schedule created the payout. Switch to manual to stop future ones.

On GET /v1/balance-transactions with payout_id:

  • HTTP 400
    payout_id is not a payout ID (param is payout_id), or page_token came from a request with different filters (param is page_token). Start again from the first page.
  • HTTP 404
    No payout with that ID exists in this environment. param is payout_id.
  • HTTP 409
    The payout doesn't list its contents, such as a manual payout, and details[0].reason is not_itemized. The refusal is permanent and doesn't depend on the payout's status. Account for the payout with its own payout balance transaction.
  • HTTP 503
    SERVICE_UNAVAILABLERetry the same request
    The payout's contents aren't prepared yet, whatever its status. Retry after the Retry-After header, and don't treat the payout as empty.

On PATCH /v1/payout-settings:

  • HTTP 400
    param names the field: interval is not manual, daily, weekly, or monthly; a weekly_payout_days day is not monday through friday; interval is weekly without weekly_payout_days or monthly without monthly_payout_days; or a payout day list was sent without interval. Other causes: the body has no fields to change (REQUIRED, param: body); weekly_payout_days was sent with an interval other than weekly, or monthly_payout_days with an interval other than monthly (NOT_ALLOWED); a monthly day is not 1 through 31; delay_days_override is not 0 through 31 or is below the account's minimum delay; or statement_descriptor is longer than 22 characters. With default_payout_destinations: expected_version is missing (REQUIRED, param: expected_version); a key isn't a 3-letter currency code or names a currency twice; or a value is null or isn't a payout destination ID (INVALID_VALUE, with param naming the entry, such as default_payout_destinations.USD); or a destination isn't in the currency it's listed under (NOT_ALLOWED).
  • HTTP 404
    A destination in default_payout_destinations doesn't exist in this environment. param names the entry, such as default_payout_destinations.USD, and details[0].resource_id the destination.
  • HTTP 409
    Reason configuration_required: a destination in default_payout_destinations isn't active, or your payment processor refused the change and nothing changed. param names the entry and details[0].resource_id the destination.
  • HTTP 409
    Reason capability_unavailable with details[0].capability manage_payout_destinations: Flint can't change this account's payout destinations, so it can't change a default either. Change it in the payouts component.
  • HTTP 409
    The account is still under its new-account payout terms. Send weekly or monthly with one payout day, and a delay_days_override of at least delay_days, or wait until details[0].payout_terms_expires_at.
  • HTTP 409
    The settlement delay for your account can't be changed.
  • HTTP 409
    VERSION_CONFLICTRefresh, then retry
    The settings changed after you read them. details[0].current_version is the current version. Read them again, reconcile your draft, and send it with that version and a new Idempotency-Key.
  • HTTP 409
    CONCURRENT_MODIFICATIONRetry the same request
    Another change to your payout settings or an affected destination was starting, and nothing changed. Send the same request again with the same Idempotency-Key.
  • HTTP 409
    OPERATION_IN_PROGRESSRetry the same request
    An earlier change to your payout settings or an affected destination is running, or stopped less than two minutes ago and Flint is waiting to read its outcome from your payment processor. Nothing changed. Wait the Retry-After seconds, then send the same request again.
  • HTTP 500
    Flint can't yet tell whether an earlier change to an affected payout destination reached your payment processor. Send that destination change again with its original Idempotency-Key, as Recovery reads describes. If the error persists, contact Flint support with the Idempotency-Key, the endpoint, and the request_id.
  • HTTP 409
    Reason platform_review. Flint has placed a review pause on the account and holds payouts, so the schedule can't change. Do not retry. Flint puts back your schedule when the review ends.

On DELETE /v1/payout-destinations/{payout_destination_id}:

  • HTTP 404
    No destination with that ID exists in this environment. param is payout_destination_id.
  • HTTP 409
    The destination is the active default for its currency. Make another destination the default with default_payout_destinations on PATCH /v1/payout-settings, then retry.

Next steps#

Was this helpful?