Surcharging enables you to charge customers an additional fee depending on the payment method or card they pay with. Below is an example checkout with surcharging.

This document explains how to use the surcharging feature of the Universal Checkout.

High level flow

• Pass surcharge details for supported payment methods when creating a client session. More info here.
• Use the clientToken provided in the response to initialize the Universal Checkout with the relevant surcharge information. The checkout will now display surcharge amounts.
• When the user selects or deselects a payment method, client session actions will be provided via the onClientSessionActions() callback. Forward these actions to your server to update the client session. More info here.
  • order.fees will be automatically populated with a fee of id SURCHARGE and the appropriate amount
  • The total amount charged to the user is calculated automatically based on the line items and fees in the order.

<aside> ⚠️ The surcharge feature dynamically updates the total order amount for you by updating the order.fees array on your Client Session when at least one line item is provided. Specifying a top-level amount will override this with a static amount. We recommend only using order-level line items in this case.

</aside>

Integration guide

1 - Prepare 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 surcharge has a non-zero amount.

// POST /client-session
// Request

{
	"currencyCode": EUR,
	"order": {
		"lineItems": [{
		  "itemId": "shoe-123",
      "description": "Blue Shoe",
      "amount": 100,
      "quantity": 1   
	  }],
		"fees": [],
	},

	"paymentMethod": {
		"options": {
			
			// Surcharge for PAYPAL
			"PAYPAL": {
				"surcharge": {
					"amount": 300,
				}
			},
			
			// Surcharge with Cards
			// Use the `networks` object to set the surcharge amount for each network
			"PAYMENT_CARD": {
				"networks": {
					"VISA": {
						"surcharge": {
							"amount": 100
						}
					},
					"MASTERCARD": {
						"surcharge": {
							"amount": 150
						}
					}
				}
			},

			// Surcharge for iDEAL through Adyen
			"ADYEN_IDEAL": {
				"surcharge": {
					"amount": 100
				}
			},

			"BUCKAROO_IDEAL": {
				"surcharge": {
					"amount": 100
				}
			}
		}
	}

	/* ... */
}

<aside> ⚠️ The surcharge feature dynamically updates the total order amount for you by updating the order.fees array when at least one line item is provided. Specifying a top-level amount will override this with a static amount.

</aside>

Get the ID of any of the currently supported payment methods here.

2 - Process client session actions

When the user selects a payment method, Universal Checkout fires client session actions through the callback onClientSessionActions.

{
	"clientToken": "<CLIENT_TOKEN>",
	"actions": [{
		"type": "...",
		"params": { /* ... */ }
	}]
}