docs(payouts): document platform-assessed fees

[ls-bolt]

Summary

• New docs page for platform-assessed fees — the fee a platform configures and collects from its own customers, credited to the platform's own internal account. This is distinct from the fees Grid charges the platform.
• Covers six topics: what can be charged, how to configure it, when fees are assessed, which webhooks carry them, how to query transactions and revenue, and how to test in sandbox.
• Added to the Payouts & B2B → Sending payments nav group, between Send Payment and List Transactions.

Approach

Written against the shipped API contract in this repo — FeeConfig, FeeType, PlatformFeeOverride, Quote.platformFeesIncluded, OutgoingTransaction.platformFees, and PlatformConfigUpdateRequest.feeConfigs — and against the current server behavior, so the page documents what the API does today rather than what was proposed. The worked example (30 bps + $0.50 on a $10.00 payment = 53 cents) is taken from an existing end-to-end test of this path.

Two points where the page deliberately documents current behavior, both raised with the feature owner for confirmation before publishing:

• Per-transaction overrides are uncapped. PlatformFeeOverride replaces any configured platform fee with no ceiling relative to it, and an override is accepted even when no standing config exists. The page describes it that way.
• No per-fee breakdown endpoint. Fee detail is documented as platformFees on the transaction object, since no dedicated fee-listing endpoint exists in the spec.

The page also notes that platform fees are not yet supported on every payment flow, and that an affected quote is rejected at creation rather than failing at settlement, without enumerating flows — that list is still changing.

Revision 2 — review feedback

Four corrections, three from reviewer feedback on the fee mechanics and one caught by an automated review pass:

• Fee credit timing. The page previously said the fee is credited when the transaction reaches COMPLETED. It is credited as one step of settlement and can land earlier, so a refund after that point reverses the credit — pulling the fee back out of the platform account and returning it to the customer. Now documented, with the guidance to treat a fee as earned only at COMPLETED, and the accrued-balance and webhook sections reworded to match.
• Grid fee interaction. "Grid's fees are unchanged by anything you configure here" was too strong. Grid's rates don't change, but its variable fee is proportional to the sending amount — so on a receiving-locked quote a platform fee raises the sending amount and the absolute amount Grid takes rises with it.
• Fee formula. Added the combined calculation explicitly: total_variable_fee = (sending_amount - platform_fixed_fee - grid_fixed_fee) x (platform_variable_fee + grid_variable_fee). The worked example now shows Grid's fixed fee in the subtraction.
• Which side absorbs the fee. "Deducted from what the recipient gets" was only true for sending-locked quotes. Now split by lockedCurrencySide: lock sending and the recipient receives less; lock receiving and the sender pays more.

Revision 3 — Greptile review + remaining feedback

Fixed — inconsistent quote example (Greptile P1, valid). The quote response showed
totalSendingAmount: 10000 while carrying the 53-cent fee computed for a 1,000-cent send,
so the figures didn't reproduce. The block is now internally consistent at the 1,000-cent
send (totalReceivingAmount: 863, feesIncluded: 63), with a lead-in tying it back to the
worked calculation.

Fixed — two points from the earlier review that hadn't landed yet. A RAIL fee type
and stablecoin sending currencies (USDC) are now flagged as planned rather than implying
today's single fee type and USD-only limit are permanent; and the page now states that a fee
can only be charged when the platform holds an internal account in the transaction's sending
currency.

Fixed — two consistency issues from an automated review pass. The component table said
the variable fee applies to the sending amount, contradicting the formula section (it
applies after fixed fees); and a capability-discovery suggestion pointed at GET /config,
which returns active configs rather than supported types — now points at the changelog.

Declined — relative internal links (Greptile P2). Root-relative paths are this repo's
actual convention: 94 root-relative internal links across mintlify/**/*.mdx versus 2 using
../, including the neighbouring pages in this same nav group. mintlify/CLAUDE.md is
self-contradictory on this point, and its enforceable "Do not" line prohibits absolute URLs,
which /payouts-and-b2b/... is not. Converting only this page would make it the outlier;
reasoning is in the review thread.

Not a defect — receiving-amount arithmetic. An automated pass flagged
totalReceivingAmount: 863 as wrong, modelling it as (1000 - 63) x 0.92 = 862. The engine
subtracts fixed fees, applies the summed rate, then converts, rounding each component
independently — which yields 863. Verified against the pricing code; left as-is.

