Conversion when customer selects payment currency

Overview

Currency conversion when the customer selects the payment currency is supported for card, Apple Pay, and Google Pay payments. It has the following characteristics:

• The customer selects the currency out of all available.

  Available currencies encompass all currencies supported as operational for the merchant's project in question and also available for performing conversion within the initiated payment session. For card payments, the currency availability can be limited by filtering all available currencies by those relevant for the country where the card was issued (determined by the card number) and a specific currency passed in the request. For example, if the customer uses the card issued in Brazil, the available currencies can be the initial currency specified in the request and the Brazilian real. However, if the currency relevant for the card country cannot be used as operational, the option to filter all available currencies can either be removed, or the list can be reset to all available. Thus, the list of available currencies can differ depending on the project, payment method, and payment instrument.

• The merchant receives the funds in the currency selected by the customer: dollars, euros, or pounds sterling.

  If the customer selects to pay in euros, US dollars, or pounds sterling, and the payment is processed in the selected currency, the merchant receives the funds in this currency. If the Bulgarian lev is selected, then the merchant receives the funds in euros (for Visa payments) or in dollars (for Mastercard payments). In all other cases, the merchant receives the funds in dollars.

• This option uses exchange rates set by ecommpay.

  Conversion rates information (for reference use only) can be retrieved via the Data API interface. You can also contact your account manager to learn more about exchange rates and the specifics of how they are applied.

• For Apple Pay and Google Pay payments, this currency selection option is supported if the buttons to select these methods are shown on the payment method selection page.

  if for the project in question these buttons are shown on the page to enter card details, this currency selection option is not available.

Currencies available for the customer to select are displayed on Payment Page in a drop-down list with currency codes. If the payment request contains a code of the currency from this list, this currency is shown as preselected.

Selecting from all available currencies is supported for one-time purchases, including scenarios when payment retries are used.

The customer can confirm the payment in the initial currency of the request or select another. When a different currency is selected, the payment form displays the amount in the selected currency instead of the initial payment amount. Let's say the payment amount is 10.00 USD and the customer selects to pay in Brazilian reals, then the payment form will display the amount converted to reals—for example, 57.60 BRL.

Following this step, the customer can see the amount in the selected currency on all pages of the payment form including the payment result page. Thus, in our example with the initial payment amount of 10.00 USD, the customer is shown the amount in the selected currency—57.60 BRL.

Setup

To set up the functionality of currency conversion when the customer selects the currency:

1. With your ecommpay account manager, discuss and agree upon setting up this functionality for specific projects, whether testing is necessary, what payment methods and relevant currencies are required, and whether you need the option to filter all available currencies by the customer's card country.
2. If you need testing, get notified by the ecommpay specialists that the payment form is ready for being used in test mode, test this functionality, and inform ecommpay that everything is ready to launch.
3. Get notified by the ecommpay specialists that the functionality has been added and fully set up.

Use

You do not need to update your web service to support payment currency selection by customer. The following is a workflow of a one-step purchase with saved card data which requires conversion to the currency selected by the customer.

Currency conversion information is included in payment result callbacks: the operation object contains the sum_initial object that specifies the initial amount and the currency of the request and the sum_converted object that specifies the amount and the currency after the conversion operation. In addition, the sum_customer object contains the following information about the customer's currency selection:

• amount—operation amount in the currency selected by the customer
• currency—code of the currency selected by the customer

However, the currency selection information is not specified in a callback if the information about the currency selected by the customer is passed in the initial payment request.

The following is an example of the payment with a conversion operation in which 10.00 USD are converted into 57.60 BRL as the customer selected to pay in BRL and the amount the customer actually paid is equal to 57.60 BRL.

{
    "payment":{
        "method":"card",
        "sum":{
            "amount":1000,
            "currency":"USD"
        },
        "id":"11006",
        "type":"purchase",
        "status":"success",
        "date":"2022-06-23T13:32:09+0000",
        "description":""
    },
    "customer":{
        "id":"12"
    },
    "sum_customer":{
        "amount":5760,
        "currency":"BRL"
    },
    "account":{
        "number":"541333******0019"
    },
    "project_id":42,
    "operation":{
        "created_date":"2022-06-23T13:32:02+0000",
        "request_id":"a23962a836e8e4-db4f1981d9-0006",
        "sum_initial":{
            "amount":1000,
            "currency":"USD"
        },
        "sum_converted":{
            "amount":5760,
            "currency":"BRL"
        },
        "code":"0",
        "message":"Success",
        "eci":"05",
        "provider":{
            "id":6,
            "payment_id":"1629803",
            "auth_code":"563253",
            "endpoint_id":6,
            "date":"2022-06-23T10:32:09+0000"
        },
        "id":682400942,
        "type":"sale",
        "status":"success",
        "date":"2022-06-23T13:32:09+0000"
    },
    "signature":"BsGd0vcBQjd+aFl8ehEPRjf/eQUABow+VO+/xSG+lqKo6xHQ=="
}