Using Global Blue DCC with the Web SDK

If you take card payments with the Web SDK (a Hosted Session integration), you can offer dynamic currency conversion (DCC) on your own card form. When a customer enters a card issued in another currency, the SDK offers them a choice: pay in AED, or pay in their card's currency at a rate from Global Blue. Their choice travels with the session, so your server makes the payment call exactly as it does today.

Which customers and cards are offered DCC, and what happens on captures and refunds, is set out in Global Blue Dynamic Currency Conversion (DCC).

What you need

• A working Web SDK integration. DCC is added to the mountCardInput call you already make. There is no new script and no new API key.
• DCC switched on for your outlet. Network International does this for you. Ask your relationship manager.
• Orders in AED. DCC is offered on AED orders only, on Visa and Mastercard cards.

What you add

1. Two options in mountCardInput: dccEnabled: true, and orderDetails, the amount and currency of the order.
2. A container on your page for the DCC choice screen.
3. Two callbacks: onTriggerDCC, which shows the choice screen, and onCompleateDcc, which tells you what the customer chose.

Your server code does not change.

How it works

1. You mount the card input with dccEnabled: true and the order details.
2. The customer enters a card number. The SDK looks up the card's currency and a rate for the order amount.
3. If the card's currency is not the order's, the SDK calls onTriggerDCC with the offer. If it is the same, nothing happens and the customer pays as usual.
4. You call NI.handleDCCFlow with the offer. The SDK shows the choice screen in your container: a button for each currency, the exchange rate, the markup where there is one, and the text the customer confirms.
5. The customer chooses. The screen closes and onCompleateDcc gives you their choice.
6. When the customer pays, NI.generateSessionId() adds the choice to the session. Your server sends the payment with the session ID, as before, with no extra fields.

Example

Add a container for the choice screen next to your card input. Keep it hidden until an offer arrives.

<div id="mount-point"></div>
<div id="dcc-modal" style="display:none">
  <div id="dcc-mount" style="height: 400px"></div>
</div>

Then add the DCC options and callbacks to mountCardInput.

window.NI.mountCardInput('mount-point', {
  apiKey,                // your Hosted Session API key
  outletRef,             // your outlet reference
  language: 'en',
  dccEnabled: true,
  orderDetails: { amount: orderAmount, currency: 'AED' }, // amount in minor units: 3000 is AED 30.00
  orderAction: 'PURCHASE', // or 'AUTH', the action your server will send

  onTriggerDCC: async dccData => {
    document.getElementById('dcc-modal').style.display = 'block';
    try {
      const choice = await window.NI.handleDCCFlow({
        config: { mountId: 'dcc-mount', orderAction: 'PURCHASE' },
        dccData // pass the payload on unchanged
      });
      // choice = { isDccSelected, globalBlueId }
    } finally {
      document.getElementById('dcc-modal').style.display = 'none';
    }
  },

  onCompleateDcc: ({ isDccSelected, currencyCode, amount, formattedAmount }) => {
    // update your order summary, for example show formattedAmount
  },

  onSuccess,
  onFail,
  onChangeValidStatus
});

Options and callbacks

These are added to the mountCardInput arguments.

NI.handleDCCFlow shows the choice screen and returns a promise that resolves when the customer chooses.

The promise resolves with isDccSelected and, when the offer carried one, globalBlueId.

What the offer contains

The SDK shows the offer for you. If you also want to show the converted amount somewhere else on your page, it is in dccData.dccData.transactionInfo.

The offer's identifier, globalBlueId, sits beside transactionInfo, not inside it.

What onCompleateDcc returns

Good to know

• One offer per card number. If the customer edits the card number, their choice is cleared and a new offer may be shown.
• Language and style. The choice screen follows your language setting (en, or ar, shown right to left) and your style object.
• Multi-currency pricing comes first. If the customer has already picked a currency through multi-currency pricing, DCC is not offered on top of it.
• No offer, no event. If there is no rate because the card is in AED, is not eligible, or the lookup fails, neither callback is called and the customer pays in AED.
• Offers expire.

After the payment

Captures, voids and refunds work as they do for any DCC payment. Send amounts in AED, and refunds are always made in AED. See Captures, voids and refunds.

Test before you go live

• A card in another currency shows the choice screen, and a card in AED does not.
• Choosing either currency closes the screen and calls onCompleateDcc.
• Payments go through with both choices, and with AUTH as well as PURCHASE if you use both.
• Editing the card number after choosing clears the choice.
• A card that is not offered DCC still pays in AED.

Related

• Web SDK Integration Guide
• Web SDK API Reference
• Using MCP (Multi-Currency Pricing) with the WebSDK
• Global Blue Dynamic Currency Conversion (DCC)