marcopolo Online payment
Sign up

Introduction

Our Electronic Dynamic Currency Conversion (eDCC) solution converts your currency transaction amount into the currency of your customers’ card's country of issue.

Using eDCC, you and your customers will benefit from:

  • Transparency - Your customers get a real-time view of their transaction amount in the currency they are familiar with, enabling them to make an informed purchase decision
  • Compliance – Implement automatically local regulations imposed by payment networks and local governments
  • Coverage - Follow-up on eDCC details via our API, Webhooks and Merchant Portal

We will be happy to help you get started!

eDCC is available for the following payment methods: 
MasterCard
Visa
via integration modes Hosted Checkout Page/Server-to-server/Mobile/Client Integration 

Apply eDCC

Make sure to contact us before using this feature, as we will have to preconfigure your account

The following properties enable eDCC for your order in a CreateHostedCheckout/CreatePayment request for Hosted Checkout Page/Server-to-server/Mobile/Client Integration integration modes:

Properties Remarks

cardPaymentMethodSpecificInput.
currencyConversionSpecificInput.
dccEnabled

dccEnabled: Set to "true" to enable eDCC

Mandatory for Hosted Checkout Page integration mode

transaction.amount
     amount
     currency

amount: The gross amount you want to charge for this order in your currency 

currency: The ISO 4217 currency code for this amount for your currency

Mandatory for Server-to-server / Mobile/Client Integration integration mode

cardPaymentMethodSpecificInput
    acceptedByUser
    dccSessionId

acceptedByUser: Set to "true"/"false" respectively to indicate which currency your customers opt for the actual purchase
true: Your customers opt to pay in their local currency (the proposal.targetalmount as received in your GetDccRateInquiry request)
false: Your customers opt to pay in your currency (the proposal.baseAmount as received in your GetDccRateInquiry request)

dccSessionId: The session ID as received as received in your GetDccRateInquiry request

Mandatory for Server-to-server / Mobile/Client Integration integration mode

Depending on the integration mode, differences apply:

Hosted Checkout Page

This is a high-level payment flow covering only the mandatory steps for this feature. Read our dedicated chapter in our Hosted Checkout Page guide for detailed information, code samples and optional steps in the flow

Follow these steps to create a request for this order:

  1. Your customers go to your check-out page and finalise the order
  2. You send this CreateHostedCheckout request to our platform, including property dccenabled to indicate you want to use this feature. Our platform will then automatically enable eDCC on that order:
    {
    "order":{
    "amountOfMoney":{
    "currencyCode":"AUD",
    "amount":2980
    }
    },
    "cardPaymentMethodSpecificInput":{
    "currencyConversionSpecificInput":{
    "dccEnabled":true
    }
    }
    }
  3. You redirect the customers in the browser to the redirectUrl. Once your customers enter their card number on the payment page, our platform automatically fetches the eDCC rate quote and displays the amount option for both your customers' local currency and your local currency
  4. Your customers select their desired currency and confirms the payment
  5. We process the transaction and you receive the settlement in your local currency

Server-to-server

This is a high-level payment flow covering only the mandatory steps for this feature. Read our dedicated chapter in our Server-to-server guide for detailed information, code samples and optional steps in the flow

