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. See Payouts for schedules, manual payouts, and failures.

A balance transaction's fee_money is Flint's own fee on that movement, never a provider cost passed through. At API version 2026-09-07, fee charges are positive and returned fees are negative. On a payment, fee_money equals processing_fee_money, and net_money is amount_money minus 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.

The Money movement object#

Every field on a money movement, as returned by retrieve and carried by the endpoints below.

Attributes

amount_moneyobjectRequired

Signed gross amount of this balance movement, before any fee.

available_atstring

RFC3339 timestamp.

balance_transaction_idstringRequired
currencystringRequired

ISO 4217 currency code.

descriptionstring
fee_moneyobjectRequired

Flint fee for this balance movement, never a provider cost passed through. Charges are positive; returned fees are negative. A payment of 5000 with a fee of 175 has a net amount of 4825. A payout reversal returning a fee of 25 reports fee_money -25.

hold_detailobject
merchant_idstringRequired
net_moneyobjectRequired

Signed net effect on your Flint balance: amount_money minus fee_money in the same currency.

occurred_atstringRequired

RFC3339 timestamp.

orderobject or null
order_idstring
payout_idstring

Flint payout containing this balance transaction. Present after the paid payout's entries are recorded.

related_balance_transaction_idsarray of string
related_resourceone of
statusenumRequired
  • pending
  • available
  • reserved
  • reversed
  • failed
  • superseded
typeenumRequired
  • payment
  • refund
  • dispute
  • dispute_reversal
  • return
  • recovery
  • payout
  • payout_failure
  • payout_cancellation
  • payout_reversal
  • payout_advance
  • payout_advance_funding
  • reserve_hold
  • reserve_release
  • payout_hold
  • payout_hold_release
  • adjustment
  • merchant_billing_payment
  • merchant_billing_payment_reversal
JSON
{
  "amount_money": {
    "amount": 5000,
    "currency": "USD"
  },
  "available_at": "2026-03-19T00:00:00Z",
  "balance_transaction_id": "btxn_123",
  "currency": "USD",
  "description": "Payment for order 1001",
  "fee_money": {
    "amount": 175,
    "currency": "USD"
  },
  "merchant_id": "mer_123",
  "net_money": {
    "amount": 4825,
    "currency": "USD"
  },
  "occurred_at": "2026-03-17T14:30:00Z",
  "order_id": "ord_123",
  "payout_id": "po_123",
  "status": "available",
  "type": "payment"
}

List balance transactions#

GET/v1/balance-transactions

Requires 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.

  • payment
  • refund
  • dispute
  • dispute_reversal
  • return
  • recovery
  • payout
  • payout_failure
  • payout_cancellation
  • payout_reversal
  • payout_advance
  • payout_advance_funding
  • reserve_hold
  • reserve_release
  • payout_hold
  • payout_hold_release
  • adjustment
  • merchant_billing_payment
  • merchant_billing_payment_reversal
related_object_typeenum

Optional related object type filter.

  • payment_intent
  • refund
  • dispute
  • payout
  • payout_destination
  • reserve
  • adjustment
  • merchant_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.

  • pending
  • available
  • reserved
  • reversed
  • failed
  • superseded
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
curl https://api.withflintpay.com/v1/balance-transactions \
  -H "Flint-Version: 2026-09-07" \
  -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. Repeat expand, for example expand=order&expand=order, or pass one comma-separated value.

  • order

Response · 200

dataobjectRequired
metaobject
request_idstring
curl https://api.withflintpay.com/v1/balance-transactions/{balance_transaction_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "amount_money": {
      "amount": 5000,
      "currency": "USD"
    },
    "available_at": "2026-03-19T00:00:00Z",
    "balance_transaction_id": "btxn_123",
    "currency": "USD",
    "description": "Payment for order 1001",
    "fee_money": {
      "amount": 175,
      "currency": "USD"
    },
    "merchant_id": "mer_123",
    "net_money": {
      "amount": 4825,
      "currency": "USD"
    },
    "occurred_at": "2026-03-17T14:30:00Z",
    "order_id": "ord_123",
    "payout_id": "po_123",
    "status": "available",
    "type": "payment"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

List balances#

GET/v1/balances

Requires 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
curl https://api.withflintpay.com/v1/balances \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get payout settings#

