What is surcharging?

Surcharging enables you to charge customers an additional fee depending on the payment method or card they pay with. Applying this surcharge fee is a way to cover the costs associated with processing payments on each of the available payment methods.

Universal Checkout can help you manage and present your surcharge in a unified way across all your platforms and payment methods.

Get started with Drop-in Checkout

High level flow

• First, create a client session with the line items and the surcharge amount for all of your payment methods and card networks.
• During its initialization, Drop-in Checkout automatically retrieves the surcharge data and presents the amount to the user.
• When the user selects a payment method, Drop-in Checkout automatically adds the surcharge amount to the client session.
• When a payment is created, the full amount including surcharging is used to process the transaction.

Step 1. Configure the client session

Pass the surcharge amount for each payment method that you support when creating a client session. The surcharge feature is activated when at least one payment method has a surcharge amount attached.

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051

{    "currencyCode": "EUR",    "order": {        "lineItems": [            {                "itemId": "shoe-123",                "description": "Blue Shoe",                "amount": 100,                "quantity": 1            }        ],        "fees": []    },
    "paymentMethod": {        "options": {            "PAYPAL": {                "surcharge": {                    "amount": 300                }            },
            "PAYMENT_CARD": {                "networks": {                    "VISA": {                        "surcharge": {                            "amount": 100                        }                    },                    "MASTERCARD": {                        "surcharge": {                            "amount": 150                        }                    }                }            },
            "ADYEN_IDEAL": {                "surcharge": {                    "amount": 100                }            },
            "BUCKAROO_IDEAL": {                "surcharge": {                    "amount": 100                }            }        }    }}

The list of payment method types is available here.

Step 2. Present the drop-in checkout

Once the client session is created, use the client token to present the drop-in checkout as usual.

The drop-in checkout automatically retrieves the surcharge fees from the client session and displays them on its UI.

When the user selects a payment method, the SDK automatically patches the client session to add a fee of type SURCHARGE with the relevant surcharge amount.

Similarly, when the user unselects a payment method, the SDK automatically patches the client session to remove the surcharge fee.

Step 3. Update the surcharge amount (optional)

You can update the client session at any time to modify the surcharge fees attached to each payment method. This is particularly useful on Web if the user has the opportunity to update their cart while interacting with our drop-in checkout.

This automatically updates the fee of type SURCHARGE added by the SDK to the new amount for the currently selected payment method. You can also use this mechanism to enable and disable surcharging during a client session.

123456789101112131415161718192021222324252627

// Content of the client session
{    "currencyCode": EUR,    "order": {        "lineItems": [{          "itemId": "shoe-123",      "description": "Blue Shoe",      "amount": 100,      "quantity": 1      }],        "fees": [{            /* This is automatically added by the SDK when the user selects a payment method*/            "type": "SURCHARGE",            "amount": 300        }],    },
    "paymentMethod": {        "options": {
            /* Surcharge values ... */        }    }
    /* ... */}

Step 4. Create a payment

By default, the drop-in checkout creates payments automatically. This payment takes into account the surcharge amount, so you don’t have to do anything.

If you choose to create payment manually, make sure to not pass the top-level amount or order.fees on the payment request as this would override the amount set during the client session.

Considerations

Security measures have been put in place to prevent users, malicious or not, to bypass surcharging:

• If the surcharge options have been passed but no surcharge fee is present in the client session, the payment will fail to be created.
• If the surcharge options have been set but the surcharge fee does not match the selected payment method, the payment will fail to be created.

Get started with Headless Checkout