# Collect surcharges

Offset your card processing costs in the form of surcharges with the Payment Element.

> This feature is in private preview. 

Automatic surcharge adds a surcharge to your Checkout payments based on your customer’s card details, including card brand, funding type, and issuing country. Surcharging laws vary by jurisdiction. Stripe enables you to use a third-party surcharging provider to calculate the surcharge amount.

## Compliance requirements 

If you impose a surcharge on your customers, you must comply with all applicable laws and card network rules. Surcharging requirements vary across regions and card types. Some jurisdictions prohibit surcharging entirely. Where surcharging is permissible, you must accurately calculate the surcharge so it doesn’t exceed surcharge limits imposed by relevant card networks, or your cost of payment acceptance.

Depending on the network, card network requirements might include obligations to:

- Accurately calculate surcharge amounts.
- Notify your acquirer or the card network of your intent to surcharge.
- Surcharge consistently across card networks or card products.
- Conspicuously disclose details of your surcharging or total costs (including any applied surcharge) to the cardholder ahead of purchase, and reflect the surcharge separately on the transaction receipt.
- After surcharge disclosure, provide the ability to cancel the transaction, or choose a different payment method, before confirmation.

> You’re fully responsible for any fines, penalties, or losses arising in connection with your failure to adhere to applicable surcharging requirements.

The information provided on this page relating to your compliance with these requirements is for your general guidance, and isn’t legal, tax, accounting, or other professional advice. Consult a professional if you’re unsure about your obligations.

## Before you begin

This feature requires a preview API version. Set the `Stripe-Version` header to a preview API version when initializing your Stripe client.

During this private preview, automatic surcharge has the following limitations:

