Conversion when customer selects payment currency

Overview

Currency conversion when the customer selects the payment currency has the following characteristics:

  • The customer selects the currency out of all available.

    Available currencies encompass all currencies supported for the merchant's project in question with available currency pairs as provided by the exchange rate data source. Thus, the list of available currencies can differ depending on the project and the required action.

  • 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.

    To learn more about exchange rates, contact your account manager.

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.

Figure 1. Payment form with the initial payment currency


Figure 2. Payment form after the customer completes all fields


Figure 3. Payment form with the list of available currencies


Figure 4. Payment form after the customer selects the currency


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

The customer can confirm the payment in the initial currency 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 USD and the customer selects to pay in brazilian reals, then the payment form will display the amount converted to dollars—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 USD, the customer is shown the amount in the selected currency—57.60 BRL.

Setup

To learn more about the option when the customer selects payment currency and to set up this functionality, contact your ecommpay account manager.

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 which requires conversion to the currency selected by the customer.



Figure 5. Payment workflow that involves conversion to a customer-selected currency
  1. Payment Page sends the request to obtain information required for currency conversion to the payment platform.
  2. The payment platform processes the request.
  3. The payment platform sends the information required for currency conversion to Payment Page.
  4. Payment Page displays the boxes for the customer to enter card details and the list of available currencies.
  5. The customer selects the currency and enters card details.
  6. Payment Page sends the request for payment denominated in the currency that the customer selected to the payment platform.

Currency conversion information is included in payment result callbacks: the operation object contains the sum_initial object that specifies the amount and the initial currency 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 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.

Figure 6. Sample callback with the result of the payment that requires currency conversion
{
    "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=="
}