# Platform fees

Building with an AI agent? Start at https://docs.payme.io/agents.md

## Related

- [Reconcile sales and withdrawals](/accepting-payments/reporting/reconcile-sales-and-withdrawals)
- [Withdrawals](/marketplaces-and-platforms/fees-and-payouts/withdrawals)

## What market_fee is

`market_fee` is the percent of each sale price that PayMe collects from the seller for you, the platform. It comes on top of PayMe's own fees. The buyer pays the same price.

- **Units:** a percent, not minor units. `2.5` means 2.5%.
- **Range:** 0 to 60.
- **VAT:** the percent includes VAT. PayMe adds none on top.
- **Payout:** by default, the fee is transferred to the marketplace once a month. The seller's balance is already net of it.

On a sale of `10000` (100.00) with `market_fee` `2.5`, the fee is `250` (2.50).

## Set a default for a seller

Send `market_fee` on [Create a seller](/payments/merchants-management/post-create-seller). Without it, the seller's default is `0`. A value outside 0–60 returns error `304`.

The default can't be changed with [Update a seller](/payments/merchants-management/post-update-seller). To change a seller's default later, contact PayMe Partners (<partners@payme.io>). Until it's changed, set the fee on each sale with `market_fee`, as shown below.

A change to the default affects future sales only. Each sale keeps the fee it had when it was generated, including an authorization that hasn't been captured yet.

## Set the fee on one sale

Send `market_fee` on [Generate Payment](/payments/hosted-payment-page/post-generate-sale) to override the seller's default for that sale. Without it, the sale uses the seller's default. Send `0` to charge no fee on that sale.

```json
{
  "payme_client_key": "XXXXXXXX",
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "sale_price": 10000,
  "currency": "ILS",
  "product_name": "Monthly plan",
  "transaction_id": "order-1001",
  "sale_callback_url": "https://example.com/payme/callback",
  "sale_return_url": "https://example.com/thanks",
  "market_fee": 2.5
}
```

## Add a fixed fee per sale

Send `market_fee_fixed` on generate-sale to add a fixed fee to the percent on that sale. Unlike other amounts in the API, it is in **major units**: `2.5` means 2.50. The percent and the fixed fee are added together.

On a sale of `10000` (100.00) with `market_fee` `2.5` and `market_fee_fixed` `1`, the fee is `350` (3.50).

The percent plus the fixed fee, taken as a percent of the sale price, can't be more than 60%.

| Error | Meaning |
| --- | --- |
| `10` | `market_fee` is not a number |
| `304` | `market_fee` is negative, or `market_fee_fixed` is negative or not a number |
| `308` | `market_fee` plus `market_fee_fixed` is above 60% of the sale price |

## Sellers paid directly

Setting the fee on a sale isn't supported for sellers the card companies pay directly: the seller's default applies, whatever the sale sends. Contact PayMe to arrange platform fees for these sellers.

## See what was charged

| Where | Field | Meaning |
| --- | --- | --- |
| [get-sellers](/payments/query-apis/post-get-sellers) | `seller_fees.fee_market_fee` | The seller's default percent. Use it to confirm a change took effect. You can also filter on `fee_market_fee` |
| [get-sales](/payments/query-apis/post-get-sales) | `sale_fees.sale_market_fee`, `sale_fees.sale_market_fee_fixed` | The percent, and the fixed fee in major units, on this sale |
| [get-transactions](/payments/query-apis/post-get-transactions) | `sale_fees.sale_market_fee_total` | The fee on this transaction's amount in minor units: the percent part plus the fixed part |

On `get-transactions`, a partial refund's `sale_market_fee_total` is worked out from the refunded amount, so it shows the fee on that part of the sale. Whether a seller gets fees back on a refund depends on the seller's account settings.