Private preview

Collect surcharges Private preview

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

Private preview

This feature is in private preview. Request access to automatic surcharge.

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 card network of your intent to apply a surcharge, if required by your jurisdiction or the card network.
• 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.

Warning

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 initialising 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 .
• Only the Payment Element supports automatic surcharge, the Address Element or Express Checkout Element 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 and InterPayments to provide surcharges.

Warning

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] to true , along with an automatic _ surcharge[calculation _ basis] .
• Set billing_address_collection to auto to allow the Payment Element to collect the billing address fields required for surcharge calculation.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Calculation basis

The automatic_surcharge[calculation_basis] determines which amount to use as the basis for calculating the surcharge.

Tax compatibility

Automatic surcharge is compatible with Stripe Tax using automatic tax, which you can configure in the Dashboard. To override this, use 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 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 or Express Checkout Element.

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>
 );
}

Setting fields.billingDetails to auto is the default behaviour, 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

Use the useCheckout hook to display the surcharge amount in your payment form by reading from total.surcharge.

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>
 )
};

Optional Check the response

Test your integration

Use test cards 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.