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
- 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.
- 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:
- Check that the customer’s home currency is one of your registered DCC currencies.
- To retrieve the
markUpValue
(as specified in your DCC agreement with Nuvei), the convertedamount
and therateValueWitMarkUp
.
/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
block (containing originalAmount
and originalCurrency
) inside the /payment
request in your existing workflow:
Example currencyConversion
Block
"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.