Currency conversion

General information

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

Suppose that the customer uses their dollar-denominated card to pay a certain amount in euros to the merchant whose account is denominated in pound. The payment amount is consecutively converted from dollars to euros and then from euros to pounds. The first conversion operation is performed by the issuer or by the alternative payment system. The second conversion operation is performed by the ecommpay payment platform.

You can also perform the conversion on your side and send the converted amount in the desired currency in the requests for performing operations.

For payments with conversion via Payment Page, the ecommpay payment platform supports automatic payment currency selection when the currency is 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.

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 issuers and alternative payment systems use the merchant account currency to keep record of the merchant transactions.

It should be also taken into account that the operation amount and the amount actually debited from the customer's account may not be the same, since currency exchange rates usually differ on the date when the payment was initiated and the date when the funds were actually debited. For conversion and compensation in such cases, the customer should contact the card issuer or the organization where the account is opened.

To find out which payment methods in which currencies support conversion, please refer to the description of this method or to the ecommpay key account manager.

The following section describes the option of the currency conversion with the payment currency selected by the merchant in greater detail.

Automatic payment currency selection

Overview

The capability of automatic payment currency selection does not allow the customer to select the currency to perform the payment. 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. However, 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 action on your part and is automatically performed during the payment procedure.

Currency conversion information is passed in payment result callbacks and is added to 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.

The following example shows information about a purchase with a conversion operation in which 100 USD are converted into 519.41 PHP.

Figure: Example of a callback when executing a purchase required 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" // initially 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...=="
}