Currency Conversion

Introduction

When a transaction is made from an account that is in a different native currency than the merchant, there are two ways that currency conversion can happen:

• At the time the transaction is cleared, this is the standard way and relies on no up-front configuration
• At the time the transaction is authorised, which is done using a process called DCC (Dynamic Currency Conversion)

Our APIs offer the ability to achieve both, but for context, why would someone want to use DCC?

Pros

• It offers visibility to the consumer at time of sale in their native currency for improved transparency
• The exchange rate is locked in at the time of transaction

Cons

• The rate is usually less favourable, resulting in a higher transaction cost to the consumer

Payments API

The two types of dynamic currency conversion requests that can be used via the APIs are defined, similar to transactions, via the requestType field:

• DCCExchangeRateRequest - Use 'Dynamic Currency Conversion' to select the optimal currency conversion and apply that
• DynamicPricingExchangeRateRequest - Request a listing of available exchange rates

1. Getting a dcc rate

The first step is to call the exchange-rates endpoint with one of the above requestType options.

// POST /exchange-rates
{
  "requestType": "DCCExchangeRateRequest",
  "baseAmount": "12.32",
  "bin": "411111" // <-- the bin here tells us which currency is used
}

{
  "clientRequestId": "30dd879c-ee2f-11db-8314-0800200c9a66",
  "apiTraceId": "rrt-0bd552c12342d3448-b-ea-1142-12938318-7",
  "requestTime": 1592912760,
  "exchangeRateDetails": {
    "inquiryRateId": 49150, // <-- reference for later use in the transaction
    "foreignCurrency": "NOK",
    "foreignAmount": 130.33,
    "exchangeRate": 10.2968,
    "dccOffered": "true",
    "marginRatePercentage": "3",
    // ...
  }
}

// POST /exchange-rates
{
  "requestType": "DynamicPricingExchangeRateRequest",
  "baseAmount": "12.32",
  "foreignCurrency": "USD"
}

2. Using the dcc rate

Using the inquiryRateId provided in the response (see the above example), we can supply this in a transaction request to utilise the given exchange rate. The value must be provided in the currencyConversion field object.

// POST /payments
{
  "requestType": "PaymentCardSaleTransaction",
  "transactionAmount": {
    "total": "130.33",
    "currency": "NOK"
  },
  "paymentMethod": {
    "paymentCard": {
      "number": "5424180279791732",
      "securityCode": "977",
      "expiryDate": {
        "month": "12",
        "year": "24"
      }
    }
  },
  "currencyConversion": {
    "conversionType": "Dcc",
    "inquiryRateId": "49150",
    "dccApplied": true
  }
}

👍

Example complete!

If the inquiryRateId was supplied correctly and the resulting transaction was approved, this is now complete. Bear in mind that the given inquiryRateId is valid for TODO (add how long this is valid for).

Hosted Payment Page

If you use hosted forms for the payment process in your webshop and your store has been activated for this product option, a currency choice is automatically provided to your customers if the card they use has been issued in a country with a currency that is different to your default currency.

🚧

Note

Please note, that for compliance reasons Currency Conversion can only be offered on transactions that take place in full at that time (e.g. Sale, Refund) and not on any delayed settlement (e.g. pre/post auth, recurring) due to the fluctuation of the rate of exchange.