---
title: "How platforms add their own margin to a live quote: partner fees explained"
seoTitle: "Partner fees: add your own margin to a live FX quote"
description: "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."
date: "2026-10-10"
updated: "2026-10-10"
category: "payments"
author: "BlindPay Team"
faq:
  - q: "What is a partner fee in a stablecoin API?"
    a: "A partner fee is a markup a platform adds on top of each transaction it runs through a payments provider. At BlindPay you create a fee configuration once, pass its partner_fee_id on a payin, payout, or transfer quote, and the quote returns partner_fee_amount as its own line. BlindPay collects it during the transaction and pays it out monthly."
  - q: "Can I charge a percentage and a flat fee?"
    a: "Yes. A BlindPay fee configuration has percentage and flat fields, set separately for payins and payouts. Percentages are in basis points from 0 to 9,900, where 100 means 1%, capped at 99% of the transaction. Flat fees are in minor units from 0 to 100,000, where 200 means $2.00, capped at $1,000.00 per transaction."
  - q: "When do I receive the partner fees I collect?"
    a: "Fees collected during a calendar month accumulate and are released for withdrawal on the first day of the following month. BlindPay nets your outstanding BlindPay invoice out of that balance first, so you receive the net amount and never pay the invoice separately. If you collect $500 and your invoice is $250, $250 becomes available."
  - q: "Should a platform hide its margin inside the exchange rate?"
    a: "It works, but it makes your price hard to audit and hard to compare. A separate fee line keeps the market rate visible, lets users check the spread, and maps to how US remittance disclosures separate fees from the exchange rate. On BlindPay the partner fee is always its own field, partner_fee_amount, next to the market and applied rates."
  - q: "How do I track partner fee revenue per transaction?"
    a: "Store partner_fee_amount from each quote next to the quote_id and the payout or payin id. That field is the exact amount collected for that transaction, so summing it by month gives you the revenue BlindPay will release on the first of the next month, before invoice netting. Reconcile that sum against the monthly release."
  - q: "Do partner fees apply to virtual account deposits?"
    a: "Yes. Deposits into a virtual account create payins without a quote request, so the fee is configured ahead of time: an instance-wide default set with virtual_account_set true, or a fee pinned to a single virtual account, which overrides the default. A deposit always delivers at least $0.01, so tiny deposits can collect a partial fee."
---

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 rides on the quote, so the user sees your margin, the market rate, and the provider's fees before confirming.
- Percentage fees run from 0 to 9,900 basis points (capped at 99%); flat fees from 0 to 100,000 minor units (capped at $1,000.00).
- Fees are set separately for payins and payouts, and can also be applied to transfer quotes.
- Collected fees accumulate per calendar month and are released on the 1st of the next month, net of your BlindPay invoice.
- A fee line beats a hidden rate markup: it is easier to disclose, audit, and reconcile.

## What is a partner fee on a live quote?

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](/resources/more/onramp-offramp-liquidity-glossary) defines live quote, spread, and fee lines if you want the vocabulary first.

## How do you add a partner fee to a quote?

You configure the fee once, then reference it on every quote that should carry it. Four steps:

1. **Create a fee configuration.** `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.
2. **Pass it on the quote.** Add `partner_fee_id` to the payin quote, payout quote, or transfer quote request.
3. **Show the quote.** The response returns `partner_fee_amount` next to `commercial_quotation`, `blindpay_quotation`, `flat_fee`, `sender_amount`, and `receiver_amount`. Render your fee as its own line.
4. **Execute before `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](/docs/learn/partner-fees), and the quote fields are in the [payout quotes docs](/docs/payout-quotes).

## Percentage or flat: which fee type fits your product?

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:

- **Choose a percentage fee** if tickets vary a lot or skew small, as in consumer cash-out, creator payouts, and contractor payroll.
- **Choose a flat fee** if tickets are large and predictable, as in B2B supplier payments and treasury moves, where a percentage starts to look like a tax on size.
- **Set payins and payouts differently** when the two directions have different economics. The configuration takes separate fields for each, so a 1% payin fee and a $2.00 flat payout fee can live on the same instance.

## Should the markup sit in the rate or in a fee line?

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](https://www.law.cornell.edu/cfr/text/12/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](/resources/more/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.

## When do you get paid?

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:

- Volume: 1,200 x $1,500 = $1,800,000
- Partner fees collected: $1,800,000 x 0.004 = $7,200
- BlindPay invoice for January (illustrative): $2,000
- Available for withdrawal on February 1: $7,200 - $2,000 = $5,200

The docs use a smaller version of the same math: $500 collected, a $250 invoice, $250 available on February 1.

## How do partner fees work on virtual account deposits?

Deposits into a [virtual account](/resources/more/what-is-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](/resources/more/virtual-account-fees) shows every other cost on the same deposit.

## How do you track partner fee revenue per transaction?

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.

## How do you price a markup users will accept?

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:

- **The policy benchmark.** The G20 target set by the [Financial Stability Board](https://www.fsb.org/2021/10/targets-for-addressing-the-four-challenges-of-cross-border-payments-final-report/) is a global average cost of no more than 1% for retail cross-border payments, with no corridor above 3%, by end-2027. Staying under 1% all-in is a strong position.
- **The quote screen.** If your fee shows as a clean line on a well-designed quote screen, users accept it more readily than a mystery rate. [How to show a cross-border quote to users](/resources/more/cross-border-quote-screen-fee-disclosure) covers the layout and the disclosure rules.

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](/resources/more/onramp-offramp-liquidity-scorecard) tells you whether the base quote underneath your fee is worth building on.

BlindPay publishes its plans on the [pricing page](/pricing), and per-transaction fees vary by rail and network, so each quote shows the exact fee lines before execution.

## What to do next

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](/docs/learn/partner-fees) 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.*