Skip to content

Platform fees

A platform fee is the cut your partner app takes from a payment it creates for an installed merchant. The merchant pays it beside Flint's fees, it comes out of the payment, and Flint takes no share of it. Each payment carries the fee its own request asked for, and Flint never charges more than the platform fee cap the merchant approved when it installed your app.

For example, Classboard runs bookings for Tidewater Yoga. On a $100.00 class pass, Flint's card fee is $4.14 at the published rate of 3.79% + 35¢, and Classboard's platform fee is $1.50. Tidewater nets $94.36.

  • POST/v1/payment-intentsRequired API key scope: payments.payment_intents.writeReference for POST /v1/payment-intents

    Create an order's payment with a platform fee.

  • POST/v1/payment-intentsRequired API key scope: payments.payment_intents.writeReference for POST /v1/payment-intents

    Create a standalone payment with a platform fee.

  • POST/v1/orders/{order_id}/payRequired API key scope: commerce.orders.writeReference for POST /v1/orders/{order_id}/pay

    Pay an order with action: pay and a platform fee.

  • POST/v1/checkout-sessionsRequired API key scopes: checkouts.checkout_sessions.write, commerce.invoices.write or commerce.returns.resolutions.writeReference for POST /v1/checkout-sessions

    Open a checkout session whose payment carries a platform fee.

  • POST/v1/payment-intents/{payment_intent_id}/captureRequired API key scope: payments.payment_intents.writeReference for POST /v1/payment-intents/{payment_intent_id}/capture

    Set or change the fee when you capture a standalone payment.

Before you charge a fee#

  • A cap on your app. Set platform_fee_cap on your partner app. Merchants see it on the consent screen beside your permissions.
  • The merchant's approval. A merchant approves your cap when it installs your app, separately for test and live. The environment grant's platform_fee_cap shows what it approved. A merchant that installed before you set or raised the cap must authorize again to approve it.
  • Live mode needs an approved platform. In live mode, your app's platform_fees capability must be active, which takes Flint's review and your acceptance of the Flint Platform Agreement. See Become an approved platform. Test mode never checks it, so you can build and test fees before you apply.
  • A partner app token. Only requests made with a partner app token can carry a fee. Your own API key and the dashboard can't, and neither can the merchant's credentials.

Charge a fee#

Send platform_fee.amount_money with the request that creates the payment. The amount is a fixed fee of at least 1 minor unit, in the payment's currency. To charge no fee, omit platform_fee. If your pricing is a percentage, compute the amount yourself.

cURL
curl -X POST https://api.withflintpay.com/v1/payment-intents \
  -H "Authorization: Bearer PARTNER_APP_TOKEN" \
  -H "Flint-Merchant-Id: mer_01KEZF7C00MPP0T9S0KH5BB4CC" \
  -H "Idempotency-Key: classboard-pass-4410" \
  -H "Content-Type: application/json" \
  -d '{"order_id": "ORDER_ID",
    "amount_money": {"amount": 10000, "currency": "USD"},
    "payment_options": ["card"],
    "platform_fee": {"amount_money": {"amount": 150, "currency": "USD"}}
  }'

The payment intent comes back with the fee:

JSON
"platform_fee": {
  "platform_fee_id": "pfee_01KF2M8W5C9T3B7Q1H4N6R2D0V",
  "partner_app_id": "papp_01KEZF7C00D8DXK5AXR7NPRJ0J",
  "amount_money": {"amount": 150, "currency": "USD"},
  "refunded_money": {"amount": 0, "currency": "USD"}
}

platform_fee is part of the request's idempotency fingerprint: a retry with the same Idempotency-Key must send the same fee.

Which requests accept a fee#