Verification

• Rendered locally with the pinned Mintlify CLI (4.2.284) after each revision; page, formula block, quote example, and sidebar entry all render correctly.
• Quote-example figures recomputed against the pricing engine's own rounding rules rather than by hand.
• mint broken-links reports no broken links from this page (the 24 it finds are pre-existing in other files).
• docs.json re-parsed as valid JSON.
• Caught while rendering: two $ characters on one line put the fee example into LaTeX math mode. Escaped as \$, matching the convention on existing pages.

make lint-markdown fails on main as well — it invokes an npm script that does not exist. Not touched here.

Changes: 2 files

• mintlify/payouts-and-b2b/payment-flow/assessing-fees.mdx — new page
• mintlify/docs.json — one nav entry

Requested by @pengying

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Grid	🟢 Ready	View Preview	Aug 13, 2026, 9:50 PM

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ready	Preview	Aug 15, 2026 6:27pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
grid-wallet-demo	Ignored	Preview	Aug 15, 2026 6:27pm

[lightspark-bot]

• docs(payouts): document platform-assessed fees #830 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[ls-bolt]

Live preview of the new page: https://ramps-08-13-grid-platform-assessed-fees-docs.mintlify.site/payouts-and-b2b/payment-flow/assessing-fees

CI is green and the hosted build renders all sections correctly.

[ls-bolt]

Pushed revision 2 with the fee-mechanics corrections — thanks, these were all substantive and two of them were things the page got wrong:

1. Fee credit timing. Corrected: the credit lands as a step of settlement rather than at COMPLETED, so a refund after that point reverses it back out of the platform account. I did go into detail, because the failure mode is a platform counting revenue that can still disappear — the page now says to treat a fee as earned only at COMPLETED, and calls out that balance updates fire in both directions. Happy to trim if it reads as too much.
2. Grid fee interaction. Fixed — the old wording overclaimed. Now: Grid's rates are unchanged, but since the variable fee is proportional to the sending amount, a platform fee on a receiving-locked quote raises the sending amount and Grid's absolute take with it.
3. Formula added verbatim, and the worked example now shows Grid's fixed fee in the subtraction.

An automated review pass also caught a fourth error of the same kind: I'd written that the fee is "deducted from what the recipient gets," which only holds for sending-locked quotes. Now split by lockedCurrencySide.

Re-rendered and verified after each change. Live preview: https://ramps-08-13-grid-platform-assessed-fees-docs.mintlify.site/payouts-and-b2b/payment-flow/assessing-fees

[greptile-apps]

Greptile Summary

The PR adds a public guide explaining how platforms configure, assess, reconcile, and test platform fees, and adds it to the Payouts & B2B navigation.

• Documents standing fee configuration and per-transaction overrides.
• Explains pricing, settlement, refunds, webhooks, and revenue reconciliation.
• Adds sandbox validation guidance and links to related documentation.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
mintlify/payouts-and-b2b/payment-flow/assessing-fees.mdx	Adds the platform-fee guide and resolves the previously reported inconsistency by aligning the quote’s sending amount and fee fields with the worked example.
mintlify/docs.json	Adds the new guide to the intended Payouts & B2B navigation group.

_{Reviews (2): Last reviewed commit: "docs(payouts): fix quote example, note R..." | Re-trigger Greptile}

[ls-bolt]

📌 Bolt Status

2026-08-14 21:52:05 UTC — ⚡ Agent shielded-cipher-3(#3) started

---

Feedback

[ls-bolt]

⚡ Revision log — updated in place, latest first.

Revision 1

• Fixed the inconsistent quote example (Greptile P1) — response now consistent at the 1,000-cent send, tied explicitly to the worked calculation above it
• Flagged the incoming RAIL fee type and stablecoin (USDC) sending-currency support as planned, so the page doesn't read as if today's limits are permanent
• Added that a fee can only be charged when you hold a platform internal account in the transaction's sending currency
• Fixed two internal inconsistencies: the component table now says the variable fee applies after fixed fees, and the capability-discovery pointer moved from GET /config to the changelog
• Declined the relative-links suggestion (Greptile P2) — root-relative is this repo's actual convention, 94 vs 2; reasoning in the thread
• Confirmed totalReceivingAmount: 863 is correct against the pricing engine's rounding, not the simpler (1000 - 63) x 0.92 model

[ls-bolt]

@greptile review