Follow these steps to create a request for this order:

  1. Your customers go to your check-out page and enters their credit card data to finalise the purchase
  2. You send this GetDccRateInquiry request to our platform with the following properties to receive DCC information. You can provide the customer's card details using
    cardNumber
    token
    hostedTokenizationId
    encryptedCustomerInput

    cardNumber
    {
      "cardSource": {
        "card": {
          "paymentProductId": 1,
          "cardNumber": "4450896052107792"
        }
      },
      "transaction": {
        "amount": {
          "amount": 3000,
          "currencyCode": "EUR"
        }
      }
    }

    token
    {
       "cardSource":{
          "token":"b2076d9f-b2ce-4488-95aa-25ba8aa1c7ce"
       },
       "transaction":{
          "amount":{
             "amount":1300,
             "currencyCode":"AUD"
          }
       }
    }

    hostedTokenizationId
    {
       "cardSource":{
          "hostedTokenizationId":"d153e6ea6a024613ad6bfeff15210f6c"
       },
       "transaction":{
          "amount":{
             "amount":1300,
             "currencyCode":"AUD"
          }
       }
    }

    encryptedCustomerInput
    {
       "cardSource":{
          "encryptedCustomerInput":"b2076d9f-b2ce-4488-95aa-25ba8aa1c7ce"
       },
       "transaction":{
          "amount":{
             "amount":1300,
             "currencyCode":"AUD"
          }
       }
    }
  3. Our platform returns the base amount in your currency in properties proposal.baseAmount.currencyCode / currency and your customers’ local currency in properties targetAmount.amount / currency. Property rate includes further DCC details (i.e. dccSessionId) about the exchange. Make sure to display both the proposal.baseAmount, the targetAmount.amount and the disclosure guidelines in real time for maximum transparency to your customers before the actual payment
  4. Your customers select any of the two currencies on your check-out page
  5. You send this CreatePayment to our platform, including properties acceptedByUser to indicate your customers’ choice of currency and the dccSessionId you have received in step 2
    {
      "cardPaymentMethodSpecificInput": {
        "currencyConversion": {
          "acceptedByUser": true,
          "dccSessionId": "44b1ea32125b4cb5a99e15641859dc8d"
        },
        "card": {
          "cardNumber": "4450896052107792",
          "cvv": "123",
          "expiryDate": "1225",
          "cardholderName": "Wile E. Coyote"
        },
        "paymentProductId": 1,
        "skipAuthentication": true,
        "transactionChannel": "ECOMMERCE",
        "authorizationMode": "SALE",
        "returnUrl": "test"
      },
      "order": {
        "amountOfMoney": {
          "amount": 3000,
          "currencyCode": "AUD"
        },
        "customer": {
          "billingAddress": {
            "AdditionalInfo": "b",
            "city": "Paris",
            "countryCode": "BE",
            "houseNumber": "13",
            "state": "Utah",
            "street": "Desertroad",
            "zip": "84536"
          },
          "locale": "fr_FR",
          "merchantCustomerId": "1234",
          "personalInformation": {
            "dateOfBirth": "19490917",
            "gender": "male",
            "name": {
              "firstName": "Wile",
              "surname": "Coyote",
              "surnamePrefix": "E.",
              "title": "Mr."
            }
          }
        },
        "references": {
          "merchantReference": "{{TIMESTAMP}}"
        }
      }
    }
  6. We process the transaction and you receive the settlement in your local currency

Disclosure Guidelines

  • Cardholder must be clearly advised of the option to choose from two currencies
  • Cardholder must actively choose the DCC option prior to the merchant processing the transaction. A merchant may not proceed with a DCC transaction without explicit cardholder consent
  • No opt-out, default option, no steering or pre-selection is allowed
  • Cardholder must not be asked to select "yes" or "no", "accept" or "decline" or similar pairs
  • All DCC disclosures below are mandatory and must be the same size, color and font types on screens, quote sheets or receipts
  • If the cardholder declines the DCC offer, the transaction must be completed in the merchant's local currency
  • A cardholder must not be re-prompted to accept DCC after rejecting the offer. Cardholder's choice must be honored
  • Currency symbol or code (e.g., AUD or SGD) of the merchant’s local currency.
  • Exchange rate used to determine the DCC transaction amount
  • Any additional exchange rate mark-up over the wholesale or government-mandated rate
  • Total transaction amount in the DCC currency
  • Currency symbol or code (e.g., AUD or SGD) of the offered DCC transaction amount

Follow-up on eDCC transactions

Capture / Refund eDCC transactions

To capture/refund an eDCC transaction, send a standard capture/refund request to our platform.

Get feedback on eDCC transactions

Use our webhooks or any GET request as defined in our API reference to receive detailed information about eDCC transactions in property currencyConversion.

A typical webhook/GET response contains the following properties:

Properties Remarks

acceptedByUser

Indiciates which currency your customers opted for the actual purchase

true: Your customers opted to pay in their local currency (the proposal.targetAmount)

false: Your customers opted to pay in your currency (the proposal.baseAmount)

proposal.baseAmount
    amount
    currencyCode

amount: The gross amount you charged for this order in your currency

currencyCode: The ISO 4217 currency code for this amount for your currency

proposal.targetAmount
    amount
    currencyCode

amount: The gross amount you charged for this order in your customers' local currency

currencyCode: The ISO 4217 currency code for this amount your customers' local currency

proposal.rate
     exchangeRate
     invertedExchangeRate
     markUpRate
     quotationDateTime
     source

exchangeRate: The quotient to convert the proposal.baseAmount to the proposal.targetAmount

invertedExchangeRate: The quotient to convert the proposal.targetAmount to the proposal.baseAmount

markUpRate: Potential additional fees charged by the payment processor or financial institution offering the DCC service. This value is not part of the targetAmount calculation and only provided for transparency

quotationDateTime: Timestamp of your eDCC request

source: Source of the exchange rate used to calculate the targetAmount

Find detailed information about this object and its properties in our API reference

Check processed transactions in Merchant Portal

You can look up DCC details for any transaction via the Merchant Portal. To do so, follow these steps

  1. Login to the Merchant Portal and look up the transaction as described in our Merchant Portal guide
  2. Find detailed DCC information in the "History" section, including
    Customer currency amount
    Exchange rate
    Markup rate
    Exchange provider
    Exchange source
    Quotation date
This information is only available if the transaction was processed with your customers' local currency

Was this page helpful?

Do you have any comments?

Thank you for your response.