RequestAccepts platform_fee
POST /v1/payment-intentsYes
POST /v1/payment-intents with order_idYes, unless the order starts or renews a subscription.
POST /v1/orders/{order_id}/pay with action: payYes, unless the order starts or renews a subscription. The fee rides on the processor payment pay creates. A pay that gift cards or a zero balance settle creates none and charges no fee. The other actions confirm or resume payments that already carry their fee, or none, so they don't accept one.
POST /v1/checkout-sessions with type order or quick_payYes, unless the order has a subscribed line. See Checkout sessions.
POST /v1/checkout-sessions with type subscription_planNo. Renewals are created by Flint's billing, not by your request.
POST /v1/payment-intents/{payment_intent_id}/captureYes, on a standalone payment your app created. See Set the fee at capture. Not yet on a payment that belongs to an order.
Payment links, invoices, and subscriptionsNo. An order whose payment starts or renews a subscription, such as a plan's signup order or a cart with a subscribed line, doesn't accept one either, because Flint's billing creates the renewals.

Checks when you create the payment#

Flint checks the fee in this order and creates nothing when one fails:

CheckError
The request uses a partner app token.400 INVALID_REQUEST with NOT_ALLOWED on platform_fee
amount_money.amount is at least 1.400 INVALID_REQUEST with INVALID_VALUE on platform_fee.amount_money.amount
The fee is in the payment's currency.400 INVALID_REQUEST with INVALID_VALUE on platform_fee.amount_money
The request accepts a fee, so it doesn't start or renew a subscription, and the merchant isn't your app's own merchant.400 INVALID_REQUEST with NOT_ALLOWED on platform_fee
The merchant approved a cap in this currency for this mode.409 ACTION_NOT_ALLOWED with reason platform_fee_consent_required and resource_type environment_grant. Send the merchant through authorization again.
In live mode, your app's platform_fees capability is active.409 ACTION_NOT_ALLOWED with resource_type partner_app, capability platform_fees, and the reason your platform status gives: platform_onboarding_required, platform_pending_review, platform_rejected, or platform_capability_inactive.
The fee is at most the cap for the payment's amount.400 INVALID_REQUEST with INVALID_VALUE on platform_fee.amount_money, and the largest fee allowed in details[0].maximum_money
The fee is below the payment's amount.The same, with maximum_money one minor unit below the amount

Your app's platform limits never refuse a fee. They're soft: crossing one alerts Flint staff, who may limit or pause your app.

Readers#

platform_fee works on payments taken on a reader as it does online: when you create the payment, and with pay and a reader. Presenting the payment on the reader is its confirmation, so Flint prices the fee again then and again at capture. A tip the buyer picks on the reader raises the amount the cap is figured on.

Set the fee at capture#

When you authorize first and capture later, for example a restaurant bill with a tip, you may not know your fee until the final amount. Send platform_fee with the capture of a payment your app created:

cURL
curl -X POST https://api.withflintpay.com/v1/payment-intents/PAYMENT_INTENT_ID/capture \
  -H "Authorization: Bearer PARTNER_APP_TOKEN" \
  -H "Flint-Merchant-Id: mer_01KEZF7C00MPP0T9S0KH5BB4CC" \
  -H "Idempotency-Key: capture-table-6-0412" \
  -H "Content-Type: application/json" \
  -d '{
    "final_amount_money": {"amount": 6200, "currency": "USD"},
    "tip_money": {"amount": 1200, "currency": "USD"},
    "platform_fee": {"amount_money": {"amount": 104, "currency": "USD"}}
  }'
  • It replaces the fee the payment was created with, or adds one if it had none.
  • Flint runs the same checks as at create, except the cap: only the partner app token that created the payment can send it, and the merchant's approval and, in live mode, your capability must still hold. A fee that already ended returns 409 ACTION_NOT_ALLOWED with reason terminal_status.
  • The cap and Flint's fees apply to the captured total, bill plus tip, and lower the fee rather than refuse the capture. With a cap of 1% + $0.30, the $74.00 capture above allows $1.04.
  • platform_fee is part of the capture's idempotency fingerprint.
  • A payment that belongs to an order doesn't accept it at capture yet: 400 INVALID_REQUEST with NOT_ALLOWED on platform_fee. Set the fee when you create the order's payment.

What Flint charges#

