Dynamic Currency Conversion

Dynamic Currency Conversion (DCC) provides point-of-sale exchange rates to customers using a card issued in a currency other than the merchant’s base (or store) currency. For a more detailed explanation and step-by-step instructions, see our Dynamic Currency Conversion article.

In this API reference, we present an overview of each request type, examples of request and response values, as well as how to handle them.

The Rate Lookup request determines if a card is eligible for DCC. If so, it returns the most up-to-date exchange rate, along with additional currency conversion information.

If the card is not eligible for DCC or the currency of the card is the same as the merchant's base, a result code of 105 will be returned. In this case, you can proceed with a regular authorization without including any DCC information.

Sample request

<?xml version="1.0" encoding="UTF-8"?>
<request type="dccrate" timestamp="20180613173251">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>HUrD-jsFSniaul_g0_z4YA</orderid>
  <amount currency="EUR">1001</amount>
  <card>
    <number>4006097467207025</number>
    <expdate>1218</expdate>
    <chname>James Mason</chname>
    <type>VISA</type>
  </card>
  <!-- Begin DCC Elements -->
  <dccinfo>
    <ccp>Currency Conversion Processor</ccp>
    <type>1</type>
    <ratetype>S</ratetype>
  </dccinfo>
  <!-- End DCC Elements -->
  <sha1hash>30e37e11a44ff9eee125933bd48455991820a7d7</sha1hash>
</request>

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Sample response

<response timestamp="20180802120019">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>HUrD-jsFSniaul_g0_z4YA</orderid>
  <authcode/>
  <result>00</result>
  <message>Success</message>
  <pasref>14622680939731425</pasref>
  <timetaken>1</timetaken>
  <authtimetaken>0</authtimetaken>
  <cardissuer>
    <bank>ING BANK (AUSTRALIA) LIMITED</bank>
    <country>AUSTRALIA</country>
    <countrycode>AU</countrycode>
    <region>A/P</region>
  </cardissuer>
  <dccinfo>
    <cardholdercurrency>AUD</cardholdercurrency>
    <cardholderamount>1674</cardholderamount>
    <cardholderrate>1.6728</cardholderrate>
    <merchantcurrency>EUR</merchantcurrency>
    <merchantamount>1001</merchantamount>
    <marginratepercentage>03.0000</marginratepercentage>
    <exchangeratesourcename>Reuters Wholesale Interbank</exchangeratesourcename>
    <commissionpercentage>00.0000</commissionpercentage>
    <exchangeratesourcetimestamp>20180802 13:13</exchangeratesourcetimestamp>
  </dccinfo>
  <sha1hash>118b9d2dc037dfa5525dbaf409e828c51c2016e7</sha1hash>
</response>

Response syntax

Where the customer is offered a DCC choice, the authentication request requires the currency and amount the customer will pay. This is a requirement of 3D Secure (3DS) whereby the amount and currency authenticated should match the amount and currency authorized.

Where the customer declines the offer or is not offered DCC, the merchant amount and currency is all that is required.

Where the customer accepts the DCC offer, both the merchant amount and currency, and the customer amount and currency are required.

When 3DS2 is used with an authorization request requiring the customer to authenticate the card used in a transaction, populate the additional fields in the 3DS2 authentication request.

Sample request

"order": {
....
      "amount": "MerchantAmount",
      "currency": "MerchantCurrency",
....
      }
"currency_conversion": {
        "payer_amount": "CustomerChosenCurrencyAmount",
        "payer_currency": "CustomerChosenCurrency"

After the customer decides which currency they want to use, you can send the additional DCC information in your authorization request.

Sample request

<?xml version="1.0" encoding="UTF-8"?>
<request type="auth" timestamp="20180613173251">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>HUrD-jsFSniaul_g0_z4YA</orderid>
  <amount currency="EUR">100</amount>
  <card>
    <number>4006097467207025</number>
    <expdate>0424</expdate>
    <chname>James Mason</chname>
    <type>VISA</type>
    <cvn>
      <number>123</number>
      <presind>1</presind>
    </cvn>
  </card>
  <autosettle flag="1"/>
  <!-- Begin DCC Elements -->
  <dccinfo>
    <ccp>Currency Conversion Processor</ccp>
    <type>1</type>
    <rate>1.6728</rate>
    <ratetype>S</ratetype>
    <amount currency="AUD">167</amount>
  </dccinfo>
  <!-- End DCC Elements -->
  <sha1hash>0a9256911d62e42058abc0a72ceece3fa7e81ba3</sha1hash>
</request>

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Response syntax

Follow the steps in this section to build the request security hash, concatenate the specified fields and hash them using the SHA-1 algorithm, concatenate the hashed string with your Shared Secret, hash it again, and add the resulted string to the request.

Build the request hash

Follow the steps for the Rate Lookup request type.

1. Create a SHA-1 hash made up of request values

The blueprint of the hash for this request is:

"timestamp.merchantid.orderid.amount.currency.cardnumber"

Based on the XML example above our initial string will be:

"20200205093140.Merchant ID.N6qsk4kYRZihmPrTXWYS6g.1001.EUR.4263970000005262"

2. Concatenate the hashed string with your Shared Secret

After step 1, you'll have a string like: 28b85cd34d0e0d6b243d58f0e9f7f4bf7da1b882

You'll need to concatenate this with your Shared Secret, for example:

"28b85cd34d0e0d6b243d58f0e9f7f4bf7da1b882.Po8lRRT67a"

3. SHA-1 hash the concatenated string

Our final string that we add to the request should be a hash, using the SHA-1 algorithm, of your concatenated string. For example: 947903969e7aaf996164c680a6669805fe405269

Follow the steps in this section to build the response security hash, concatenate the specified fields and hash them using the SHA-1 algorithm, concatenate the hashed string with your Shared Secret, hash it again, and add the resulted string to the request.

Check the response hash

Follow the steps to check the response hash for the Rate Lookup request type.

1. Create a SHA-1 hash made up of response values

The blueprint of the hash for this response is:

"timestamp.merchantid.orderid.result.message.pasref.authcode"

So, based on the above example, the initial string to check the hash of the response will be:

"20200205093140.Merchant ID.N6qsk4kYRZihmPrTXWYS6g.00.Success.14631546336115597.12345"

2. Concatenate the hashed string with your Shared Secret

After step 1, you'll have a string like: 28b85cd34d0e0d6b243d58f0e9f7f4bf7da1b882

You'll need to concatenate this with your Shared Secret, for example:

"28b85cd34d0e0d6b243d58f0e9f7f4bf7da1b882.Po8lRRT67a"

3. SHA-1 hash the concatenated string

Our final string that we add to the request should be a hash, using the SHA-1 algorithm, of your concatenated string. For example: 947903969e7aaf996164c680a6669805fe405269

We create the hash in the same way on our side and send it back. To confirm that a response hasn't been tampered with, compare what you've generated with what was returned in the sha1hash element.