• Documentation
  • API Reference
  • Documentation
  • API Reference
Expand All Collapse All
  • Payment Overview
    • Introduction
    • Choosing an Integration Method
  • Accept Payment
    • Payment Page
      • Quick Start
      • Input Parameters
      • Output Parameters
    • Web SDK
      • Quick Start
      • Nuvei Fields
        • Styling
      • Additional Functions
      • APM Payments
      • Tokenization-Only Flow
      • Scenarios
      • Using ReactJS
        • Full Samples
        • Sandbox Examples
      • FAQs
    • Checkout
      • Quick Start
        • UI Customization
        • Payment Customization
        • Advanced Controls
        • Checkout Examples
      • Server-to-Server
      • Payment Scenarios
      • Mobile SDKs (Beta Release)
        • Android Mobile SDK (Beta Release)
        • iOS Mobile SDK (Beta Release)
      • Flow Diagrams
      • Plugins
        • Magento
          • Rebilling with Magento
        • WooCommerce
          • Rebilling with WooCommerce
        • PrestaShop
          • PrestaShop with Web SDK
          • PrestaShop with Checkout
        • OpenCart
        • Shopify (via AsiaBill)
        • Mirakl
        • Salesforce
        • SAP
        • WIX
      • Marketplaces
    • Features
      • Authentication
      • Financial Operations
        • Refund
        • Void
        • Auth and Settle
        • Partial Approval
        • Currency Conversion (DCC and MCP)
        • Payout
      • Card Operations
        • Card-on-File
        • PCI and Tokenization
        • Zero-Authorization
        • Merchant-Initiated Transactions (MIT)
        • Blocking Cards
      • Subscription (Rebilling)
      • 3D-Secure
        • 3D-Secure Explained
        • 3DS Implementations
          • 3DS MPI-Only Web SDK
          • 3DS MPI-Only REST
          • 3DS External MPI
          • 3DS Responses
        • 3DS Functions
          • 3D-Secure Fingerprinting
          • 3D-Secure Authentication Challenge
      • Webhooks (DMNs)
        • Payment Transaction Requests
        • Control Panel Events API
    • Guides
      • Testing Cards, APIs and APMs
        • Testing Cards
        • Testing APIs with Postman
        • Testing APMs
      • Response Handling
      • Alternative Payment Guides (APMs)
      • Airline Ticket Guides
        • Airline Addendum
        • External Authorization Addendum
      • Payment Facilitators (PayFac)
      • Cashier
        • Cashier Events Guide
        • Cashier Features
      • Withdrawal Guide
      • Risk Guide
        • Nuvei Services
        • Transaction Types
        • Credits and Payouts
        • Fraud to Sale Programs
        • Compliance Programs
        • Chargebacks
      • eKYC Guide
      • Server SDKs
        • Java SDK
        • .NET SDK
        • PHP SDK
        • Node.JS SDK
      • Fast Track Onboarding Developer Guide
      • Currency Conversion Guides
        • Multiple Currency Pricing (MCP)
        • Dynamic Currency Conversion (DCC)
          • DCC in Cashier or Payment Page
          • DCC in REST API Workflows
          • DCC in Web SDK Workflows
      • Website Compliance Guides
    • Additional Links
      • FAQs
      • API Reference
      • Release Notes
      • Country and Currency Codes

    DCC in Web SDK Workflows

    On this page:
    • Overview
    • 1. Initiate a Session
    • 2. Collect Payment Details
    • 3. Calling setOpenAmount()
    • 4. Get the DCC Details
    • 5. Create the Payment
    • 6. Verify the Response
    • Full ​JavaScript Example

    Overview

    If your payment workflow uses our Web SDKs, then integrating DCC is relatively simple because the regular payment workflow remains unchanged, with a few additional steps, as described below.

    (This topic refers to steps in the Web SDK – Quick Payment Integration workflow.)

    1. Initiate a Session

    The customer begins the checkout process as usual by clicking “Pay” (or “Go to Payment” or a similar button).

    Call the /openOrder method on the server side, (see the Initiate a Session topic).
    This authenticates and sets up an order in the Nuvei system, and returns a sessionToken.

    2. Collect Payment Details

    Perform these steps (click the links below for details of each step):

    1. Import the Web SDK Library.
    2. Generate the Payment Form.
    3. Present a form to the customer so that they can select a payment method, or enter their cardholder details.
      For instructions, see the Activate Nuvei Fields topic.

    3. Calling setOpenAmount()

    This is an optional step.

    This feature supports merchants who operate in industries where the payment amount is not known at the beginning of the payment flow, or where a payment amount needs to be updated on the client-side device, for example the gambling industry.
    Note: Before using this feature, contact Nuvei Support to enable the openAmount feature in your merchant account configuration.
    This is required because changing the amount is normally only performed using server-side APIs.

    If you want to change the amount that was originally set in the /openOrder to a new amount (in the same currency), then you can call the setOpenAmount() function. For example, if customer changes the items in their order, etc.

    You can only call the setOpenAmount() method before calling the clientGetDccDetails() or the  createPayment() requests.

    Example setOpenAmount() Request
    sfc.setOpenAmount({
         clientRequestId:"<unique request ID in merchant system>",
         clientUniqueId:"<unique transaction ID in merchant system>",     
         amount:"156"
    }, function(crRes) {
         console.log(crRes);
    });

    4. Get the DCC Details

    Call the clientGetDccDetails() Web SDK method to retrieve DCC details to display to the customer.

    This method calculates the DCC transaction amount and rateValueWithMarkup based on the selected payment method and target currency, and the original amount and currency provided in the /openOrder call.

    clientGetDccDetails() Input Parameters
    ParameterDescriptionMandatory
    sessionTokenSession identifier returned by /getSessionToken.Y
    merchantIdMerchant ID provided by Nuvei.Y
    merchantSiteIdMerchant Site ID provided by Nuvei.Y
    clientRequestIdUnique Request ID in the merchant’s system.N
    clientUniqueIdUnique transaction ID in the merchant's system.N
    cardNumberPayment method (one of these must be provided: paymentOption.userPaymentOptionId or cardNumber or apm).

    The cardNumber can be provided in one of these ways:
    • "Nuvei Fields" Card - Use a previously created Nuvei Fields card.
    • (For PCI accredited merchants) - Provide the "clear text" cardholder information.
    Conditional
    userPaymentOptionIdPayment method (one of these must be provided: paymentOption.userPaymentOptionId or cardNumber or apm).

    The userPaymentOptionId is the identifier of a customer's tokenized payment method. It must be used together with a userTokenId parameter.
    Conditional
    apmPayment method (one of these must be provided: paymentOption.userPaymentOptionId or cardNumber or apm).
    See APM Input Fields for details.
    Conditional
    currencyConversion currency.
    (Target currency or target country must be provided. If both are provided then currency takes precedence.)
    Conditional
    countryConversion country.
    (Target currency or target country must be provided. If both are provided then currency takes precedence.)
    Conditional
    Example clientGetDccDetails() Request
    sfc.clientGetDccDetails({
        cardNumber: nf_card, //Nuvei Fields element reference
        currency: "GBP"
    }, function(dccRes) {
        console.log(dccRes);
    });
    Example clientGetDccDetails() Response – SUCCESS
    {
      amount: "7.58",
      clientRequestId: "1656272959945313",
      currency: "GBP",
      dccFullSupport: "true",
      errCode: 0,
      internalRequestId: 17058931,
      merchantId: "8256777005602846935",
      merchantSiteId: "112106",
      originalAmount: "10",
      originalCurrency: "USD",
      rateValueWitMarkUp: "0.7579",
      reason: "",
      sessionToken: "5071b042-fc6c-4f62-af10-2fbccf3d0cd2",
      status: "SUCCESS",
      version: "1.0"
    }

    If the request fails, then the transaction is rejected and returns "result": "ERROR", and the relevant errorCode and errorDescription.
    The example below shows errCode: 2006, which is returned when the payment method does not support DCC. (This error can sometimes be caused by other reasons.)

    Example clientGetDccDetails() Response – ERROR
    {
      clientRequestId: "5421874822453359",
      dccFullSupport: "false",
      errCode: 2006,
      internalRequestId: 17058901,
      merchantId: "8256777005602846935",
      merchantSiteId: "112106",
      reason: "Currency conversion is not supported",
      sessionToken: "5071b042-fc6c-4f62-af10-2fbccf3d0cd2",
      status: "ERROR",
      version: "1.0"
    }

    5. Create the Payment

    Perform the next step based on the response from the clientGetDccDetails() request (above):

    If the issuing bank supports DCC for the card:

    If the clientGetDccDetails() request returns dccFullSupport: "true", then the issuing bank supports DCC for that card.

    Present the DCC details to your customer, and offer them the option to pay in their home currency, by accepting the DCC payment option.

    • If the customer accepts the DCC option, then send a createPayment() request, and include the "useDCC":"true" input parameter.

      At this point, the createPayment() request cannot be used to change the transaction amount, (because you will be including the useDCC parameter in the request).
      However, if you need to change the transaction amount at this point, then go back and perform the Set the Open Amount step (see above), followed by the Get the DCC Details step again, and continue from there.

      Example createPayment() Request with "useDCC":"true"
      sfc.createPayment({
          "userTokenId": "<unique customer identifier in merchant system>",
          "clientUniqueId": "<unique transaction ID in merchant system>", // optional
          "cardHolderName": "John Smith",
          "paymentOption": scard,
          "useDCC": true,   //if not using "useDCC" then you can use "openAmount" and visa versa.
          "billingAddress": {
              "email": "john.smith@email.com",
              "country": "US"
          }
      }, function(res) {
          console.log(res);
          document.getElementById('result').innerHTML = JSON.stringify(res, null, 4)
      })
      }
    • If the customer does not accept the DCC option, then perform the transaction without DCC, by sending a createPayment() request without the useDCC parameter, (or set "useDCC":"false").
    If the issuing bank does not support DCC for the card:

    If the clientGetDccDetails() request returns dccFullSupport: "false", then the issuing bank does not support DCC for that card.

    Do one of the following:

    • Perform the transaction without DCC, by sending a createPayment() request without the useDCC parameter, (or set "useDCC":"false").

      At this point, if you need to change the transaction amount, you can simply include this, "openAmount": "<new amount>", in the createPayment() request to set a new amount. (You cannot change the currency.)
      Note: This feature supports merchants who operate in industries where the payment amount is not known at the beginning of the payment flow, or where a payment amount needs to be updated on the client-side device, for example the gambling industry.
      Before using this feature, contact Nuvei Support to enable the openAmount feature in your merchant account configuration.
      This is required because changing the amount is normally only performed using server-side APIs.

    • If the customer still wants to pay in their home currency, then:
      • You can still choose to allow the customer to use DCC, by sending a createPayment() request, and include the "useDCC":"true" input parameter, as shown in the example above.
      • Alternatively, you can choose to end this payment flow, and somehow re-start the payment flow again (from the first step, /openOrder), this time using the customer’s home currency and a (manually) converted amount.

    6. Verify the Response

    You can verify the response from thecreatePayment() request in one of these ways:

    • Send a /getPaymentStatus API request from your server-side using the sessionToken (returned from the /openOrder.)

      The /getPaymentStatus can only be called while the session in which the payment was performed is still open. Once the session expires, you receive a “session expired” response.

      The /getPaymentStatus method can only be called at the end of payment processing for that payment.
      (You can detect the end of payment processing by monitoring the JavaScript events for the final transaction event.)
      /getPaymentStatus is not intended for repeated status polling during the payment processing. Doing so may result in your IP address being blocked.

    • Alternatively, you can use our Direct Merchant Notification (DMN) system, which sends a direct notification to a webhook endpoint on your system.

    Full ​JavaScript Example

    var show = function(elem) {
        elem.classList.add('is-visible');
    };
    var hide = function(elem) {
        elem.classList.add('is-hide');
    };
    
    function initSDK() {
        // SDK initiation function – for full spec please refer to the Nuvei SDK chapter
        hide(document.getElementsByClassName('webSDK-placeholder')[0]);
        show(document.getElementsByClassName('toggle-content')[0]);
        if(window.scard) {
            window.scard.destroy();
        }
        var sfc = SafeCharge({
            env: 'int', // Nuvei API environment - 'int' (integration) or 'prod' (production - default if omitted)
            merchantId: "<as received from Nuvei>",
            sessionToken: "<as received from the openOrder API call>",
            merchantSiteId: "<as received from Nuvei>"
        });
        window.sfc = sfc
        var ScFields = sfc.fields({
            fonts: [{
                cssUrl: 'https://fonts.googleapis.com/css?family=Source+Code+Pro'
            }, ],
            locale: 'en'
        });
        var scard = ScFields.create('card', { /* stylize Nuvei fields here*/ });
        scard.attach(document.getElementById('card-field-placeholder'));
        window.scard = scard;
    }
    
    function main() {
        document.getElementById('result').innerHTML = '';
        sfc.clientGetDccDetails({
            cardNumber: scard,
            currency: "GBP"
        }, function(dccRes) {
            console.log(dccRes);
        });
        sfc.createPayment({
            "userTokenId": "230811147",
            "clientUniqueId": "695701003", // optional
            "cardHolderName": document.getElementById('cardHolderName').value,
            "paymentOption": scard,
            "useDCC": true,
            "billingAddress": {
                "email": "someone@somedomain.com",
                "country": "GB"
            }
        }, function(res) {
            console.log(res);
            document.getElementById('result').innerHTML = JSON.stringify(res, null, 4)
        })
    }
     
    Parameter Description Mandatory
    sessionToken Session identifier returned by /getSessionToken. Y
    merchantId Merchant ID provided by Nuvei. Y
    merchantSiteId Merchant Site ID provided by Nuvei. Y
    clientRequestId ID of the API request in merchant’s system. This value must be unique. N
    clientUniqueId The ID of the transaction in merchant system. N
    userPaymentOptionId Payment method (One of these must be provided: paymentOption.userPaymentOptionId or cardNumber or apm).
    The userPaymentOptionId is the customer’s tokenized payment method.
    Include the paymentOption.userPaymentOptionId and the userTokenId fields. This identifies the customer and ensures that the APM is indeed linked to that customer.
    Conditional
    cardNumber Payment method (One of these must be provided: paymentOption.userPaymentOptionId or cardNumber or apm).
    The cardNumber can be provided in one of these ways:
    • “Nuvei Fields” Card – Use a previously created Nuvei Fields card.
    • (For PCI accredited merchants) – Provide the “clear text” cardholder information.
    Conditional
    apm Payment method (One of these must be provided: paymentOption.userPaymentOptionId or cardNumber or apm). Conditional
    currency Conversion currency.
    (Target currency or target country must be provided. If both are provided then currency takes precedence.)
    Conditional
    country Conversion country
    (Target currency or target country must be provided. If both are provided then currency takes precedence.)
    Conditional

     

    2022 Nuvei. All rights reserved.