Dynamic Currency Conversion (DCC) enhances the online shopping experience by allowing customers to choose between paying in the merchant's currency or their own card's currency. This feature provides transparency in pricing and empowers customers to make informed decisions, eliminating surprises in conversion rates or additional fees on their card statements.

📘

DCC is only possible if the merchant configuration and the card supports it!

Please note that in some scenarios, DCC may not be possible, due to your selected currency and card used during the checkout. Please be aware that DCC will only be possible if the following apply:

• The merchant configuration supports DCC
• The card supports DCC
• The combination of the card's currency and the requested transaction currency both are not equal

Quick Integration: Redirect, Lightbox & Mobile SDK

For Redirect & Lightbox and Mobile SDK integrations, no modifications to your existing integration will be needed. The feature can be enabled globally by updating your merchant settings, making it easy to adopt with minimal effort.

DCC automatically detects the issuing country of the customer's card. If the card is eligible, it presents a currency conversion screen using Planet's latest exchange rates. Customers can select their preferred currency and review the converted rate before purchasing, ensuring a seamless and transparent payment experience.

Secure Fields Integration

To support Dynamic Currency Conversion (DCC) with Secure Fields, a few simple changes are required to your Secure Fields integration. These steps allow you to detect eligible cards, present a clear currency choice to the customer, and resubmit the transaction with their selected currency.

Initializing transactions

Start by creating a transaction via the secureFieldsInit endpoint. This is identical to non-DCC flows. This returns a transactionId which you will use to initialize Secure Fields on your frontend.

curl 'https://api.sandbox.datatrans.com/v1/transactions/secureFields' \
-H 'Authorization: Basic {basicAuth}' \
-H 'Content-Type: application/json' \
-d '{
	"amount": 100,
	"currency": "CHF",
	"returnUrl": "{returnUrl}"
}'

Initializing our Javascript library

Once you have a valid transactionId, initialize Secure Fields as usual This time, however, enable DCC explicitly in the options with dccEnabled.

secureFields.init(
  "transactionId",
  {
    cardNumber: "card-number",
    cvv: "cvv-number"
  },
  {
    dccEnabled: true,
    // other options
  }
);

Submit and listen for dccAvailable

Submit the card information once ready with secureFields.submit(). Listen for the DCC event.

secureFields.submit({
  expm: 6,
  expy: 25
});

If the dccAvailable event fires, you must prompt the customer to make a choice. You need to use the data.dcc object to display a clear currency comparison in your frontend.

secureFields.on('dccAvailable', function (data) {
  // your logic to show the DCC options with data.dcc.*
});

To remain compliant with scheme rules and provide pricing transparency, you will need to show the following information during DCC selection. This ensures transparency and helps you remain compliant with scheme rules. You are responsible for formatting the amount with its decimal places with originalDecimalPlaces and dccDecimalPlaces. Do not preselect a currency for them. Show both options equal (eg. not highlighting one and making the other less favourable).

Submit the currency choice

After the customer makes a choice, call secureFields.submit() again, this time passing the selected currency via dccSelected. Set dccSelected to true if the user chose their card currency, which will charge the card with the DCC option. You can choose whether this step happens automatically after their currency selection, or if they require an additional "Confirm" click. This depends entirely on your UX preference.

secureFields.submit({
  expm: 6,
  expy: 25,
  dccSelected: true
});

After this second submission, the integration proceeds as in the normal Secure Fields flow, as documented in the Secure Fields success flow.

Advanced integration with your forms

If you are a merchant who wants to display the DCC choice for stored PANs in your checkout, follow the steps below. After collecting the PAN, you must call an additional API to access a given card's DCC eligibility and available currency options. After receiving these details, you can continue with the payment flow. Depending on your desired processing, various flows will be possible.

Retrieving DCC details

Call our DCC endpoint with the token or PAN, currency, and amount. Our response will include details on whether the card is eligible for DCC and the DCC details.

curl 'https://api.sandbox.datatrans.com/v1/transactions/dcc' \
-H 'Authorization: Basic {basicAuth}' \
-H 'Content-Type: application/json' \
-d '{
	"cardNumber": "{cardNumber}",
	"currency": "CHF",
	"amount": 100
}'

{
 "dccAvailable": true,
  "originalOption": {
    "amount": 100,
    "currency": "CHF",
    "exponent": 2
  },
  "dccOption": {
    "amount": 107,
    "currency": "USD",
    "exponent": 2
  },
  "baseRate": "wholesale",
  "rate": 1.06015,
  "margin": 2.97
}

DCC with 3D Secure via Redirect & Lightbox

Merchants who only want to process 3DS with the DCC preselection previously retrieved within their frontend can now call the init endpoint with the returned DCC information. This will skip the payment method entry on our payment forms while still processing 3D Secure. The object dcc contains a property for the DCC currency, amount, and rate you must pass in your payload.

"dcc": {
  "currency": "USD",
  "amount": "107",
  "rate": "1.06015"
}

DCC without 3D Secure

When processing either a token or a PAN through our authorize endpoint, similar to the above examples you can also specify the DCC details in the object dcc.

"dcc": {
  "currency": "USD",
  "amount": "107",
  "rate": "1.06015"
}