Overview

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

(This section assumes that a session has already been initiated as part of a regular payment workflow. For details, see the Authentication topic.)

1. Collect Payment Details

1. The customer begins the checkout process as usual by pressing a “Checkout” (or “Go to Payment” or a similar) button, and selects a payment method.
2. As part of the regular payment workflow, call the /getCardDetails method, to retrieve the card details, and check if the payment method allows DCC transactions (dccAllowed: true).
   
   

   Example /getCardDetails Request

   {
      "sessionToken":"<received from getSessionToken>",
      "merchantId":"<your merchantId>",
      "merchantSiteId":"<your merchantSiteId>",
      "clientRequestId":"<unique request ID in merchant system>",
      "clientUniqueId":"<unique transaction ID in merchant system>",
      "cardNumber":"4017356934955740"
   }

   Example /getCardDetails Response

   {
       "brand": "VISA",
       "cardType": "Credit",
       "program": "Visa Platinum",
       "visaDirectSupport": "0",
       "issuerCountry": "pe",
       "currency": "pen",
       "dccAllowed": true,
       "sessionToken": "eaeed493-6ed1-4e44-9cc9-7e698efe51e2",
       "internalRequestId": 212986558,
       "status": "SUCCESS",
       "errCode": 0,
       "merchantId": "2502136204546424962",
       "merchantSiteId": "126006",
       "version": "1.0",
       "clientRequestId": "1C6CT7V1L"
   }

2. Get the DCC Details

If the payment method allows DCC transactions (dccAllowed: “true“) (the issuer supports DCC conversion). However, even if  dccAllowed: “false” you can still decide to apply DCC to the payment. To continue the DCC conversion, use the /getDccDetails method to:

1. Check that the customer’s home currency is one of your registered DCC currencies.
2. To retrieve the markUpValue (as specified in your DCC agreement with Nuvei), the converted amount and the rateValueWitMarkUp.
   
   

   /getDccDetails Request

   {
       "sessionToken": "<received from getSessionToken>",
       "merchantId": "<your merchantId>",
       "merchantSiteId": "<your merchantSiteId>",
       "clientRequestId": "<unique request ID in merchant system>",
       "clientUniqueId": "<unique transaction ID in merchant system>",
       "cardNumber": "4473146022489737",
       "originalAmount": "15",
       "originalCurrency": "GBP",
       "currency": "EUR"
   }

   /getDccDetailsResponse

   {
       "rateValueWithMarkUp": "1.236739013895",
       "markUpValue": "0.05",
       "amount": "18.551085208425",
       "currency": "EUR",
       "originalAmount": "15",
       "originalCurrency": "GBP",
       "sessionToken": "eaeed493-6ed1-4e44-9cc9-7e698efe51e2",
       "clientUniqueId": "695701003",
       "internalRequestId": 214036488,
       "status": "SUCCESS",
       "errCode": 0,
       "dccFullSupport": "true",
       "merchantId": "2502136204546424962",
       "merchantSiteId": "126006",
       "version": "1.0",
       "clientRequestId": "1C6CT7V1L"
   }

3. Create the Payment

If the customer’s home currency is one of your registered DCC currencies, then you can offer the DCC payment option to the customer, using the DCC details returned (highlighted in the example above).

If the customer accepts the DCC option, to pay in their home currency, then include the currencyConversion class (containing originalAmount and originalCurrency) inside the /payment request in your existing workflow:

Example currencyConversion Class

"currencyConversion": {
    "type": "DCC",
    "originalAmount": "15",
    "originalCurrency": "GBP"
}

Example /payment Request

{
    "sessionToken": "<received from getSessionToken>",
    "merchantId": "<your merchantId>",
    "merchantSiteId": "<your merchantSiteId>",
    "clientRequestId": "<unique request ID in merchant system>",
    "timeStamp": "<YYYYMMDDHHmmss>",
    "checksum": "<calculated checksum>",
    "amount": "18.551085208425",
    "clientUniqueId": "<unique transaction ID in merchant system>",
    "currency": "EUR",
    "paymentOption": {
        "alternativePaymentMethod": {
            "paymentMethod": "apmgw_Neteller",
            "nettelerAccount": "453313818311",
            "nettelerSecureId": "173419"
        }
    },
    "currencyConversion": {
        "type": "DCC", 
        "originalAmount": "15",
        "originalCurrency": "GBP"
    },
    "billingAddress": {
        "email": "[email protected]",
        "country": "DE"
    },
    "deviceDetails": {
        "ipAddress": "<customer's IP address>"
    },
    "urlDetails": {
        "notificationUrl": "<URL to which DMNs are sent>"
    }
}

When the Nuvei gateway receives your /payment request, it recalculates and validate the DCC values.