Conversion when customer selects payment currency

Overview

Currency conversion when the customer selects the payment currency is supported for card 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.
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 Orchid.
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.

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 2. Payment form with the initial payment currency

Figure 3. Payment form with the list of available currencies

Figure 4. Payment form after the customer selects the currency

Figure 5. Payment form after the customer completes all fields

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 95.00 USD and the customer selects to pay in Brazilian reals, then the payment form will display the amount converted to reals—for example, 485.00 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 95.00 USD, the customer is shown the amount in the selected currency—485.00 BRL.

Setup

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

With your Orchid account manager, discuss and agree upon setting up this functionality for specific projects.
If you need testing, get notified by the Orchid specialists that the payment form is ready for being used in test mode, test this functionality, and inform Orchid that everything is ready to launch.
Get notified by the Orchid 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.

Figure 7. Payment workflow that involves conversion to a customer-selected currency

Payment Page sends to the payment platform the request to obtain information (about available currencies and exchange rates) required for currency conversion.
The payment platform processes the request.
The payment platform sends the information required for currency conversion to Payment Page.
Payment Page displays the list of available currencies.
The customer selects the currency and enters the card verification code.
Payment Page sends to the payment platform the request for payment denominated in the currency that the customer selected.

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 95.00 USD are converted into 485.00 BRL as the customer selected to pay in BRL and the amount the customer actually paid is equal to 485.00 BRL.

Figure 8. Sample callback with the result of the payment that requires currency conversion

{
    "payment":{
        "method":"card",
        "sum":{
            "amount":9500,
            "currency":"USD"
        },
        "id":"11006",
        "type":"purchase",
        "status":"success",
        "date":"2022-06-23T13:32:09+0000",
        "description":""
    },
    "customer":{
        "id":"12"
    },
    "sum_customer":{
        "amount":48500,
        "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":9500,
            "currency":"USD"
        },
        "sum_converted":{
            "amount":48500,
            "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=="
}