Flint's own fees are only known once the buyer picks a payment option, and the amount collected can change, for example with a partial capture or a tip. So at confirm and again at capture, Flint prices your fee again before the payment processor sees it:

  • The cap. The fee is lowered to the merchant's current cap for the amount being collected.
  • Flint's fees come first. If Flint's processing and add-on fees plus your fee would reach the amount collected, your fee is lowered so the merchant keeps at least one minor unit.
  • Consent and capability. If the merchant revoked the install or removed your cap, or, in live mode, your platform_fees capability is no longer active, the payment goes ahead without the fee.

A buyer's payment never fails because of your fee. platform_fee.amount_money on the payment intent is the fee Flint will charge until the payment succeeds, then the fee it charged. It is 0 when Flint canceled the fee: when nothing was left to charge, when consent or the capability is gone, or when the payment ended without succeeding.

What the merchant sees#

The merchant reads the fee on the same payment intent, with its own credentials:

FieldWhat it holds
processing_fee_money and add_on_feesFlint's fees only. They never include your fee.
platform_feeYour fee, its platform_fee_id, and your partner_app_id. Buyers and checkout credentials never see it.
merchant_net_moneycaptured_money minus Flint's fees and platform_fee.amount_money.

On the merchant's balance, the payment's payment balance transaction has fee_money equal to Flint's fees plus yours, so its net_money still equals the payment's merchant_net_money. The payments_itemized_v1 report has a platform_fee_money column, and its merchant_net_money subtracts it.

The merchant's payment_intent.succeeded, payment_intent.canceled, and payment_intent.expired events carry platform_fee as it stands then. Your own platform_fee.* events report every change to the fee; see See what you earned.

Checkout sessions#

Send platform_fee when you create a session of type order or quick_pay. Flint checks it once against the session's total. The session's platform_fee shows the fee you requested; buyers never see it.

Each payment the session creates carries its own platform_fee, lowered to the cap for that payment's amount, and Flint prices it again at confirm and capture. A session collects at most one processor payment, so at most one fee succeeds per session. A session that expires, or a gift card that covers the whole order, leaves no processor payment and no fee.

If an open checkout changes from a one-time purchase to a subscription, its payments carry no platform fee. Flint cancels a fee already recorded on an unpaid payment as uncollectible before confirm or capture. The buyer can still pay for the subscription.

Refunds and disputes#

Your fee stays by default when the merchant refunds the payment. To return it, create the refund with your partner app token and refund_platform_fee: true:

JSON
{
  "refund_type": "amount",
  "payment_intent_id": "pi_01KF2M8W5C9T3B7Q1H4N6R2D0V",
  "amount_money": {"amount": 4000, "currency": "USD"},
  "refund_platform_fee": true
}

Send this body to POST /v1/refunds with an Idempotency-Key and the installed merchant's Flint-Merchant-Id. Only the app that charged a payment's fee can return it. Another app, the merchant's credentials, and your own API key receive 400 INVALID_REQUEST with NOT_ALLOWED at refund_platform_fee. Payments without a fee refund normally, and the refund still echoes refund_platform_fee: true. The credit_note refund type doesn't accept the field.

A refund of a whole captured payment returns the whole unreturned fee. A partial refund returns the fee multiplied by the refunded amount divided by the captured amount, rounded half up and capped at the fee left. In the example above, $40.00 of a $100.00 payment returns $0.60 of its $1.50 fee. If every earlier refund also returned its fee share, the refund that finishes the payment returns any cent left by rounding.

Refund.refund_platform_fee echoes your choice on creates, reads, lists, and events. Each payment_refunds[].refunded_platform_fee_money shows the share to return once that payment refund succeeds, or zero when you kept the fee; it is absent on payments without a collected fee. Buyers see neither field. The payment intent's platform_fee.refunded_money and the owner's PlatformFee.refunded_money match the refund debits in your platform ledger, less any reversals. They include returns awaiting completion.

