Dynamic Currency Conversion (DCC) Learn about DCC and how you can offer it to your customers

What is DCC?

DCC is a process whereby the amount of a card transaction is converted to the currency of the card's country of issue at the time of payment. A simple example would be a US student using their US issued credit card while on vacation in the UK. DCC would allow the student to pay in US Dollars as opposed to British Pounds.

DCC usually adds a markup to the used exchange rate to cover the currency exchange service and its associated risks. When this DCC markup is less than the card issuer's currency conversion fee, DCC can benefit card holders by allowing them to see the amount that their card will be charged expressed in the currency of the card's country of issue.

Integration

1. Get DCC offer

If you want to offer DCC to your customers you can check eligibility and the offered exchange rate by calling transaction.getDccQuote.

For this check only the first 6 digits of the card (called the BIN or IIN) are relevant. This is why we suggest to send dummy data for the other values of the funding instrument.

{
  "jsonrpc": "2.0",
  "method": "transaction.getDccQuote",
  "params": {
    "merchant_id": 3,
    "currency": "USD",
    "amount": 2000,
    "funding_instrument": {
      "type": "credit_card",
      "number": "424242 0000000000",
      "expires": "2030-12",
      "cvc": "123",
      "holder": "Not Relevant"
    }
  },
  "id": 1
}
{
  "jsonrpc": "2.0",
  "result": {
    "success": true,
    "currency": "USD",
    "amount": 2000,
    "amount_formatted": "$20.00",
    "quote": {
      "currency": "GBP",
      "amount": 1660,
      "amount_formatted": "\u00a316.60",
      "exchange_rate": 0.83,
      "conversion_margin": "5.00%"
    },
    "reference": "eyJhbGciOiJIU...9g-B-FYAa_YfEAcyjI"
  },
  "id": 1
}
{
  "jsonrpc": "2.0",
  "result": {
    "success": false,
    "error": "The transaction currency is already in the funding instrument's home currency"
  },
  "id": 1
}

To make the integration as seamless as possible we recommend to collect the card number as the first thing in the form and then use JavaScript to watch for key inputs to the card number form element. Once 6 digits are available an asynchronous call to transaction.getDccQuote, likely proxied through your application server, can be made.

2. Offer DCC to your customer

In case DCC is available (success is true in the response) you should update your payment form to offer your customer payment in their home currency (quote.amount_formatted).

Please note: The customer must be able to choose the original currency and decide against using DCC. Additionally you must show the used exchange rate (quote.exchange_rate) and link to Payyo's Terms of Services.

If DCC is not available (success is false) you can handle the payment just as if DCC wouldn't be offered or implemented by your system. No additional information needs to be shown to the customer and no additional data needs to be sent to Payyo.

3. Use DCC during authorization

If DCC was available and the customer decided to use it, you must send the DCC quote reference (reference) along with the authorization call (for example the dcc_quote_reference field on transaction.initiate).

{
  "jsonrpc": "2.0",
  "method": "transaction.initiate",
  "params": {
    "merchant_id": 3,
    "merchant_reference": "order_123",
    "currency": "USD",
    "amount": 2000,
    "return_urls": {
      "success": "https://example.org/success",
      "fail": "https://example.org/fail",
      "abort": "https://example.org/abort"
    },
    "funding_instrument": {
      "type": "credit_card",
      "number": "4242 4242 4242 4242",
      "expires": "2021-04",
      "cvc": "032",
      "holder": "John Doe"
    },
    "dcc_quote_reference": "eyJhbGciOiJIU...9g-B-FYAa_YfEAcyjI"
  },
  "id": 1
}

Please note: Do not change the currency or amount of the authorization request. The same values that were used for the DCC quote must be sent again. Otherwise Payyo will respond with an error. The sent DCC quote reference will be used to look up the agreed upon exchange rate and it will be applied before charging the card.