A partner fee is the markup a platform adds to a stablecoin quote. How to set percentage or flat fees, show them on the quote, and get paid each month.
A partner fee is the margin a platform adds to a live quote so it earns on every payin, payout, or transfer it runs for its users. On BlindPay, you create a percentage or flat fee once, pass its partner_fee_id when you request a quote, and the quote shows partner_fee_amount as a separate line before anyone confirms.
Key takeaways
A partner fee is your markup, added on top of the provider's price inside the same binding quote. The quote locks the market rate, the provider's fees, and your fee together for its window, so the number your user confirms is the number that settles.
This is the business model for most platforms that embed stablecoin payments: a payroll app, a marketplace paying sellers, a wallet offering cash-out to a bank. The provider runs the conversion and the rail. You own the user and charge for the product around it.
Every term here has one meaning across this cluster. The on/off-ramp liquidity glossary defines live quote, spread, and fee lines if you want the vocabulary first.
You configure the fee once, then reference it on every quote that should carry it. Four steps:
POST /v1/instances/{instance_id}/partner-fees with a name and the four fee fields: payin_percentage_fee, payin_flat_fee, payout_percentage_fee, payout_flat_fee. Save the returned id (pf_...). You can also create it in the dashboard's Partner Fees tab.partner_fee_id to the payin quote, payout quote, or transfer quote request.partner_fee_amount next to commercial_quotation, blindpay_quotation, flat_fee, sender_amount, and receiver_amount. Render your fee as its own line.expires_at. The fee is locked into the quote like everything else. If the quote expires, request a new one and the fee is recalculated on the new amounts.Two details that save debugging time. Fee configurations are immutable: to change a fee, delete the configuration and create a new one, then point new quotes at the new id. And POST /partner-fees accepts an Idempotency-Key header, so a retried create does not leave you with two configurations.
The full field reference is in the partner fees docs, and the quote fields are in the payout quotes docs.
Percentage fees scale with the amount, flat fees do not. Pick by ticket size and by how your users think about price.
Illustrative example. Compare a 50 basis point fee (0.50%) with a $5.00 flat fee across three payout sizes:
| Payout size | 50 bps fee | 50 bps as % | $5.00 flat fee | Flat as % |
|---|---|---|---|---|
| $200 | $200 x 0.005 = $1.00 | 0.50% | $5.00 | 5 / 200 = 2.50% |
| $2,000 | $2,000 x 0.005 = $10.00 | 0.50% | $5.00 | 5 / 2,000 = 0.25% |
| $20,000 | $20,000 x 0.005 = $100.00 | 0.50% | $5.00 | 5 / 20,000 = 0.025% |
The flat fee looks expensive on a $200 consumer payout and almost free on a $20,000 supplier payment. The percentage fee is steady, which is easier to explain and easier to compare.
A decision rule that holds up in practice:
Put it in a fee line. A margin hidden inside the exchange rate is still a cost, it is just harder for users to see and harder for you to defend.
US remittance rules show why. For consumer remittance transfers, the CFPB's pre-payment disclosure under 12 CFR 1005.31 asks providers to list the transfer amount, the transfer fees, the total, and the exchange rate used as separate items. A separate fee line maps onto that structure directly. Whether those rules apply to your product depends on what you do and who your users are, so check with counsel.
A fee line also keeps your pricing honest against the market. The quote shows commercial_quotation, the raw market rate, and blindpay_quotation, the rate net of BlindPay's fee. With your fee as partner_fee_amount, a user can see three things at once: the market, the provider's margin, and yours. The method for measuring a spread from those two rates is in how to calculate FX spread.
And it reconciles cleanly. One field per transaction means revenue is a sum, not a reverse-engineering exercise on exchange rates.
Monthly. BlindPay collects your partner fee from your customer during each transaction, accumulates the total over the calendar month, and releases it for withdrawal on the first day of the next month.
Your BlindPay invoice is netted out first, so you never pay it separately.
Illustrative example. Your platform runs 1,200 payouts in January at an average of $1,500 each, with a 40 basis point partner fee:
The docs use a smaller version of the same math: $500 collected, a $250 invoice, $250 available on February 1.
Deposits into a virtual account create payins on their own, with no quote request where you could pass a partner_fee_id. So the fee is set ahead of time, at two levels:
| Level | How to set it | Effect |
|---|---|---|
| Instance-wide default | Create a fee with virtual_account_set: true, or toggle it in the dashboard | Applies to every virtual account deposit on the instance; one active default at a time |
| Per virtual account | Pass partner_fee_id when creating the account, or set it later | Overrides the default for that account; set it to null to fall back |
Send virtual_account_set as a real boolean. A string such as "false" is read as true.
Every deposit delivers at least $0.01 of stablecoin, and the partner fee comes out of what remains after any transaction-time BlindPay fee. On a tiny deposit, collection can be partial: a $5.00 fee on a $5.00 deposit collects $4.99. If you price per account, the virtual account fees breakdown shows every other cost on the same deposit.
Read partner_fee_amount from each quote and store it with the quote_id and the payin or payout id. That field is the exact amount collected for that transaction, and it is the source of truth for revenue.
A minimal revenue log needs five columns: quote_id, transaction id, partner_fee_amount, currency, and the month it settled. Sum by month, subtract your BlindPay invoice, and the result should match the release on the 1st.
Webhooks tell you when the underlying payout or payin moves (payout.new, payout.update, payout.complete), and the fee travels with that transaction. Build revenue reporting off the quote field rather than waiting for a fee-specific event.
Price the total, not your slice. Your user compares what lands in the recipient's account, so your fee plus the provider's margin plus any network cost is the number that matters.
Two anchors help:
Then test it. Request a quote with and without your partner_fee_id for the same corridor, compare receiver_amount, and ask whether a user would still pick you. If you are also evaluating providers, the 10-point liquidity scorecard tells you whether the base quote underneath your fee is worth building on.
BlindPay publishes its plans on the pricing page, and per-transaction fees vary by rail and network, so each quote shows the exact fee lines before execution.
Create one partner fee on a free development instance, pass its id on a payout quote, and read partner_fee_amount in the response. Then follow the partner fees guide to set payin and payout fees separately and wire the amount into your revenue log.
This article is general information, not legal, tax, or financial advice.
Seven places blockchain payments beat bank rails: contractor payroll, remittances, B2B suppliers, marketplaces, 24/7 treasury, bill pay, and PSP payouts.
AP2, ACP, and x402 each verify that an AI agent had permission to spend. Here is what every protocol covers, who backs it, and the reconciliation gap none of them close.
The three roles behind every card program, stablecoin cards included: what each one does, who carries liability, and what to ask a provider.