​
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.

Card surcharge on Web

It is worth noting that, while Universal Checkout supports this feature natively, payment method surcharge is regulated, or even prohibited, in many countries.In addition, some payment methods have guidelines and agreements that prohibit surcharging fees. Universal Checkout is not opinionated in this regard, and will always attempt to present the surcharge to the user.
Surcharging is currently available on Drop-in Checkout for all payment methods except Klarna.Headless Checkout does not support surcharging natively.

​
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.
Keep in mind that all amounts on Primer are in minor units
JSON
{
	"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.
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.Do not specify a top-level amount as this will override the dynamically-calculated amount.

​
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.

Surcharge

On Web, applying surcharge forces the payment method “Card” to appear as a button instead of a form.
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.
Typescript
// 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 ... */
		}
	}

	/* ... */
}
On Web, if card.preferredFlow is not provided or is set to EMBEDDED_IN_HOME , the checkout will attempt to show the card form on the home screen. This cause the card form to break when surcharging is enabled and then disabled during a client session.We highly encourage you to set card.preferredFlow to DEDICATED_SCENE to force the card form to appear behind a button. This ensures that the card form can always be presented.

​
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

At the moment, payment method surcharging is not supported by Headless Checkout. We encourage you to not pass the surcharge options in the client session.