# Fee subsidization

Cover onramp fees and let Stripe bill you instead.

Fee subsidization lets you cover onramp transaction fees. When enabled for a session, the user pays no network or transaction fees, so their total charge is only the source amount. Stripe deducts those fees from your Stripe balance instead.

Fee subsidization is currently a binary feature: a session’s fees are either fully subsidized or not at all. There’s no partial subsidy.

Fee subsidization is only available for users in the US. Contact your Stripe account team to confirm availability for your use case.

## Before you begin

Before you can subsidize fees, you need:

- **Access to fee subsidization**: Fee subsidization isn’t enabled for every account. Contact your Stripe account team to request access.
- **Embedded components**: Fee subsidization is currently only supported for [embedded components onramp sessions](https://docs.stripe.com/crypto/onramp/embedded-components-integration-guide.md) (`ui_mode: headless`). Sessions created with any other UI mode can’t use `fee_responsibility: merchant`.
- **No revenue share**: Fee subsidization and revenue share are mutually exclusive. If your account has an active revenue share agreement with a non-zero partner fee, we reject requests with `fee_responsibility: merchant` until the fee is removed or the configuration is zeroed out.

## Enable fee subsidization for a session

Pass `fee_responsibility` when you create a crypto onramp session or fetch a quote. Setting it to `merchant` requires `ui_mode=headless`—without it, the request fails with a 400 and `error.code` set to `crypto_onramp_fee_subsidy_unavailable`, even if the session itself uses embedded components. Check `error.message` for the specific cause. `fee_responsibility` is a preview-only parameter: use a [private preview SDK](https://docs.stripe.com/sdks/versioning.md#private-preview-release-channel), or include a [preview API version](https://docs.stripe.com/release-phases.md) in the `Stripe-Version` header if you’re calling the API directly—requests on a general availability version don’t recognize it.

#### curl

```shell
curl https://api.stripe.com/v1/crypto/onramp_sessions \
  -u <<YOUR_SECRET_KEY>>: \
  -H "Stripe-Version: 2026-09-30.preview;crypto_onramp_beta=v2" \
  -H "Stripe-OAuth-Token: $ACCESS_TOKEN" \
  -d ui_mode=headless \
  -d fee_responsibility=merchant \
  ...
```

The same two parameters apply to a quote request:

#### curl

```shell
curl -G https://api.stripe.com/v1/crypto/onramp_quotes \
  -u <<YOUR_SECRET_KEY>>: \
  -H "Stripe-Version: 2026-09-30.preview;crypto_onramp_beta=v2" \
  -d ui_mode=headless \
  -d fee_responsibility=merchant \
  ...
```

`fee_responsibility` accepts:

| Value | Description |
| --- | --- |
| `consumer` (default) | The user pays the transaction fees. |
| `merchant` | You pay all transaction fees on behalf of the user. |

### Verify it in a sandbox

Create an embedded components sandbox session with `fee_responsibility: merchant` and fetch a quote. Confirm that:

- The quote’s `source_total_amount` equals the pre-fee source amount (no fee added for the user).
- The quote’s `fees.subsidy` object is present. See [Reconciling subsidized fees](https://docs.stripe.com/crypto/onramp/fee-subsidization.md#reconciling-subsidized-fees).

## Apply conditional subsidies

You can choose which sessions to subsidize based on conditions in your app. For example, you can cover fees for a user’s first completed transaction or for users who meet your promotion criteria.

Your app defines and evaluates these conditions for each new session. Each qualifying session is fully subsidized, and conditional subsidies don’t change the amount of fees covered within a session.

## How billing works

When you subsidize a session’s fees, Stripe doesn’t waive those fees. Instead, it bills you for them rather than collecting them from the user. Stripe aggregates subsidized fees across your sessions and applies them to your Stripe balance after the transactions complete. Charges don’t appear against an individual session in real time. See [Review fee history](https://docs.stripe.com/crypto/onramp/fee-subsidization.md#review-fee-history) to find billed fees and their breakdown in the Dashboard and reports.

If Stripe refunds a subsidized session later, we automatically reverse the corresponding billed amount and don’t bill you for fees on the refunded transaction. Use the [All fees report](https://docs.stripe.com/crypto/onramp/fee-subsidization.md#all-fees) or [Balance summary report](https://docs.stripe.com/crypto/onramp/fee-subsidization.md#balance-summary) to reconcile refunded transactions and their fee reversals. The session’s `subsidy` properties retain the original subsidized amounts and don’t reflect these reversals.

## Reconciling subsidized fees

Both the quote response and session retrieval include a `subsidy` object when a quote’s fees become available and `fee_responsibility` is `merchant`. The `subsidy` object is omitted entirely when `fee_responsibility` isn’t `merchant`, and it’s also absent early in a session’s lifecycle, before a quote with fees has been selected.

Quote response—each individual quote is nested under `destination_network_quotes.<network>[]`:

```json
{
  "destination_network_quotes": {
    "ethereum": [
      {
        "fees": {
          "network_fee_monetary": "1.25",
          "transaction_fee_monetary": "0.50",
          "subsidy": {
            "original_fee": "1.75",
            "total_fee_after_subsidization": "0.00"
          }
        }
      }
    ]
  }
}
```

Retrieved session:

```json
{
  "transaction_details": {
    "fees": {
      "network_fee_amount": "1.25",
      "transaction_fee_amount": "0.50",
      "subsidy": {
        "original_fee": "1.75",
        "total_fee_after_subsidization": "0.00"
      }
    }
  }
}
```

- `original_fee`: the total fee (network fee plus transaction fee) before subsidization.
- `total_fee_after_subsidization`: the fee actually charged to the user. Currently, this is always `0.00`.

The `original_fee` for the quote response is only an estimate for that network and amount, and it isn’t billable until a session completes with those terms. Use the `original_fee` from the completed session (not from a quote) to reconcile against the billed fees in the Dashboard and reports.

## Review fee history

Use the Stripe Dashboard to review billed fees, or list onramp sessions through the API to check the subsidized amount for each completed transaction.

### Use the Dashboard

Sign in to the [Stripe Dashboard](https://dashboard.stripe.com) with your Stripe account to review fees deducted from your Stripe balance in any of the following ways. See [Standalone fees](https://docs.stripe.com/standalone-fees.md) for details on how fees are applied separately from transactions and displayed in the Dashboard and reports.

#### Transactions

Go to **Transactions** > **All Activity**. Filter by `Type` set to **Stripe Fee**, `Category` set to **Fee**, or `Description` containing `Crypto Onramp Merchant Subsidy`.

Standalone fees appear as aggregated fee transactions after they’re applied to your balance, typically within 36 hours of the transaction. A single fee transaction can include subsidized fees from multiple onramp sessions. To view the list of onramp sessions included in a fee transaction, see [All fees](https://docs.stripe.com/crypto/onramp/fee-subsidization.md#all-fees).

#### Balance summary

Go to **Reports** > **Balance summary** to review and export your balance activity. You can view standalone fees under **Additional Stripe fees** after they’re applied to your balance (typically within 36 hours of the transaction). Complete report data for the day the fees affect your balance is available by 12:00 PM the following day in the report’s time zone. See the [Balance summary report](https://docs.stripe.com/reports/balance.md#reporting-periods-and-data-availability) for details.

#### All fees

Go to **Reports** > **All Fees** to view the fees associated with each transaction. Use the itemized report to break down an aggregated fee transaction into fees for individual onramp sessions. See [Find the fees for a transaction](https://docs.stripe.com/reports/all-fees.md#find-the-fees-for-a-transaction) for instructions on downloading and filtering the report.

Fee data is available within 96 hours after a fee affects your balance. This reporting delay starts when the fee is applied to your balance, not when the onramp session completes.

### Use the API

Use the [List CryptoOnrampSessions API](https://docs.stripe.com/api/crypto/onramp_sessions/list.md?api-version=2026-09-30.preview&rds=1&lang=curl) to retrieve past sessions and their fee data.

For each session, check `transaction_details.fees.subsidy`. Subtract `total_fee_after_subsidization` from `original_fee` to calculate the subsidized amount. Sessions where the user pays the fees don’t include the `subsidy` object.