Currency conversion

General information

In general, a payment may involve three currencies: customer account currency, payment currency, and merchant account currency. If all the three currencies are the same, there is no need for currency conversion, otherwise you need to convert payment amount between currencies.

Suppose that customer uses their rouble-denominated card to pay some euros to merchant whose account is denominated in pound. The payment amount is consecutively converted from roubles to euros, and then from euros to pounds. The first conversion operation is performed by issuer or by alternative payment system. The second conversion operation is performed by the ECommPay payment platform.

For payments that use Payment Page, the ECommPay payment platform offers the following options:
  • Payment currency selected by merchant: the customer cannot select payment currency while the exchange rate is dictated by the payment system. This option is default and available for all payment methods and currencies.
  • Payment currency selected by customer: the customer can select the currency to use for the payment while the exchange rate is defined by ECommPay's partner. This option is available only when customer uses payment card. To enable the option, contact your ECommPay key account manager.

You can get the information about conversion operations performed by the payment platform from the callbacks with payment results, from Dashboard, or from regular reports sent to email addresses you specify. We recommend that you use this information for reconciliation with ECommPay, because issuer and alternative payment system use the merchant account currency to keep record of the merchant transactions.

The sections that follow describe these options in greater details.

Conversion when merchant selects payment currency

Overview

As its name implies, the payment currency selected by customer does not allow the customer to select the currency to perform the payment, although this type of payment currency selection is available for all payment methods. Automatic payment currency selection uses exchange rates from one of the following sources:

The rates in all the sources are updated daily.

By default, each merchant project uses only one source which is assigned byECommPay. Although, the ECommPay payment platform may use rates from a different source if the default source fails to provide the required exchange rate.

Setup

You do not need to update your web service to support automatic payment currency selection.

Usage

Automatic payment currency selection does not require any additional efforts and is automatically performed during payment procedure.

Any conversion information is added in payment result callbacks into two objects embedded into the operation object: the sum_initial object contains the amount and the currency before conversion while the sum_converted object contains the amount and the currency after the conversion operation. For more information about these objects, see Callbacks.

Below you will find the example of payment with a conversion operation in which 100 USD are converted into 519,41 PHP debited to merchant account denominated in Philippine peso.

Figure: Sample callback with the result of a payment that requires currency conversion

