Skip to content
  • 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.

statusMeaning
pendingThe 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.
succeededFlint collected the fee with the payment.
canceledFinal. 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_money is what Flint holds for you as available funds. It can be negative when a returned fee is owed back from your next fees.
  • pending_money is 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_money is 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_money plus pending_money always equals the sum of amount_money over 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.

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

statusMeaning
pendingFlint is sending the payout.
succeededFlint transferred the amount to your merchant balance. succeeded_at records when.
failedFinal. 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:

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_moneyobjectRequired

The 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_reasonenum

Why Flint collected no fee. Present only when status is canceled. Can gain values.

  • payment_not_completed
  • install_revoked
  • platform_capability_inactive
  • uncollectible
checkout_session_idstring

The checkout session the payment came from. Absent when the fee was sent with the payment itself.

collected_atstring

When Flint collected the fee with the payment. Absent unless status is succeeded.

created_atstringRequired

When the payment's create recorded the fee.

merchant_idstringRequired

The installed merchant charged the fee, as on the install.

partner_app_idstringRequired

The partner app that charged the fee.

partner_app_install_idstringRequired

The install whose partner app token created the payment.

payment_intent_idstringRequired

The 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_idstringRequired

Unique identifier for the platform fee, the payment intent's platform_fee.platform_fee_id.

refunded_moneyobjectRequired

The 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_moneyobjectRequired

The fee the request asked for.

reserve_available_atstring

The 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_moneyobject

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

statusenumRequired

Where the fee stands. canceled is final.

  • pending
  • succeeded
  • canceled
updated_atstringRequired

When the fee last changed.

versionintegerRequired

Persisted version of this resource's owned state. Expanded resources and external observations can change independently.

JSON
{
  "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_moneyobjectRequired

The signed effect on available_money plus pending_money: positive for money in, negative for money out.

available_atstring

When the entry becomes, or became, available. Absent while Flint hasn't verified the application fee that carries it.

created_atstringRequired

When Flint recorded the entry.

descriptionstring

Display text, not for matching.

occurred_atstringRequired

When the movement happened.

partner_app_idstringRequired

The partner app the entry belongs to.

platform_fee_balance_transaction_idstringRequired

Unique identifier for the balance transaction.

platform_fee_idstring

The fee the entry concerns, when it concerns one.

platform_fee_payout_idstring

The payout that carried the entry. Set once when a payout is prepared, and never changed.

related_balance_transaction_idsarray of stringRequired

Earlier entries this one is linked to. Empty when none.

related_resourceobject

The Flint resource behind the entry, when it has one other than the fee.

statusenumRequired

Whether the amount counts toward available_money yet.

  • pending
  • available
typeenumRequired

What the entry records. Can gain values; treat an unknown value as other.

  • platform_fee
  • reserve_hold
  • reserve_release
  • loss_coverage
  • loss_coverage_reversal
  • platform_fee_refund
  • platform_fee_refund_reversal
  • platform_fee_payout
  • platform_fee_payout_reversal
  • other
JSON
{
  "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_moneyobjectRequired

The amount transferred to your merchant balance.

balance_transaction_idstring

The credit on your merchant ledger. Present once Flint observes it; linking it sends no payout event and doesn't advance version.

created_atstringRequired

When Flint prepared the payout.

failure_reasonenum

Why the payout failed. Present only when status is failed. Can gain values; treat unknown values as payout_failed.

  • merchant_cannot_receive
  • payout_failed
partner_app_idstringRequired

The partner app whose fee balance funded the payout.

platform_fee_payout_idstringRequired

Unique identifier for the platform fee payout.

statusenumRequired

Where the payout stands. succeeded and failed are final.

  • pending
  • succeeded
  • failed
succeeded_atstring

When the transfer succeeded. Present only when status is succeeded.

updated_atstringRequired

When the payout's owned state last changed. Retry bookkeeping and observing the credit don't change it.

versionintegerRequired

Persisted version of this resource's owned state. Expanded resources and external observations can change independently.

JSON
{
  "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#

GET/v1/platform-fee-balance-transactions

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

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque, 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_idstring

Exact match on the partner app.

platform_fee_idstring

Exact match on the fee the entry concerns.

platform_fee_payout_idstring

Exact match on the payout that carried the entry.

typearray of enum

Types 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_fee
  • reserve_hold
  • reserve_release
  • loss_coverage
  • loss_coverage_reversal
  • platform_fee_refund
  • platform_fee_refund_reversal
  • platform_fee_payout
  • platform_fee_payout_reversal
occurred_afterstring

Inclusive lower bound on occurred_at.

occurred_beforestring

Exclusive upper bound on occurred_at.

Response · 200

A page of platform fee balance transactions.

dataarray of objectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

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

JSON
{
  "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#

GET/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_idstringRequired

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

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

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

JSON
{
  "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#

GET/v1/platform-fee-balances

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

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque, 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_idstring

Exact match on the partner app.

currencystring

Exact match on the ISO 4217 currency code.

Response · 200

A page of platform fee balances.

dataarray of objectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

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

JSON
{
  "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#

GET/v1/platform-fee-payouts

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

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque, 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_idstring

Exact match on the partner app.

statusarray of enum

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

  • pending
  • succeeded
  • failed
created_afterstring

Inclusive lower bound on created_at.

created_beforestring

Exclusive upper bound on created_at.

Response · 200

A page of platform fee payouts.

dataarray of objectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

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

JSON
{
  "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#

GET/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_idstringRequired

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

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

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

JSON
{
  "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#

GET/v1/platform-fees

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

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque, 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_idstring

Exact match on the partner app.

partner_app_install_idstring

Exact match on the install whose token created the payment.

merchant_idstring

Exact match on the installed merchant charged the fee.

payment_intent_idstring

Exact match on the payment the fee rides on.

statusarray of enum

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

  • pending
  • succeeded
  • canceled
created_afterstring

Inclusive lower bound on created_at.

created_beforestring

Exclusive upper bound on created_at.

Response · 200

A page of platform fees.

dataarray of objectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

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

JSON
{
  "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#

GET/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_idstringRequired

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

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

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

JSON
{
  "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?