- It’s only supported in the United States.
- Supported payment methods are cards and Apple Pay. Transactions with a non-supported payment method don’t have any applicable surcharge.
- It’s available in `payment` mode only.
- It isn’t compatible with [Adaptive Pricing](https://docs.stripe.com/payments/checkout/localize-prices/adaptive-pricing.md).
- Only the Payment Element supports automatic surcharge, the [Address Element](https://docs.stripe.com/elements/address-element.md) or [Express Checkout Element](https://docs.stripe.com/elements/express-checkout-element.md) doesn’t support it.

## Install a surcharge provider app

Before you can use automatic surcharge, install a surcharge provider’s Stripe App from the Dashboard App Marketplace and complete the onboarding process. Stripe supports [Yeeld](https://marketplace.stripe.com/apps/yeeld) and [InterPayments](https://marketplace.stripe.com/apps/interpayments) to provide surcharges.

> You’re responsible for verifying your provider is calculating surcharges in compliance with applicable laws and card network rules in each jurisdiction where you operate.

## Configure your Checkout Session to collect surcharge

- Set [automatic_surcharge[enabled]](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-automatic_surcharge-enabled) to `true`, along with an `automatic_surcharge[calculation_basis]`.
- Set [billing_address_collection](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-billing_address_collection) to `auto` to allow the Payment Element to collect the billing address fields required for surcharge calculation.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-04-22.preview" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "automatic_surcharge[enabled]=true" \
  -d "automatic_surcharge[calculation_basis]=total_before_tax" \
  -d billing_address_collection=auto \
  -d mode=payment \
  -d ui_mode=elements \
  -d return_url={{RETURN_URL}}
```

### Calculation basis

The [automatic_surcharge[calculation_basis]](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-automatic_surcharge-calculation_basis) determines which amount to use as the basis for calculating the surcharge.

| Value              | Description                                                                                                                                                     | Use when                                                                             |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `total_before_tax` | Calculates the surcharge on the subtotal before taxes. For example, a 3% surcharge on a 100 USD order with 10 USD tax = 3.00 USD surcharge.                     | Regulations or business policy require surcharging only on the pre-tax amount.       |
| `total_after_tax`  | Calculates the surcharge on the total after taxes. For example, a 3% surcharge on a 100 USD order with 10 USD tax = 3.30 USD surcharge (calculated on 110 USD). | You want the surcharge to cover payment processing costs on the full charged amount. |

### Tax compatibility

Automatic surcharge is compatible with [Stripe Tax](https://docs.stripe.com/tax.md) using automatic tax, which you can configure in the Dashboard. To override this, use [automatic_surcharge[tax_behavior]](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-automatic_surcharge-tax_behavior) to manually control whether to calculate the surcharge inclusive or exclusive of tax. Automatic surcharge doesn’t support manual tax rates.

## Configure the Payment Element

Create the Payment Element with [fields.billingDetails](https://docs.stripe.com/js/custom_checkout/create_payment_element#custom_checkout_create_payment_element-options-fields-billingDetails) set to `auto` to collect the fields required for surcharge calculation. Automatic surcharge is supported with the Payment Element only, and not compatible with the [Address Element](https://docs.stripe.com/elements/address-element.md) or [Express Checkout Element](https://docs.stripe.com/elements/express-checkout-element.md).

#### React

```jsx
import React from 'react';
import {PaymentElement, useCheckout} from '@stripe/react-stripe-js';

export default function CheckoutForm() {
  const {confirm} = useCheckout();

  const handleSubmit = async (e) => {
    e.preventDefault();
    await confirm({return_url: '{{RETURN_URL}}'});
  };

  return (
    <form onSubmit={handleSubmit}>
      <PaymentElement
        options={{
          fields: {
            billingDetails: 'auto',
          },
        }}
      />
      <button type="submit">Pay</button>
    </form>
  );
}
```

#### HTML + JS

```html
<form id="payment-form">
  <div id="payment-element">
    <!--Stripe.js injects the Payment Element-->
  </div>
  <button id="submit">Pay</button>
</form>
```

```javascript
const paymentElement = checkout.createElement('payment', {
  fields: {
    billingDetails: 'auto',
  },
});
paymentElement.mount('#payment-element');

document
  .getElementById('payment-form')
  .addEventListener('submit', async (e) => {
    e.preventDefault();
    await checkout.confirm({return_url: '{{RETURN_URL}}'});
  });
```

Setting `fields.billingDetails` to `auto` is the default behavior, and allows Stripe to determine which fields to show. If you set `fields.billingDetails.address` to `never`, the billing address won’t be collected and the surcharge can’t be calculated.

## Render the surcharge amount

#### React

Use the [useCheckout](https://docs.stripe.com/js/react_stripe_js/checkout/use_checkout) hook to display the surcharge amount in your payment form by reading from [total.surcharge](https://docs.stripe.com/js/react_stripe_js/checkout/use_checkout#react_use_checkout-total-surcharge).

```jsx
import React from 'react';
import {useCheckout} from '@stripe/react-stripe-js';

const CheckoutForm = () => {
  const checkoutState = useCheckout();
  if (checkoutState.type === 'loading') {
    return (
      <div>Loading...</div>
    );
  } else if (checkoutState.type === 'error') {
    return (
      <div>Error: {checkoutState.error.message}</div>
    );
  }
  const {checkout} = checkoutState;
  return (
    <div>
      <h2>Checkout Summary</h2>
      <pre>
        {JSON.stringify(checkout.lineItems, null, 2)}
      </pre>
      <h3>Totals</h3>
      <pre>
        Subtotal: {checkout.total.subtotal.amount}
        Surcharge: {checkout.total.surcharge.amount}
        Total: {checkout.total.total.amount}
      </pre>
    </div>
  )
};
```

#### HTML + JS

Use the [Session object](https://docs.stripe.com/js/custom_checkout/session_object) to display the surcharge amount in your payment form by reading from [total.surcharge](https://docs.stripe.com/js/react_stripe_js/checkout/use_checkout#react_use_checkout-total-surcharge). You can read from [surcharge](https://docs.stripe.com/js/react_stripe_js/checkout/use_checkout#react_use_checkout-surcharge) to determine the surcharge computation status.

```html
<div>
  <h3> Totals </h3>
  <div id="subtotal" ></div>
  <div id="surcharge" ></div>
  <div id="total" ></div>
</div>
```

```js
const checkout = stripe.initCheckoutElementsSdk({clientSecret})
const subtotal = document.getElementById('subtotal');
const surcharge = document.getElementById('surcharge');
const total = document.getElementById('total');

checkout.on('change', (session) => {
  subtotal.textContent = `Subtotal: ${session.total.subtotal.amount}`;
  surcharge.textContent = `Surcharge: ${session.total.surcharge.amount}`;
  total.textContent = `Total: ${session.total.total.amount}`;
})
```

## Optional: Check the response

To see the results of the surcharge calculation, retrieve the Checkout Session after the customer completes checkout. The [automatic_surcharge.status](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-automatic_surcharge) property shows whether the surcharge was successfully calculated (`complete`) or couldn’t be applied (`failed`). When `status` is `complete`, the [surcharge_cost](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-surcharge_cost) property shows the breakdown, including `amount_subtotal`, `amount_tax`, and `amount_total`.

## Test your integration

Use [test cards](https://docs.stripe.com/testing.md) to simulate surcharge scenarios before going live. Test cards let you verify that the Payment Element collects billing address details and that the surcharge is correctly calculated and displayed to the customer.