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.

1. Initiate a Session

The customer begins the checkout process as usual by pressinging “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 (press 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

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

Send a clientGetDccDetails() request with its mandatory parameters.

Example clientGetDccDetails() Request

sfc.clientGetDccDetails({
    //useFields: true, // alternative to cardNumber parameter
    cardNumber: "<cardNumber>", // either card number (for PCI-compliant merchants) or a BIN number OR use "useFields: true" instead of cardNumber
    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 are 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: "[email protected]",
          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 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 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({
        //useFields: true, // alternative to cardNumber parameter
        cardNumber: "<cardNumber>", // either card number (for PCI-compliant merchants) or a BIN number OR use "useFields: true" instead of cardNumber
        currency: "GBP"
    }, function(dccRes) {
        console.log(dccRes);
    });
    sfc.createPayment({
        "userTokenId": "230811147",
        "clientUniqueId": "695701003", // optional
        "cardHolderName": document.getElementById('cardHolderName').value,
        "useFields": "true", //" alternative to cardNumber and apm parameters
        "useDCC": true,
        "billingAddress": {
            "email": "[email protected]",
            "country": "GB"
        }
    }, function(res) {
        console.log(res);
        document.getElementById('result').innerHTML = JSON.stringify(res, null, 4)
    })
}