Money movement

Money movement covers what happens to funds after a payment succeeds: balances, the balance transaction ledger, payouts, and the payout destinations funds settle to. Your balance separates pending funds from available funds, while balance transactions give you a per-event ledger (charges, refunds, fees, holds, and payouts), each with gross, fee, and net amounts and links back to the originating order.

Payouts move available funds to a payout destination such as a bank account. Most merchants rely on automatic payouts driven by payout settings (interval, payout days, delay, and statement descriptor), but you can also create standard manual payouts. The initial destination is collected by embedded Account Onboarding. Later destination changes use the embedded Payouts component through a merchant account session. A payout tracks its status from creation through arrival, including failures and reversals.

A balance transaction's fee_money is Flint's own fee on that movement, never a provider cost passed through. On a payment it has the same magnitude as processing_fee_money with a negative sign, and net_money is amount_money plus fee_money. Refund, dispute, return, and standard payout transactions carry no fee_money, so theirs is 0. That is not the same as costing nothing: disputes, ACH returns, failed ACH payments, and instant bank verification carry separate event fees assessed against your merchant account, readable on merchant billing. See Processing Fees.

Read endpoints here are useful for reconciliation: list balance transactions to tie settled funds back to orders, and list payouts to match deposits on a bank statement.

List balance transactions#

GET/v1/balance-transactionsRequires scope: money_movement.balance_transactions.read

Returns a paginated ledger of balance-affecting transactions, including availability timing and related public resources.

Query parameters
currencystring

Optional 3-letter currency filter.

typeenum

Optional balance transaction type filter.

paymentrefunddisputedispute_reversalreturnrecoverypayoutpayout_failurepayout_cancellationpayout_reversalpayout_advancepayout_advance_fundingreserve_holdreserve_releasepayout_holdpayout_hold_releaseadjustmentmerchant_billing_paymentmerchant_billing_payment_reversal
related_object_typeenum

Optional related object type filter.

payment_intentrefunddisputepayoutpayout_destinationreserveadjustmentmerchant_subscription_invoice
related_object_idstring

Optional related object ID filter.

statusenum

Optional balance transaction status filter. Default list responses exclude terminal audit rows; filter by reversed or superseded to retrieve those rows explicitly.

pendingavailablereservedreversedfailedsuperseded
created_afterstring

Only include balance transactions created at or after this RFC3339 timestamp.

created_beforestring

Only include balance transactions created at or before this RFC3339 timestamp.

available_afterstring

Only include balance transactions available at or after this RFC3339 timestamp.

available_beforestring

Only include balance transactions available at or before this RFC3339 timestamp.

page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous response.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/balance-transactions \
  -H "Authorization: Bearer YOUR_API_KEY"

Get a balance transaction#

GET/v1/balance-transactions/{balance_transaction_id}Requires scope: money_movement.balance_transactions.read

Returns one balance transaction by ID, with optional related order expansion.

Path parameters
balance_transaction_idstringrequired

Flint balance transaction ID.

Query parameters
expandarray of enum

Supported expansions: order. Expansion requires money_movement.balance_transactions.read plus commerce.orders.read. Limits: at most 10 unique expand paths per request; path depth at most 2. Send repeated expand parameters as the canonical form, for example expand=order&expand=order. Comma-separated values, expand[]=order, and numeric expand[0]=order are accepted for common client compatibility.

order
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDDANGLING_EXPANSION_REFERENCEEXPANSION_DEPENDENCY_UNAVAILABLEEXPANSION_RESOLUTION_FAILEDINSUFFICIENT_SCOPEINTERNAL_ERRORINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/balance-transactions/{balance_transaction_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

List balances#

GET/v1/balancesRequires scope: money_movement.balances.read

Returns an unpaginated current balance snapshot grouped by currency and balance source for the authenticated merchant.

Query parameters
currencystring

Optional 3-letter currency filter.

Response · 200
dataarray of objectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/balances \
  -H "Authorization: Bearer YOUR_API_KEY"

Get payout settings#

GET/v1/payout-settingsRequires scope: money_movement.payout_settings.read or money_movement.payout_settings.write

Returns payout settings that control default payout behavior for the authenticated merchant.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/payout-settings \
  -H "Authorization: Bearer YOUR_API_KEY"

Update payout settings#

PATCH/v1/payout-settingsIdempotentRequires scope: money_movement.payout_settings.write

Updates mutable payout settings for the authenticated merchant. Safe to retry with the same Idempotency-Key.

Request body
default_payout_destinationsmap of string
delay_days_overrideinteger
intervalenum
manualdailyweeklymonthly
minimum_balance_by_currencymap of object
monthly_payout_daysarray of integer
statement_descriptorstring
weekly_payout_daysarray of string
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDREQUEST_TIMEOUTSERVICE_UNAVAILABLE
Bash
curl -X PATCH https://api.withflintpay.com/v1/payout-settings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "default_payout_destinations": {},
    "delay_days_override": 0,
    "interval": "manual",
    "minimum_balance_by_currency": {},
    "monthly_payout_days": [
      0
    ],
    "statement_descriptor": "",
    "weekly_payout_days": [
      ""
    ]
  }'

List payout destinations#

GET/v1/payout-settings/destinationsRequires scope: money_movement.payout_settings.read or money_movement.payout_settings.write

Returns a paginated list of payout destinations available to the authenticated merchant.

Query parameters
currencystring

Optional 3-letter currency filter.

typeenum

Optional payout destination type filter.

bank_accountdebit_card
statusenum

Optional payout destination status filter.