The merchant receives a platform_fee_refund balance transaction linked to the refund and the payment's balance transaction. Your ledger debits the share with the same type as soon as the refund reserves it. The debit takes the fee's status and available_at: it reduces pending fees while the fee is pending, then available fees once the funds are available. A linked reserve_release returns the proportional share of the fee's remaining hold in the same status. The cumulative reserve share is rounded half up, so returning the whole fee releases its remaining hold; amounts already released or used to cover losses cannot be released again. A canceled or failed return credits platform_fee_refund_reversal and restores its reserve share with reserve_hold; a refund that fails after the fee was returned also reverses your debit and the fee's refunded total, while the merchant keeps the money already returned. If your fee was already paid out, the returned share comes out of your next fees and can make available_money negative. reserve_hold_money and reserve_available_at remain the original collection snapshot; PlatformFeeBalance.reserve_money shows the current reserve. Flint's own fee stays in place.

Disputes never return your fee, whatever their outcome.

See what you earned#

Read your fees, balances, and ledger with your own merchant's credentials and money_movement.platform_fees.read, not with a partner app token:

cURL
curl "https://api.withflintpay.com/v1/platform-fees?partner_app_id=papp_01KEZF7C00D8DXK5AXR7NPRJ0J&status=succeeded" \
  -H "Authorization: Bearer YOUR_LIVE_API_KEY"
  • GET /v1/platform-fees lists each fee with what the request asked for, what Flint charged, and the share held in your reserve.
  • GET /v1/platform-fee-balances shows, per partner app and currency, what is available, what is pending until Flint's own funds are available, and what is held in reserve.
  • GET /v1/platform-fee-balance-transactions lists every movement of a balance.

Flint holds 20% of each fee in a reserve by default, released at 00:00 UTC 120 days after the end of the UTC day the fee was collected, so a platform's fees cover its merchants' unrecovered losses first. The Flint Platform Agreement sets out the reserve, the order losses are covered in, and what a pause holds. The fee events platform_fee.created, platform_fee.updated, platform_fee.succeeded, and platform_fee.canceled go to your own merchant's webhook endpoints. See Platform fees in the API reference.

Receive your fees#

Flint pays available fees to your own merchant balance daily at 15:00 UTC, with a $1.00 minimum. Test payouts run hourly with a one-cent minimum. Your own merchant payouts then send that balance to your bank.

Read GET /v1/platform-fee-payouts?partner_app_id=YOUR_PARTNER_APP_ID to follow payouts, and GET /v1/platform-fee-payouts/{platform_fee_payout_id} for one. A payout is pending, then succeeded or failed. A failed payout returns its amount to your platform fee balance. Its failure_reason says why.

Your balance's payouts_enabled, payouts_disabled_reason, and next_payout_at show whether payouts can run and when the next run is scheduled. Each ledger entry's platform_fee_payout_id shows which payout carried it. On your merchant ledger, the credit is platform_fee_payout, and a transfer reversal is platform_fee_payout_reversal.

Subscribe to platform_fee_payout.created, platform_fee_payout.succeeded, and platform_fee_payout.failed on your own merchant endpoints. Once Flint observes the merchant credit, balance_transaction_id links to it without another payout event. See Platform fees for filters and reconciliation fields.

Test mode#

Fees, consent, and caps work in test mode as in live, without Flint's review. Use a test partner app token, a merchant that approved your cap in test mode, and the test cards. Each test fee belongs to your own merchant's default sandbox at the time you created the payment or checkout session.

  • Test reserves release sooner. The reserve releases one day after the end of the UTC day the fee was collected. A fee collected on November 16 releases its reserve at November 18, 00:00 UTC. Read reserve_available_at for the exact time. Live reserves use the platform's agreed terms, normally 120 days.
  • The installed merchant resets its sandbox. Its test payments are deleted. Flint cancels each fee still pending on them with canceled_reason payment_not_completed. Fees already collected stay in your ledger, and their payment_intent_id no longer resolves.
  • Your own default sandbox holds your test fees. A default sandbox can't be reset, so your test fees, balances, and ledger stay.

Was this helpful?