FlintflintDocs

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 (still settling), available funds (ready to pay out), and instant-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 manual payouts, including instant payouts to eligible destinations for a fee. Payout destinations are added and updated through hosted destination sessions, which handle any verification required to manage them; a payout tracks its status from creation through arrival, including failures and reversals.

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.

Endpoints

List balance transactions#

GET/v1/balance-transactions

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_reversalpayoutpayout_failurepayout_cancellationpayout_reversalpayout_advancepayout_advance_fundingprocessor_feeflint_feereserve_holdreserve_releasepayout_holdpayout_hold_releaseadjustment
related_object_typeenum

Optional related object type filter.

payment_intentrefunddisputepayoutpayout_destinationreserveadjustment
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
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}

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
Bash
curl https://api.withflintpay.com/v1/balance-transactions/{balance_transaction_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

List balances#

GET/v1/balances

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
Bash
curl https://api.withflintpay.com/v1/balances \
  -H "Authorization: Bearer YOUR_API_KEY"

Get payout settings#

GET/v1/payout-settings

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

Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl https://api.withflintpay.com/v1/payout-settings \
  -H "Authorization: Bearer YOUR_API_KEY"

Update payout settings#

PATCH/v1/payout-settingsIdempotent

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
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/destinations

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.

standardinstant
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
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}

Returns one payout destination by ID.

Path parameters
payout_destination_idstringrequired

Flint payout destination ID.

Response · 200
dataobjectrequired
metaobject
request_idstring
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}Idempotent

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
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}Idempotent

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
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/payouts

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.

standardinstant
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
Bash
curl https://api.withflintpay.com/v1/payouts \
  -H "Authorization: Bearer YOUR_API_KEY"

Create a payout#

POST/v1/payoutsIdempotent

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
standardinstant
payout_destination_idstring
statement_descriptorstring
Response · 201
dataobjectrequired
metaobject
request_idstring
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}

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
Bash
curl https://api.withflintpay.com/v1/payouts/{payout_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Cancel a payout#

POST/v1/payouts/{payout_id}/cancelIdempotent

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
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 '{}'
Rate this doc