pendingactiveverification_requireddisableddeletedfailed
available_payout_methodenum

Optional available payout method filter.

standard
default_for_currencyboolean

Whether to return only destinations that are the default for their currency.

include_deletedboolean

Whether to include deleted payout destinations.

page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous response.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/payout-settings/destinations \
  -H "Authorization: Bearer YOUR_API_KEY"

Get a payout destination#

GET/v1/payout-settings/destinations/{payout_destination_id}Requires scope: money_movement.payout_settings.read or money_movement.payout_settings.write

Returns one payout destination by ID.

Path parameters
payout_destination_idstringrequired

Flint payout destination ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl https://api.withflintpay.com/v1/payout-settings/destinations/{payout_destination_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Update payout destination metadata#

PATCH/v1/payout-settings/destinations/{payout_destination_id}IdempotentRequires scope: money_movement.payout_settings.write

Updates mutable metadata and settings for a payout destination. Safe to retry with the same Idempotency-Key.

Path parameters
payout_destination_idstringrequired

Flint payout destination ID.

Request body
metadatamap of string
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDREQUEST_TIMEOUTSERVICE_UNAVAILABLE
Bash
curl -X PATCH https://api.withflintpay.com/v1/payout-settings/destinations/{payout_destination_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "metadata": {}
  }'

Delete or disable a payout destination#

DELETE/v1/payout-settings/destinations/{payout_destination_id}IdempotentRequires scope: money_movement.payout_settings.write

Deletes or disables an eligible payout destination and returns the resulting destination. Safe to retry with the same Idempotency-Key.

Path parameters
payout_destination_idstringrequired

Flint payout destination ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDREQUEST_TIMEOUTSERVICE_UNAVAILABLE
Bash
curl -X DELETE https://api.withflintpay.com/v1/payout-settings/destinations/{payout_destination_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{}'

List payouts#

GET/v1/payoutsRequires scope: money_movement.payouts.read or money_movement.payouts.write

Returns a paginated list of payouts with optional filters for status, currency, destination, method, and timing.

Query parameters
currencystring

Optional 3-letter currency filter.

methodenum

Optional payout method filter.

standard
balance_source_typeenum

Optional Flint balance source type filter.

cardbank_accountfpx
payout_destination_idstring

Optional payout destination ID filter.

statusenum

Optional payout status filter.

pendingin_transitpaidfailedcanceled
created_afterstring

Only include payouts created at or after this RFC3339 timestamp.

created_beforestring

Only include payouts created at or before this RFC3339 timestamp.

arrival_afterstring

Only include payouts arriving at or after this RFC3339 timestamp.

arrival_beforestring

Only include payouts arriving at or before this RFC3339 timestamp.

page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous response.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/payouts \
  -H "Authorization: Bearer YOUR_API_KEY"

Create a payout#

POST/v1/payoutsIdempotentRequires scope: money_movement.payouts.write

Creates a payout from an available balance to an eligible payout destination. Safe to retry with the same Idempotency-Key.

Request body
amount_moneyobjectrequired

Monetary amount represented as integer minor units plus an ISO 4217 currency code.

balance_source_typeenum
cardbank_accountfpx
descriptionstring
metadatamap of string
methodenum
standard
payout_destination_idstring
statement_descriptorstring
Response · 201
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDREQUEST_TIMEOUTSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/payouts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "amount_money": {
      "amount": 0,
      "currency": "USD"
    }
  }'

Get a payout#

GET/v1/payouts/{payout_id}Requires scope: money_movement.payouts.read or money_movement.payouts.write

Returns one payout by ID, with optional related payout and payout destination expansions.

Path parameters
payout_idstringrequired

Flint payout ID.

Query parameters
expandarray of enum

Supported expansions: original_payout, payout_destination, reversed_by_payout. Expansion requires money_movement.payouts.read plus the read scope for each expanded resource. Limits: at most 10 unique expand paths per request; path depth at most 2. Send repeated expand parameters as the canonical form, for example expand=original_payout&expand=payout_destination. Comma-separated values, expand[]=original_payout, and numeric expand[0]=original_payout are accepted for common client compatibility.

original_payoutpayout_destinationreversed_by_payout
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDDANGLING_EXPANSION_REFERENCEEXPANSION_DEPENDENCY_UNAVAILABLEEXPANSION_RESOLUTION_FAILEDINSUFFICIENT_SCOPEINTERNAL_ERRORINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/payouts/{payout_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Cancel a payout#

POST/v1/payouts/{payout_id}/cancelIdempotentRequires scope: money_movement.payouts.write

Cancels an eligible payout before it leaves Flint-controlled processing and returns the resulting payout.

Path parameters
payout_idstringrequired

Flint payout ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDREQUEST_TIMEOUTSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/payouts/{payout_id}/cancel \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{}'

List payout entries#

GET/v1/payouts/{payout_id}/entriesRequires scope: money_movement.payouts.read or money_movement.payouts.write

Lists the authoritative balance-transaction allocations for a payout in ascending occurrence order. A paid payout returns an unavailable error instead of incomplete or inferred entries.

Path parameters
payout_idstringrequired

Flint payout ID.

Query parameters
page_sizeinteger

Number of payout entries to return.

page_tokenstring

Opaque token returned by the previous page.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_PAGE_SIZEINVALID_PAGE_TOKENINVALID_REQUESTPAYOUT_ENTRIES_UNAVAILABLEPAYOUT_NOT_FOUNDRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/payouts/{payout_id}/entries \
  -H "Authorization: Bearer YOUR_API_KEY"
Rate this doc