GET/v1/payout-settings

Requires 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
curl https://api.withflintpay.com/v1/payout-settings \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update payout settings#

PATCH/v1/payout-settingsIdempotent

Requires 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 or null
intervalenum
  • manual
  • daily
  • weekly
  • monthly
minimum_balance_by_currencymap of object
monthly_payout_daysarray of integer
statement_descriptorstring
weekly_payout_daysarray of enum

Weekdays on which weekly payouts are sent. Allowed values are monday, tuesday, wednesday, thursday, and friday.

  • monday
  • tuesday
  • wednesday
  • thursday
  • friday

Response · 200

Same response as Get payout settings.

curl -X PATCH https://api.withflintpay.com/v1/payout-settings \
  -H "Flint-Version: 2026-09-07" \
  -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": [
      "monday"
    ]
  }'

List payout destinations#

GET/v1/payout-settings/destinations

Requires 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_account
  • debit_card
statusenum

Optional payout destination status filter.

  • pending
  • active
  • verification_required
  • disabled
  • deleted
  • failed
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
curl https://api.withflintpay.com/v1/payout-settings/destinations \
  -H "Flint-Version: 2026-09-07" \
  -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
curl https://api.withflintpay.com/v1/payout-settings/destinations/{payout_destination_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update payout destination metadata#

PATCH/v1/payout-settings/destinations/{payout_destination_id}Idempotent

Requires 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 or null

Caller-owned metadata. Omit this field to leave metadata unchanged. Send an object to merge by key, set a key to null to remove it, or set metadata to null to clear all metadata. An empty object makes no change. Empty strings are stored. Keys starting with flint_ are reserved and cannot be written through the public API.

Response · 200

Same response as Get a payout destination.

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

List payouts#

GET/v1/payouts

Requires 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.

  • card
  • bank_account
  • fpx
payout_destination_idstring

Optional payout destination ID filter.

external_reference_idstring

Exact-match filter on the caller-owned external reference ID.

querystring

Search across payout ID, external reference ID, description, and statement descriptor. Text fields match any part of the value, and %, _ and \ are ordinary characters, not wildcards. IDs match from the start and need the type prefix, such as ord_01.

statusenum

Optional payout status filter.

  • pending
  • in_transit
  • paid
  • failed
  • canceled
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
curl https://api.withflintpay.com/v1/payouts \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create a payout#

POST/v1/payoutsIdempotent

Requires 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
  • card
  • bank_account
  • fpx
descriptionstring
external_reference_idstring

Caller-owned identifier for this resource in an external system.

metadatamap of string
methodenum
  • standard
payout_destination_idstring
statement_descriptorstring

Response · 201

dataobjectRequired
metaobject
request_idstring
curl -X POST https://api.withflintpay.com/v1/payouts \
  -H "Flint-Version: 2026-09-07" \
  -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. Repeat expand, for example expand=original_payout&expand=payout_destination, or pass one comma-separated value.

  • original_payout
  • payout_destination
  • reversed_by_payout

Response · 200

Same response as Create a payout.

curl https://api.withflintpay.com/v1/payouts/{payout_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "amount_money": {
      "amount": 25000,
      "currency": "USD"
    },
    "arrival_at": "2026-03-20T09:00:00Z",
    "balance_source_type": "card",
    "created_at": "2026-03-17T14:30:00Z",
    "currency": "USD",
    "description": "Weekly payout",
    "fee_amount_status": "final",
    "fee_money": {
      "amount": 0,
      "currency": "USD"
    },
    "held_money": {
      "amount": 0,
      "currency": "USD"
    },
    "initiated_by": "scheduled",
    "merchant_id": "mer_123",
    "metadata": {
      "batch": "weekly"
    },
    "method": "standard",
    "net_money": {
      "amount": 25000,
      "currency": "USD"
    },
    "payout_destination_id": "pdest_123",
    "payout_id": "po_123",
    "reversal_status": "none",
    "status": "paid",
    "updated_at": "2026-03-20T09:00:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}
curl -X POST https://api.withflintpay.com/v1/payouts/{payout_id}/cancel \
  -H "Flint-Version: 2026-09-07" \
  -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}/entries

Requires 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
curl https://api.withflintpay.com/v1/payouts/{payout_id}/entries \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Was this helpful?