Breadcrumbs

REST API eDCC

eDCC (Electronic Dynamic Currency Conversion) allows cardholders to choose whether a card payment is processed in the merchant’s transaction currency or in the cardholder’s billing currency.

The NEXI REST API supports eDCC in two models:

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

  • Direct model (merchant-controlled UI): the merchant retrieves eligibility and pricing via REST “DCC Services” and presents the currency choice in their own checkout UI. The merchant then submits the cardholder’s decision in the REST payment request.

This page explains how to use eDCC 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 eDCC in REST integrations:

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

  • Ensure your merchant configuration supports card-based eDCC.


Integration options

The eDCC is available in all 3 integration types:

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

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

  • Direct integration (Merchant UI): Use REST DCC services to retrieve a quote, then execute the payment via REST including the cardholder’s DCC decision.


Payment flow user experience

Scenario 1: DCC is not offered (domestic card, disabled, not eligible)

  • The checkout proceeds in the merchant currency.

  • No DCC-related information is shown.

Scenario 2: DCC is offered and cardholder opts out

  • The merchant shows both currency options.

  • The cardholder selects the merchant currency.

  • The payment proceeds in the merchant currency.

Scenario 3: DCC is offered and cardholder opts in

  • The merchant shows both currency options, including exchange rate and mark-up disclosure.

  • The cardholder selects the cardholder currency.

  • The payment proceeds in the cardholder currency.


Confirmation page / Pay slip requirements

After the payment is completed, the merchant’s confirmation page (receipt / pay slip) must reflect the option chosen by the cardholder.

If eDCC was selected

The confirmation page must display:

  • Final charged amount in the cardholder currency

  • Currency code (ISO 4217)

  • Exchange rate used

  • Exchange rate source

  • Exchange rate date (timestamp)

  • Mark-up information (where applicable)

  • A clear indication that currency conversion was applied (DCC)

The values displayed must match the DCC information returned by Paygate for the transaction.

If eDCC was declined or not offered

No DCC-related information must be displayed.


Using DCC services (Pre-Payment)

The following REST endpoints provide eDCC decisioning and quote. They do not execute a financial transaction.

BIN Lookup (optional)

Purpose

The BIN lookup allows merchants to pre-check whether a card may be eligible for eDCC based on:

  • Merchant configuration

  • Card issuing country derived from the BIN

This operation is optional and intended for early UI decisions.

Endpoint

  • POST /services/dcc/bin-check

Typical usage

  • Triggered when the customer enters the first 10 digits of the card number (BIN)

  • Used to decide whether it makes sense to request a DCC quote later

DCC quote

Purpose

The DCC quote provides the converted amount and DCC metadata required to present a compliant currency choice to the cardholder.

Endpoint

  • POST /services/dcc/quote

Typical usage

  • Triggered once the merchant has the transaction amount and currency

  • The returned values are displayed to the cardholder

  • The returned quote reference is used when executing the payment (direct model)


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 eDCC processing and displays the DCC choice (if eligible).

Endpoints

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

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

Merchant control

Customer experience

  • Paygate displays DCC information and collects the cardholder choice inside the hosted card step.

Direct model (merchant-controlled UI)

In the direct model, the merchant controls the checkout UI and must:

  • Present the DCC offer (if applicable)

  • Collect explicit opt-in / opt-out

  • Submit the decision when executing the payment

Endpoint

  • POST /payments (direct card payment)

How to apply DCC in the payment request

  • If DCC was not offered, execute the payment normally in merchant currency.

  • If DCC was offered, include the cardholder’s choice in the direct card payment request:

    • Opted in → include DCC selection and quote reference from POST /services/dcc/quote

    • Opted out → include the DCC decision as declined (if your integration sends a DCC object when offered)

Paygate resolves DCC details internally based on the quote reference and the cardholder’s decision.


Retrieve payment details (Result & DCC outcome)

Payment details, including DCC 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 DCC 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 DCC handling is resolved internally by Paygate.


Compliance notes (Merchant-controlled UI)

If the merchant controls the checkout UI (direct model), the merchant is responsible for displaying DCC information to the cardholder in a clear and compliant manner, including:

  • Showing both currency options at the same time

  • Ensuring the DCC option is not pre-selected

  • Displaying exchange rate, source and mark-up information where applicable

  • Ensuring explicit cardholder consent


Available endpoints

DCC services

Payments

Payment retrieval