Platform fees
A platform fee is the cut a partner app you own charges on a payment it created for an installed merchant. See Platform fees for how to charge one. These routes are how you, as the app's owner, see what your apps charged, what Flint holds for you, and every movement of that money.
PlatformFee: one per fee-bearing payment, with what the request asked for and what Flint charged.PlatformFeeBalance: one per partner app and currency, with what is available, pending, and held in reserve.PlatformFeeBalanceTransaction: one per movement of the balance, such as a collected fee and its reserve hold.PlatformFeePayout: a transfer from your platform fee balance to your merchant balance.
Scopes and credentials#
Every route requires money_movement.platform_fees.read and your own merchant's credentials: an API key or a dashboard session of the merchant that owns the partner app. Partner app tokens can't read them, and neither can the installed merchants. The scope is separate from developer.partner_apps.read because it is revenue data: people who manage an app's permissions needn't see its money. A merchant that owns no partner app gets empty lists.
Live records are in your live environment. Test records are in your default sandbox at the time the payment or checkout session was created.
Platform fees#
GET /v1/platform-fees lists fees newest first, then by platform_fee_id. Filter by partner_app_id, partner_app_install_id, merchant_id (the installed merchant charged), payment_intent_id, status (several values), created_after, and created_before. GET /v1/platform-fees/{platform_fee_id} returns one. The payment intent's platform_fee.platform_fee_id names it.
status | Meaning |
|---|---|
pending | The payment hasn't succeeded. amount_money is the fee Flint will charge. Flint prices it again at confirm and capture, lowering it when the merchant's cap or Flint's own fees leave less, and never above requested_amount_money. |
succeeded | Flint collected the fee with the payment. |
canceled | Final. Flint collected no fee, and amount_money is 0. canceled_reason says why: payment_not_completed, install_revoked, platform_capability_inactive, or uncollectible. Can gain values. |
refunded_money totals the fee returned to the installed merchant so far. It starts at zero, increases when a fee return completes, and decreases if that refund later fails. The fee stays succeeded. See Refunds and disputes.
requested_amount_money keeps what the request asked for. Once Flint posts a collected fee to your ledger, shortly after the payment succeeds, reserve_hold_money shows the share it moved into your reserve and reserve_available_at when that share is due back. They are a snapshot: losses draw on the reserve as a whole, so PlatformFeeBalance.reserve_money is what is held now.
Balances#
GET /v1/platform-fee-balances lists one balance per partner app and currency. Filter by partner_app_id and currency.
available_moneyis what Flint holds for you as available funds. It can be negative when a returned fee is owed back from your next fees.pending_moneyis fees Flint hasn't received as available funds yet. Flint makes a fee available only after the Stripe application fee that carries it matches what Flint expected, at that fee's available date.reserve_moneyis what Flint holds in your reserve: by default 20% of each fee, released at 00:00 UTC, 120 days after the end of the UTC day the fee was collected. In test mode, a reserve releases one day after that day ends.available_moneypluspending_moneyalways equals the sum ofamount_moneyover the app's balance transactions in that currency.
payouts_enabled is false while your platform is paused or your merchant account can't receive payouts. payouts_disabled_reason says which: platform_paused or merchant_payouts_unavailable. A run Flint defers for cash safety is still enabled; next_payout_at moves to the next run.
Balance transactions#
GET /v1/platform-fee-balance-transactions lists your ledger newest occurred_at first. Filter by partner_app_id, platform_fee_id, platform_fee_payout_id, type (several values), occurred_after, and occurred_before. GET /v1/platform-fee-balance-transactions/{platform_fee_balance_transaction_id} returns one.
type | Sign | When |
|---|---|---|
platform_fee | + | A fee is collected. Pending until Flint's application fee funds are available. |
reserve_hold | - | The reserve share of that fee, with the same status and available_at as the fee. |
reserve_release | + | Reserve returns: daily for the fees collected on one UTC day, or at once to cover a loss. |
loss_coverage | - | Reserve applied to a merchant's unrecovered loss, right after its reserve_release and linked to it in related_balance_transaction_ids. While the platform is paused, coverage beyond the reserve draws on held available fees with no release. |
loss_coverage_reversal | + | A covered loss was later recovered, so the coverage comes back. |
platform_fee_refund | - | Your fee returned to an installed merchant. |
platform_fee_refund_reversal | + | A return canceled or reversed after the payment refund failed. |
platform_fee_payout | - | Money moved to your merchant balance. |
platform_fee_payout_reversal | + | A failed payout returned its amount. |
type can gain values; treat an unknown value as other. amount_money is signed, and status is pending or available. platform_fee_payout_id is set once when a payout carries the entry, and never changes. The payout's own debit carries the same ID. A reversal waiting for a later payout instead names the failed payout in related_resource with resource_type: platform_fee_payout. status can become available and available_at can be set after an entry is written.
related_balance_transaction_ids links an entry to earlier transactions, and is [] when there are none. A loss_coverage_reversal links to the loss's loss_coverage entries.
Payouts#
GET /v1/platform-fee-payouts lists payouts newest first, then by platform_fee_payout_id. Filter by partner_app_id, status (several values), created_after, and created_before. GET /v1/platform-fee-payouts/{platform_fee_payout_id} returns one.
status | Meaning |
|---|---|
pending | Flint is sending the payout. |
succeeded | Flint transferred the amount to your merchant balance. succeeded_at records when. |
failed | Final. Its amount returned to the platform fee balance. failure_reason is merchant_cannot_receive or payout_failed. Treat unknown reasons as payout_failed. |
balance_transaction_id names the credit on your merchant ledger once Flint observes it. Linking it doesn't advance the payout's version or updated_at and sends no payout event. Those fields change when the payout settles. Your merchant ledger publishes the credit as platform_fee_payout and any transfer reversal as platform_fee_payout_reversal, both with related_resource.resource_type: platform_fee_payout. Filter /v1/balance-transactions by either type or by that related resource.
Events#
Platform fee events go to your own merchant account's webhook endpoints in the fee's mode, not to your partner endpoints:
- platform_
fee. created A partner app you own recorded a fee with a payment it created.statusispending, orcanceledwhen Flint can't collect the fee from the start, which also sendsplatform_fee.canceled. - platform_
fee. updated A fee changed without a new status: Flint pricedamount_moneyagain at confirm or capture, orrefunded_moneychanged after a fee return or its reversal. - platform_
fee. succeeded Flint collected the fee with its payment. - platform_
fee. canceled Flint collected no fee.canceled_reasonsays why. - platform_
fee_ payout. created Flint prepared a payout from your app's fee balance. - platform_
fee_ payout. succeeded Flint transferred the payout to your merchant balance. - platform_
fee_ payout. failed The payout failed and its amount returned to your platform fee balance.
Balances and balance transactions send no events; list them to reconcile.
The Platform fee object#
A platform fee your partner app charged, or asked to charge, on a payment it created for an installed merchant. Owned by the merchant that owns the partner app.
Returned by GET /v1/platform-fees/{platform_fee_id} and carried by the endpoints below.
Attributes
amount_moneyobjectRequiredThe fee Flint will charge until the payment succeeds, then the fee charged. Flint lowers it at confirm and capture to fit the merchant's cap and Flint's own fees; 0 once canceled.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
canceled_reasonenumWhy Flint collected no fee. Present only when status is canceled. Can gain values.
payment_not_completedinstall_revokedplatform_capability_inactiveuncollectible
checkout_session_idstringThe checkout session the payment came from. Absent when the fee was sent with the payment itself.
collected_atstringWhen Flint collected the fee with the payment. Absent unless status is succeeded.
created_atstringRequiredWhen the payment's create recorded the fee.
merchant_idstringRequiredThe installed merchant charged the fee, as on the install.
partner_app_idstringRequiredThe partner app that charged the fee.
partner_app_install_idstringRequiredThe install whose partner app token created the payment.
payment_intent_idstringRequiredThe payment the fee rides on, owned by the installed merchant. After that merchant resets the sandbox the payment was in, the ID no longer resolves.
platform_fee_idstringRequiredUnique identifier for the platform fee, the payment intent's platform_fee.platform_fee_id.
refunded_moneyobjectRequiredThe fee debited from the platform for returns so far, including opted-in payment refunds and returns of the whole application fee. Matches the platform ledger, including returns awaiting completion; reversals reduce the total. 0 when nothing has been debited.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
requested_amount_moneyobjectRequiredThe fee the request asked for.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
reserve_available_atstringThe original scheduled release date of the held share. Refunds can release their proportional share early. Absent until the fee posts, and when nothing was held. Setting it sends no event.
reserve_hold_moneyobjectThe share of the fee Flint held in your reserve when it posted the fee to your ledger. Absent until then. The original collection snapshot: refunds release their proportional share early, and loss coverage draws on the reserve as a whole. Read PlatformFeeBalance.reserve_money for what is held now. Setting it sends no event.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
statusenumRequiredWhere the fee stands. canceled is final.
pendingsucceededcanceled
updated_atstringRequiredWhen the fee last changed.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
{
"amount_money": {
"amount": 150,
"currency": "USD"
},
"collected_at": "2026-11-09T21:14:03Z",
"created_at": "2026-11-09T21:13:40Z",
"merchant_id": "mer_01KEZF7C00MPP0T9S0KH5BB4CC",
"partner_app_id": "papp_01KEZF7C00D8DXK5AXR7NPRJ0J",
"partner_app_install_id": "pinst_01KEZG2H7Y4M8K3B6W9Q5T1R0C",
"payment_intent_id": "pi_01KF2M8V1Z6X4C8N2B5M7Q3W9E",
"platform_fee_id": "pfee_01KF2M8W5C9T3B7Q1H4N6R2D0V",
"refunded_money": {
"amount": 0,
"currency": "USD"
},
"requested_amount_money": {
"amount": 150,
"currency": "USD"
},
"reserve_available_at": "2027-03-10T00:00:00Z",
"reserve_hold_money": {
"amount": 30,
"currency": "USD"
},
"status": "succeeded",
"updated_at": "2026-11-09T21:14:03Z",
"version": 3
}The Platform fee balance transaction object#
One entry of a partner app's platform fee ledger. Entries keep their amounts; status, available_at and the payout link can be filled later.
Returned by GET /v1/platform-fee-balance-transactions/{platform_fee_balance_transaction_id} and carried by the endpoints below.
Attributes
amount_moneyobjectRequiredThe signed effect on available_money plus pending_money: positive for money in, negative for money out.
amountintegerRequiredSigned amount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
available_atstringWhen the entry becomes, or became, available. Absent while Flint hasn't verified the application fee that carries it.
created_atstringRequiredWhen Flint recorded the entry.
descriptionstringDisplay text, not for matching.
occurred_atstringRequiredWhen the movement happened.
partner_app_idstringRequiredThe partner app the entry belongs to.
platform_fee_balance_transaction_idstringRequiredUnique identifier for the balance transaction.
platform_fee_idstringThe fee the entry concerns, when it concerns one.
platform_fee_payout_idstringThe payout that carried the entry. Set once when a payout is prepared, and never changed.
related_balance_transaction_idsarray of stringRequiredEarlier entries this one is linked to. Empty when none.
related_resourceobjectThe Flint resource behind the entry, when it has one other than the fee.
resource_idstringRequiredPublic Flint ID of the referenced resource.
resource_typeenumRequiredPublic resource kind identified by resource_id, such as payment_intent for a payment.
api_keyapi_request_logbalancebalance_transactionbundlebundle_componentcategorycheckout_sessioncheckout_session_customer_verificationcredit_notecredit_note_allocationcustom_domaincustomercustomer_addresscustomer_deletion_requestcustomer_email_preferencescustomer_sessioncustomer_tax_exemptioncustomer_verificationdelivery_choice_groupdelivery_location_setdelivery_methoddelivery_profiledelivery_quotedelivery_ratedelivery_rate_callbackdelivery_revocationdelivery_selectiondelivery_zonedemo_sessiondevicediscountdisputeemail_change_requestenvironment_grantfileflint_walletflint_wallet_cardfraud_warningfulfillmentfulfillment_eventfulfillment_notificationgift_cardgift_card_funding_dispositiongift_card_loadgift_card_notificationgift_card_redemptiongift_card_transactionimageinventory_adjustmentinventory_allocation_policyinventory_allocation_policy_revisioninventory_countinventory_iteminventory_levelinventory_movementinventory_receiptinventory_reservationinventory_reservation_lineinventory_transferinventory_transfer_lineinvoiceinvoice_delivery_attemptinvoice_late_feeinvoice_line_iteminvoice_manual_paymentinvoice_payment_attemptinvoice_payment_termlocationmerchantmerchant_billing_balancemerchant_billing_entrymerchant_billing_invoicemerchant_signupmodifiermodifier_groupmodifier_setorderorder_chargeorder_editorder_line_itemorder_line_item_modifierorder_payment_attemptpackagepackage_itempartner_apppartner_app_credentialpartner_app_installpayment_intentpayment_linkpayment_link_custom_fieldpayment_link_line_itempayment_methodpayment_method_domainpayment_reviewpayment_splitpayoutpayout_destinationpayout_settingsplatform_feeplatform_fee_balance_transactionplatform_fee_payoutprice_listprice_list_priceproductproduct_optionproduct_option_valueproduct_variantpromotionpromotion_codepurchase_refund_allocationreaderrefundrefund_allocationrefund_line_item_adjustmentremembered_buyerreportreport_downloadreturnreturn_activityreturn_dispositionreturn_inspectionreturn_inspection_line_itemreturn_line_itemreturn_policyreturn_policy_revisionreturn_reasonreturn_receiptreturn_receipt_line_itemreturn_resolutionrisk_listrisk_list_itemrisk_rulesandboxsettingsshipmentsubscriptionsubscription_delivery_migrationsubscription_line_itemsubscription_offersubscription_payment_retrysubscription_plansubscription_plan_line_itemtax_calculation_callbacktax_connectiontax_registrationtest_clockticketuserwebhook_deliverywebhook_endpointwebhook_eventworkload_identity
statusenumRequiredWhether the amount counts toward available_money yet.
pendingavailable
typeenumRequiredWhat the entry records. Can gain values; treat an unknown value as other.
platform_feereserve_holdreserve_releaseloss_coverageloss_coverage_reversalplatform_fee_refundplatform_fee_refund_reversalplatform_fee_payoutplatform_fee_payout_reversalother
{
"amount_money": {
"amount": 150,
"currency": "USD"
},
"available_at": "2026-11-10T00:00:00Z",
"created_at": "2026-11-09T21:14:05Z",
"occurred_at": "2026-11-09T21:14:03Z",
"partner_app_id": "papp_01KEZF7C00D8DXK5AXR7NPRJ0J",
"platform_fee_balance_transaction_id": "pfbt_01KEZF7C00E51WR2KQN2489YGZ",
"platform_fee_id": "pfee_01KF2M8W5C9T3B7Q1H4N6R2D0V",
"related_balance_transaction_ids": [],
"status": "available",
"type": "platform_fee"
}The Platform fee payout object#
A payout from your partner app's platform fee balance to your merchant balance. Owned by the merchant that owns the partner app.
Returned by GET /v1/platform-fee-payouts/{platform_fee_payout_id} and carried by the endpoints below.
Attributes
amount_moneyobjectRequiredThe amount transferred to your merchant balance.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
balance_transaction_idstringThe credit on your merchant ledger. Present once Flint observes it; linking it sends no payout event and doesn't advance version.
created_atstringRequiredWhen Flint prepared the payout.
failure_reasonenumWhy the payout failed. Present only when status is failed. Can gain values; treat unknown values as payout_failed.
merchant_cannot_receivepayout_failed
partner_app_idstringRequiredThe partner app whose fee balance funded the payout.
platform_fee_payout_idstringRequiredUnique identifier for the platform fee payout.
statusenumRequiredWhere the payout stands. succeeded and failed are final.
pendingsucceededfailed
succeeded_atstringWhen the transfer succeeded. Present only when status is succeeded.
updated_atstringRequiredWhen the payout's owned state last changed. Retry bookkeeping and observing the credit don't change it.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
{
"amount_money": {
"amount": 120,
"currency": "USD"
},
"balance_transaction_id": "btxn_01KF2P5A7S9D1F3G5H7J9K1M3Z",
"created_at": "2026-11-10T15:00:04Z",
"partner_app_id": "papp_01KEZF7C00D8DXK5AXR7NPRJ0J",
"platform_fee_payout_id": "pfpo_01KF2P4Q6W8E0R2T4Y6V8H0Z2P",
"status": "succeeded",
"succeeded_at": "2026-11-10T15:00:06Z",
"updated_at": "2026-11-10T15:00:06Z",
"version": 2
}List platform fee balance transactions#
/v1/platform-fee-balance-transactionsRequires scope money_movement.platform_fees.read
Rate limit: read
Lists your partner apps' platform fee ledger, newest occurred_at first, then by platform_fee_balance_transaction_id. Reads the merchant that owns the partner app, with its own credentials and money_movement.platform_fees.read; partner app tokens can't. Live records are in your live environment. Test records are in your default sandbox at the time the payment was created. A merchant that owns no partner app gets an empty list. Default order: occurred_at descending, then platform_fee_balance_transaction_id descending.
Query parameters
page_sizeintegerMaximum number of results to return, from 1 to 100. Defaults to 20.
page_tokenstringOpaque, signed next_page_token from the previous response, bound to the list and caller. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An altered, invalid, expired, or mismatched token returns a validation error.
partner_app_idstringExact match on the partner app.
platform_fee_idstringExact match on the fee the entry concerns.
platform_fee_payout_idstringExact match on the payout that carried the entry.
typearray of enumTypes to include. Omit it to list every type. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.
platform_feereserve_holdreserve_releaseloss_coverageloss_coverage_reversalplatform_fee_refundplatform_fee_refund_reversalplatform_fee_payoutplatform_fee_payout_reversal
occurred_afterstringInclusive lower bound on occurred_at.
occurred_beforestringExclusive upper bound on occurred_at.
Response · 200
A page of platform fee balance transactions.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
amount_moneyobjectRequiredThe signed effect on available_money plus pending_money: positive for money in, negative for money out.
available_atstringWhen the entry becomes, or became, available. Absent while Flint hasn't verified the application fee that carries it.
created_atstringRequiredWhen Flint recorded the entry.
descriptionstringDisplay text, not for matching.
occurred_atstringRequiredWhen the movement happened.
partner_app_idstringRequiredThe partner app the entry belongs to.
platform_fee_balance_transaction_idstringRequiredUnique identifier for the balance transaction.
platform_fee_idstringThe fee the entry concerns, when it concerns one.
platform_fee_payout_idstringThe payout that carried the entry. Set once when a payout is prepared, and never changed.
related_balance_transaction_idsarray of stringRequiredEarlier entries this one is linked to. Empty when none.
related_resourceobjectThe Flint resource behind the entry, when it has one other than the fee.
statusenumRequiredWhether the amount counts toward available_money yet.
pendingavailable
typeenumRequiredWhat the entry records. Can gain values; treat an unknown value as other.
platform_feereserve_holdreserve_releaseloss_coverageloss_coverage_reversalplatform_fee_refundplatform_fee_refund_reversalplatform_fee_payoutplatform_fee_payout_reversalother
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
next_page_tokenstringOpaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/platform-fee-balance-transactions \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"A page of platform fee balance transactions.
{
"data": [
{
"amount_money": {
"amount": 150,
"currency": "USD"
},
"available_at": "2026-11-10T00:00:00Z",
"created_at": "2026-11-09T21:14:05Z",
"occurred_at": "2026-11-09T21:14:03Z",
"partner_app_id": "papp_01KEZF7C00D8DXK5AXR7NPRJ0J",
"platform_fee_balance_transaction_id": "pfbt_01KEZF7C00E51WR2KQN2489YGZ",
"platform_fee_id": "pfee_01KF2M8W5C9T3B7Q1H4N6R2D0V",
"related_balance_transaction_ids": [],
"status": "available",
"type": "platform_fee"
}
],
"meta": {
"api_version": "2026-09-07"
},
"next_page_token": "opaque-next-page-token",
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Get a platform fee balance transaction#
/v1/platform-fee-balance-transactions/{platform_fee_balance_transaction_id}Requires scope money_movement.platform_fees.read
Rate limit: read
Returns one entry of your partner apps' platform fee ledger. Reads the merchant that owns the partner app, with its own credentials and money_movement.platform_fees.read; partner app tokens can't. Live records are in your live environment. Test records are in your default sandbox at the time the payment was created. A merchant that owns no partner app gets an empty list.
Path parameters
platform_fee_balance_transaction_idstringRequiredFlint platform fee balance transaction ID. Must be a valid ID with prefix pfbt_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Response · 200
The platform fee balance transaction.
dataobjectRequiredResource, collection, or operation result returned by this request.
amount_moneyobjectRequiredThe signed effect on available_money plus pending_money: positive for money in, negative for money out.
available_atstringWhen the entry becomes, or became, available. Absent while Flint hasn't verified the application fee that carries it.
created_atstringRequiredWhen Flint recorded the entry.
descriptionstringDisplay text, not for matching.
occurred_atstringRequiredWhen the movement happened.
partner_app_idstringRequiredThe partner app the entry belongs to.
platform_fee_balance_transaction_idstringRequiredUnique identifier for the balance transaction.
platform_fee_idstringThe fee the entry concerns, when it concerns one.
platform_fee_payout_idstringThe payout that carried the entry. Set once when a payout is prepared, and never changed.
related_balance_transaction_idsarray of stringRequiredEarlier entries this one is linked to. Empty when none.
related_resourceobjectThe Flint resource behind the entry, when it has one other than the fee.
statusenumRequiredWhether the amount counts toward available_money yet.
pendingavailable
typeenumRequiredWhat the entry records. Can gain values; treat an unknown value as other.
platform_feereserve_holdreserve_releaseloss_coverageloss_coverage_reversalplatform_fee_refundplatform_fee_refund_reversalplatform_fee_payoutplatform_fee_payout_reversalother
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/platform-fee-balance-transactions/pfbt_01KEZF7C0079KPKMAHC7C60G1T \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"The platform fee balance transaction.
{
"data": {
"amount_money": {
"amount": 150,
"currency": "USD"
},
"available_at": "2026-11-10T00:00:00Z",
"created_at": "2026-11-09T21:14:05Z",
"occurred_at": "2026-11-09T21:14:03Z",
"partner_app_id": "papp_01KEZF7C00D8DXK5AXR7NPRJ0J",
"platform_fee_balance_transaction_id": "pfbt_01KEZF7C00E51WR2KQN2489YGZ",
"platform_fee_id": "pfee_01KF2M8W5C9T3B7Q1H4N6R2D0V",
"related_balance_transaction_ids": [],
"status": "available",
"type": "platform_fee"
},
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}List platform fee balances#
/v1/platform-fee-balancesRequires scope money_movement.platform_fees.read
Rate limit: read
Lists your partner apps' platform fee balances, one per partner app and currency, newest first. Reads the merchant that owns the partner app, with its own credentials and money_movement.platform_fees.read; partner app tokens can't. Live records are in your live environment. Test records are in your default sandbox at the time the payment was created. A merchant that owns no partner app gets an empty list. Default order: time Flint opened the balance (descending), then platform_fee_balance_id descending.
Query parameters
page_sizeintegerMaximum number of results to return, from 1 to 100. Defaults to 20.
page_tokenstringOpaque, signed next_page_token from the previous response, bound to the list and caller. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An altered, invalid, expired, or mismatched token returns a validation error.
partner_app_idstringExact match on the partner app.
currencystringExact match on the ISO 4217 currency code.
Response · 200
A page of platform fee balances.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
available_moneyobjectRequiredFees Flint holds as available funds, net of the reserve. It can be negative after a refund when the fee was paid out or its reserve was spent covering losses. Your next fees repay it. available_money plus pending_money equals the sum of amount_money over the app's balance transactions in this currency.
currencystringRequiredISO 4217 currency code of every amount on the balance.
next_payout_atstringThe next scheduled payout run. Absent until scheduled.
partner_app_idstringRequiredThe partner app the balance belongs to.
payouts_disabled_reasonenumWhy payouts wait. Present only when payouts_enabled is false. Can gain values.
platform_pausedmerchant_payouts_unavailable
payouts_enabledbooleanRequiredWhether your platform and merchant account can receive payouts. Flint deferring a run for cash safety doesn't disable payouts.
pending_moneyobjectRequiredFees Flint hasn't received as available funds yet, net of their reserve holds.
platform_fee_balance_idstringRequiredUnique identifier for the balance.
reserve_moneyobjectRequiredWhat Flint holds in your reserve now: reserve holds minus releases.
updated_atstringRequiredWhen the balance last changed.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
next_page_tokenstringOpaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/platform-fee-balances \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"A page of platform fee balances.
{
"data": [
{
"available_money": {
"amount": 120,
"currency": "USD"
},
"currency": "USD",
"partner_app_id": "papp_01KEZF7C00D8DXK5AXR7NPRJ0J",
"payouts_enabled": true,
"pending_money": {
"amount": 0,
"currency": "USD"
},
"platform_fee_balance_id": "pfbal_01KEZF7C00ATPP4FTPCX0YGSVR",
"reserve_money": {
"amount": 30,
"currency": "USD"
},
"updated_at": "2026-11-12T16:40:21Z"
}
],
"meta": {
"api_version": "2026-09-07"
},
"next_page_token": "opaque-next-page-token",
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}List platform fee payouts#
/v1/platform-fee-payoutsRequires scope money_movement.platform_fees.read
Rate limit: read
Lists payouts from your partner apps' fee balances to your merchant balance, newest first, then by platform_fee_payout_id. Reads the merchant that owns the partner app, with its own credentials and money_movement.platform_fees.read; partner app tokens can't. Live records are in your live environment. Test records are in your default sandbox at the time the payment was created. A merchant that owns no partner app gets an empty list. Default order: created_at descending, then platform_fee_payout_id descending.
Query parameters
page_sizeintegerMaximum number of results to return, from 1 to 100. Defaults to 20.
page_tokenstringOpaque, signed next_page_token from the previous response, bound to the list and caller. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An altered, invalid, expired, or mismatched token returns a validation error.
partner_app_idstringExact match on the partner app.
statusarray of enumStatuses to include. Omit it to list every status. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.
pendingsucceededfailed
created_afterstringInclusive lower bound on created_at.
created_beforestringExclusive upper bound on created_at.
Response · 200
A page of platform fee payouts.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
amount_moneyobjectRequiredThe amount transferred to your merchant balance.
balance_transaction_idstringThe credit on your merchant ledger. Present once Flint observes it; linking it sends no payout event and doesn't advance version.
created_atstringRequiredWhen Flint prepared the payout.
failure_reasonenumWhy the payout failed. Present only when status is failed. Can gain values; treat unknown values as payout_failed.
merchant_cannot_receivepayout_failed
partner_app_idstringRequiredThe partner app whose fee balance funded the payout.
platform_fee_payout_idstringRequiredUnique identifier for the platform fee payout.
statusenumRequiredWhere the payout stands. succeeded and failed are final.
pendingsucceededfailed
succeeded_atstringWhen the transfer succeeded. Present only when status is succeeded.
updated_atstringRequiredWhen the payout's owned state last changed. Retry bookkeeping and observing the credit don't change it.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
next_page_tokenstringOpaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/platform-fee-payouts \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"A page of platform fee payouts.
{
"data": [
{
"amount_money": {
"amount": 120,
"currency": "USD"
},
"balance_transaction_id": "btxn_01KF2P5A7S9D1F3G5H7J9K1M3Z",
"created_at": "2026-11-10T15:00:04Z",
"partner_app_id": "papp_01KEZF7C00D8DXK5AXR7NPRJ0J",
"platform_fee_payout_id": "pfpo_01KF2P4Q6W8E0R2T4Y6V8H0Z2P",
"status": "succeeded",
"succeeded_at": "2026-11-10T15:00:06Z",
"updated_at": "2026-11-10T15:00:06Z",
"version": 2
}
],
"meta": {
"api_version": "2026-09-07"
},
"next_page_token": "opaque-next-page-token",
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Get a platform fee payout#
/v1/platform-fee-payouts/{platform_fee_payout_id}Requires scope money_movement.platform_fees.read
Rate limit: read
Returns one platform fee payout. Reads the merchant that owns the partner app, with its own credentials and money_movement.platform_fees.read; partner app tokens can't. Live records are in your live environment. Test records are in your default sandbox at the time the payment was created. A merchant that owns no partner app gets an empty list.
Path parameters
platform_fee_payout_idstringRequiredFlint platform fee payout ID. Must be a valid ID with prefix pfpo_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Response · 200
The platform fee payout.
dataobjectRequiredResource, collection, or operation result returned by this request.
amount_moneyobjectRequiredThe amount transferred to your merchant balance.
balance_transaction_idstringThe credit on your merchant ledger. Present once Flint observes it; linking it sends no payout event and doesn't advance version.
created_atstringRequiredWhen Flint prepared the payout.
failure_reasonenumWhy the payout failed. Present only when status is failed. Can gain values; treat unknown values as payout_failed.
merchant_cannot_receivepayout_failed
partner_app_idstringRequiredThe partner app whose fee balance funded the payout.
platform_fee_payout_idstringRequiredUnique identifier for the platform fee payout.
statusenumRequiredWhere the payout stands. succeeded and failed are final.
pendingsucceededfailed
succeeded_atstringWhen the transfer succeeded. Present only when status is succeeded.
updated_atstringRequiredWhen the payout's owned state last changed. Retry bookkeeping and observing the credit don't change it.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/platform-fee-payouts/pfpo_01KEZF7C00H58B147FK286D4A4 \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"The platform fee payout.
{
"data": {
"amount_money": {
"amount": 120,
"currency": "USD"
},
"balance_transaction_id": "btxn_01KF2P5A7S9D1F3G5H7J9K1M3Z",
"created_at": "2026-11-10T15:00:04Z",
"partner_app_id": "papp_01KEZF7C00D8DXK5AXR7NPRJ0J",
"platform_fee_payout_id": "pfpo_01KF2P4Q6W8E0R2T4Y6V8H0Z2P",
"status": "succeeded",
"succeeded_at": "2026-11-10T15:00:06Z",
"updated_at": "2026-11-10T15:00:06Z",
"version": 2
},
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}List platform fees#
/v1/platform-feesRequires scope money_movement.platform_fees.read
Rate limit: read
Lists the platform fees your partner apps charged, newest first, then by platform_fee_id. Reads the merchant that owns the partner app, with its own credentials and money_movement.platform_fees.read; partner app tokens can't. Live records are in your live environment. Test records are in your default sandbox at the time the payment was created. A merchant that owns no partner app gets an empty list. Default order: created_at descending, then platform_fee_id descending.
Query parameters
page_sizeintegerMaximum number of results to return, from 1 to 100. Defaults to 20.
page_tokenstringOpaque, signed next_page_token from the previous response, bound to the list and caller. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An altered, invalid, expired, or mismatched token returns a validation error.
partner_app_idstringExact match on the partner app.
partner_app_install_idstringExact match on the install whose token created the payment.
merchant_idstringExact match on the installed merchant charged the fee.
payment_intent_idstringExact match on the payment the fee rides on.
statusarray of enumStatuses to include. Omit it to list every status. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.
pendingsucceededcanceled
created_afterstringInclusive lower bound on created_at.
created_beforestringExclusive upper bound on created_at.
Response · 200
A page of platform fees.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
amount_moneyobjectRequiredThe fee Flint will charge until the payment succeeds, then the fee charged. Flint lowers it at confirm and capture to fit the merchant's cap and Flint's own fees; 0 once canceled.
canceled_reasonenumWhy Flint collected no fee. Present only when status is canceled. Can gain values.
payment_not_completedinstall_revokedplatform_capability_inactiveuncollectible
checkout_session_idstringThe checkout session the payment came from. Absent when the fee was sent with the payment itself.
collected_atstringWhen Flint collected the fee with the payment. Absent unless status is succeeded.
created_atstringRequiredWhen the payment's create recorded the fee.
merchant_idstringRequiredThe installed merchant charged the fee, as on the install.
partner_app_idstringRequiredThe partner app that charged the fee.
partner_app_install_idstringRequiredThe install whose partner app token created the payment.
payment_intent_idstringRequiredThe payment the fee rides on, owned by the installed merchant. After that merchant resets the sandbox the payment was in, the ID no longer resolves.
platform_fee_idstringRequiredUnique identifier for the platform fee, the payment intent's platform_fee.platform_fee_id.
refunded_moneyobjectRequiredThe fee debited from the platform for returns so far, including opted-in payment refunds and returns of the whole application fee. Matches the platform ledger, including returns awaiting completion; reversals reduce the total. 0 when nothing has been debited.
requested_amount_moneyobjectRequiredThe fee the request asked for.
reserve_available_atstringThe original scheduled release date of the held share. Refunds can release their proportional share early. Absent until the fee posts, and when nothing was held. Setting it sends no event.
reserve_hold_moneyobjectThe share of the fee Flint held in your reserve when it posted the fee to your ledger. Absent until then. The original collection snapshot: refunds release their proportional share early, and loss coverage draws on the reserve as a whole. Read PlatformFeeBalance.reserve_money for what is held now. Setting it sends no event.
statusenumRequiredWhere the fee stands. canceled is final.
pendingsucceededcanceled
updated_atstringRequiredWhen the fee last changed.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
next_page_tokenstringOpaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/platform-fees \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"A page of platform fees.
{
"data": [
{
"amount_money": {
"amount": 150,
"currency": "USD"
},
"collected_at": "2026-11-09T21:14:03Z",
"created_at": "2026-11-09T21:13:40Z",
"merchant_id": "mer_01KEZF7C00MPP0T9S0KH5BB4CC",
"partner_app_id": "papp_01KEZF7C00D8DXK5AXR7NPRJ0J",
"partner_app_install_id": "pinst_01KEZG2H7Y4M8K3B6W9Q5T1R0C",
"payment_intent_id": "pi_01KF2M8V1Z6X4C8N2B5M7Q3W9E",
"platform_fee_id": "pfee_01KF2M8W5C9T3B7Q1H4N6R2D0V",
"refunded_money": {
"amount": 0,
"currency": "USD"
},
"requested_amount_money": {
"amount": 150,
"currency": "USD"
},
"reserve_available_at": "2027-03-10T00:00:00Z",
"reserve_hold_money": {
"amount": 30,
"currency": "USD"
},
"status": "succeeded",
"updated_at": "2026-11-09T21:14:03Z",
"version": 3
}
],
"meta": {
"api_version": "2026-09-07"
},
"next_page_token": "opaque-next-page-token",
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Get a platform fee#
/v1/platform-fees/{platform_fee_id}Requires scope money_movement.platform_fees.read
Rate limit: read
Returns one platform fee. Reads the merchant that owns the partner app, with its own credentials and money_movement.platform_fees.read; partner app tokens can't. Live records are in your live environment. Test records are in your default sandbox at the time the payment was created. A merchant that owns no partner app gets an empty list.
Path parameters
platform_fee_idstringRequiredFlint platform fee ID. Must be a valid ID with prefix pfee_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Response · 200
The platform fee.
dataobjectRequiredResource, collection, or operation result returned by this request.
amount_moneyobjectRequiredThe fee Flint will charge until the payment succeeds, then the fee charged. Flint lowers it at confirm and capture to fit the merchant's cap and Flint's own fees; 0 once canceled.
canceled_reasonenumWhy Flint collected no fee. Present only when status is canceled. Can gain values.
payment_not_completedinstall_revokedplatform_capability_inactiveuncollectible
checkout_session_idstringThe checkout session the payment came from. Absent when the fee was sent with the payment itself.
collected_atstringWhen Flint collected the fee with the payment. Absent unless status is succeeded.
created_atstringRequiredWhen the payment's create recorded the fee.
merchant_idstringRequiredThe installed merchant charged the fee, as on the install.
partner_app_idstringRequiredThe partner app that charged the fee.
partner_app_install_idstringRequiredThe install whose partner app token created the payment.
payment_intent_idstringRequiredThe payment the fee rides on, owned by the installed merchant. After that merchant resets the sandbox the payment was in, the ID no longer resolves.
platform_fee_idstringRequiredUnique identifier for the platform fee, the payment intent's platform_fee.platform_fee_id.
refunded_moneyobjectRequiredThe fee debited from the platform for returns so far, including opted-in payment refunds and returns of the whole application fee. Matches the platform ledger, including returns awaiting completion; reversals reduce the total. 0 when nothing has been debited.
requested_amount_moneyobjectRequiredThe fee the request asked for.
reserve_available_atstringThe original scheduled release date of the held share. Refunds can release their proportional share early. Absent until the fee posts, and when nothing was held. Setting it sends no event.
reserve_hold_moneyobjectThe share of the fee Flint held in your reserve when it posted the fee to your ledger. Absent until then. The original collection snapshot: refunds release their proportional share early, and loss coverage draws on the reserve as a whole. Read PlatformFeeBalance.reserve_money for what is held now. Setting it sends no event.
statusenumRequiredWhere the fee stands. canceled is final.
pendingsucceededcanceled
updated_atstringRequiredWhen the fee last changed.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/platform-fees/pfee_01KEZF7C00JHAZN19B3MMW0R3A \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"The platform fee.
{
"data": {
"amount_money": {
"amount": 150,
"currency": "USD"
},
"collected_at": "2026-11-09T21:14:03Z",
"created_at": "2026-11-09T21:13:40Z",
"merchant_id": "mer_01KEZF7C00MPP0T9S0KH5BB4CC",
"partner_app_id": "papp_01KEZF7C00D8DXK5AXR7NPRJ0J",
"partner_app_install_id": "pinst_01KEZG2H7Y4M8K3B6W9Q5T1R0C",
"payment_intent_id": "pi_01KF2M8V1Z6X4C8N2B5M7Q3W9E",
"platform_fee_id": "pfee_01KF2M8W5C9T3B7Q1H4N6R2D0V",
"refunded_money": {
"amount": 0,
"currency": "USD"
},
"requested_amount_money": {
"amount": 150,
"currency": "USD"
},
"reserve_available_at": "2027-03-10T00:00:00Z",
"reserve_hold_money": {
"amount": 30,
"currency": "USD"
},
"status": "succeeded",
"updated_at": "2026-11-09T21:14:03Z",
"version": 3
},
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Was this helpful?