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):
- Import the Web SDK Library.
- Generate the Payment Form.
- 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:
| 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.
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 theuseDCC
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 theuseDCC
parameter, (or set"useDCC":"false"
). - 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.
- You can still choose to allow the customer to use DCC, by sending a
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 thesessionToken
(returned from the/openOrder
.)
- 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:
|
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 |