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.

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.

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

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	Unique Request ID in the merchant’s system.	N
clientUniqueId	Unique transaction ID in the merchant's system.	N
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
userPaymentOptionId	Payment 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
apm	Payment method (one of these must be provided: paymentOption.userPaymentOptionId or cardNumber or apm). See APM Input Fields for details.	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

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)
    })
}