{ 
  "project_id":42,
  "payment":{ 
    "id":"15dd47055381e8375e7b2d0cb16f",
    "type":"purchase",
    "status":"success",
    "date":"2019-09-17T11:50:29+0000",
    "method":"dragonpay",
    "sum":{ 
      "amount":10000, // Initially requested amount
      "currency":"USD" // Initial requested currency
    },
    "description":""
  },
  "operation":{ 
    "id":200004157,
    "type":"sale",
    "status":"success",
    "date":"2019-09-17T11:50:29+0000",
    "created_date":"2019-09-16T13:17:31+0000",
    "request_id":"622d6f7f9e6bce298676b38e45",
    "sum_initial":{ 
      "amount":10000, // Initially requested amount
      "currency":"USD" // Initially requested currency
    },
    "sum_converted":{ 
      "amount":519410, // Amount after conversion
      "currency":"PHP" // Automatically selected target currency
    },
    "provider":{ 
      "id":1165,
      "payment_id":"DY3TU78",
      "date":"2019-09-16T21:17:39+0000",
      "auth_code":"",
      "endpoint_id":"BPI"
    },
    "code":"0",
    "message":"Success"
  },
  "signature":"MJv7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}

Conversion when customer selects payment currency

Overview

For payments with bank cards, Payment Page allows you to offer your customer possibility to select the currency before proceeding with the payment. The following currencies are available: EUR, USD, GBP, and RUB. You can select for you project all the currencies or only part of them.

Restriction: The option is available for only card payments and depands on a provider that can be involved in the payment processing. For more details, contact your ECommPay key account manager.

The list of currencies for customer to select from is displayed on Payment Page only if the payment request contains code of one of the currencies. In this case, the payment amount will be denominated in the currency which is specified in the request. For example, if you specify USD in your payment request, the US dollar will be selected on Payment Page and the payment amount will be denominated in US dollar.

Figure: Payment page with the currency selection section



Customer can use the default currency or select a different currency. If customer selects a different currency, the payment form displays the exchange rate and the amount in the selected currency.

For instance, if the payment amount is 95,00 USD and user selects EUR as the payment currency, the payment form displays exchange rate for the USD/EUR pair and the amount in euro, in our case this is 87,26 EUR.

The exchange rate and the amount in the selected currency on the payment page are updated every five minutes.

Figure: Payment page with the currency selection section



Upon completion of the payment procedure, the payment form shows to the customer the amount in the initial currency, amount converted to the currency customer selected, and the exchange rate used for the conversion operation. In our example, the following information is displayed:

  • amount in the currency customer selected: 87,26 EUR
  • amount in the initial currency: 95,00 USD
  • exchange rate for the USD/EUR pair

The same information is displayed on the payment form, if the payment with currency conversion is declined.

Figure: Payment result page with conversion information



Setup

Contact technical support at support@ecommpay.com to get more information about the scenario in which customer selects payment currency, as well as to set this functionality up and choose the currencies which will be available to customer to select on the checkout form.

Usage

You do not need to update your web service to support payment currency selection by customer. Here is the workflow of a one-step purchase which requires conversion operation that uses customer-selected currency.



Figure: Payment workflow that involves conversion to customer-selected currency

  1. Payment Page send a request for available currencies, rates, and converted amounts to the payment platform.
  2. The payment platform processes the request.
  3. The payment platform sends the information about available currencies, their rates, and converted amounts to Payment Page.
  4. Payment Page displays the boxes for the customer to enter card details, as well as the list of available currencies to choose from, and currency conversion information that includes exchange rate and converted amount for each available currency pair.
  5. Customer selects the currency and enters card details.
  6. Payment Page sends the request for payment denominated in the currency customer selected to the payment platform.

Any conversion information is added in payment result callbacks into two objects embedded into the operation object: the sum_initial object contains the amount and the currency before conversion while the sum_coverted object contains the amount and the currency after the conversion operation. For more information about these objects, see Callbacks.

If required, callback may also include exchange rates in the mcs object:

  • currency_pair—currency pair (for example, EURUSD)
  • rate—exchange rate (for example, 1.08876)

If you want callbacks to contain exchange rate, contact technical support service at support@ecommpay.com.

Below you will find the example of payment with a conversion operation in which 95 USD are converted into 87,26 EUR.

Figure: Sample callback with the result of a payment that requires currency conversion

{ 
  "project_id":42,
  "payment":{
    "id":"10005",
    "type":"purchase",
    "status":"success",
    "date":"2019-10-16T11:52:51+0000",
    "method":"card",
    "sum":{ 
      "amount":9500, // Initially requested amount
      "currency":"USD" // Initially requested currency
    },
    "description":""
  },
  "account":{ 
    "number":"555555******4443",
    "type":"mastercard",
    "card_holder":"JUDY DOE",
    "expiry_month":"03",
    "expiry_year":"2024"
  },
  "customer":{ 
    "id":"12"
  },
  "operation":{ 
    "id":26900008841,
    "type":"sale",
    "status":"success",
    "date":"2019-10-16T11:52:51+0000",
    "created_date":"2019-10-16T11:52:40+0000",
    "request_id":"9e713d016844bf349ea4e26938",
    "sum_initial":{ 
      "amount":9500, // Initially requested amount
      "currency":"USD" // Initially requested currency
    },
    "sum_converted":{ 
      "amount":8726, // Amount after conversion
      "currency":"EUR" // Customer-selected target currency
    },
    "mcs":{ 
      "currency_pair": "EURUSD", // Currency pair
      "rate":"1.08876" // Exchange rate
    },
    "code":"0",
    "message":"Success",
    "eci":"02",
    "provider":{ 
      "id":11,
      "payment_id":"50313",
      "auth_code":"",
      "endpoint_id":11,
      "date":"2019-10-16T11:52:50+0000"
    }
  },
  "signature":"MJv7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
}