Breadcrumbs

REST API Surcharge

The surcharge functionality is a service that allows a business to add a small extra fee to a customer's payment if they choose a card that is eligible for surcharge from a compliance perspective. This fee is called a surcharge, and it's meant to cover the cost that the business in Denmark, Finland and Norway pays to accept that payment method.

For example, if a customer chooses to pay with a corporate credit card - which usually costs more for the business to process - or with cards from non-EEA countries, the checkout system may add a small surcharge (equivalent to the fee the merchant pays to process that transaction) to help cover that cost. Which cards can be surcharged and in which way the surcharge must be processed and presented to the end customer are regulated by local laws and scheme rules.

The NEXI REST API supports surcharge in one model:

  • Hosted model (Paygate-controlled UI): surcharge eligibility, presentation and consent are handled inside the Paygate-hosted card step. This is supported via hosted forms and via hosted payment page.

This page explains how to use surcharge with REST, focusing on end-to-end usage flows and responsibilities. Detailed field definitions are described in the REST technical specification.


Get Started

Activation

To use surcharge in REST integrations:

  • Contact NEXI Helpdesk to activate surcharge for your merchant profile.

  • Ensure your merchant configuration supports card-based surcharge.


Integration options

The surcharge is available in 2 integration types:

  • Hosted forms (Paygate UI): Use REST to create a hosted payment flow and let Paygate present the surcharge outcome on the hosted card step.

  • Hosted payment page: Use REST to initiate a hosted payment page and let Paygate present the checkout session.


Payment flow user experience

Scenario 1: Surcharge is not offered (disabled, not eligible)

  • The checkout proceeds in the merchant currency and amount.

  • No surcharge-related information is shown.

Scenario 2: Surcharge (enabled, eligible)

 

https://developer.computop.com/download/attachments/233734815/surcharge_image-2026-03-23-16-23-23-011.png?version=1&modificationDate=1776263622213&api=v2

  • The checkout shows the calculated total surcharge value as a discrete, labeled fee and the new total amount (merchant amount plus surcharge)

  • The cardholder reviews all fees before confirming

  • The payment proceeds in the merchant currency, but for a higher amount.



Payment execution with REST

Hosted model (Paygate-controlled UI)

In the hosted model, the merchant creates a hosted payment flow via REST. If the customer selects card and the card step is hosted by Paygate, Paygate performs surcharge processing and displays the surcharge outcome (if eligible).

Endpoints

  • POST /payments/sessions (hosted payment session / HPP-style)

  • POST /payments with hosted configuration (hosted card flow)


Retrieve payment details (Result & surcharge outcome)

Payment details, including surcharge outcome, can be retrieved via:

  • GET /payments/getByPayId/{payID}

  • GET /payments/getByTransId/{transID}

These endpoints return the final transaction state as processed by Paygate, including surcharge information where applicable.


Authoritative amount & currency

Merchants must treat the values returned by Paygate as authoritative.

  • Merchants must not calculate, convert or adjust exchange rates themselves.

  • For follow-up operations, merchants must submit the amount and currency exactly as required by the respective Paygate interface.

  • Any required surcharge handling is resolved internally by Paygate. It can calculate the new total amount (merchant amount plus surcharge) internally when it comes to the processing of pro-rata surcharged amount.


Available endpoints

Payments

Payment retrieval