Currency choice in Payment Page

Overview

In certain cases you may find it useful to give your customers a possibility to choose the payment currency that fits their needs directly in the payment form. When accepting payments via Payment Page, you can set up payment processing workflows where this capability is integrated seamlessly, with support for a wide range of available currencies, flexible configuration, and automatic currency conversion when necessary.

When accepting payments via Payment Page, you can provide your customers with a possibility to select their payment currency in the payment form.

With this capability, the currency that was specified in the request to open Payment Page is always shown as preselected. However, the customer can choose to pay in one of the other available currencies, in which case the customer is then shown the recalculated payment amount in the currency they selected and are able to confirm the payment in the selected currency.

Choosing the currency in the payment form is supported, first and foremost, for the standard card payments. If you have any questions regarding the integration, setup, and use of this functionality, refer to your Flashpay account manager.

Special aspects and limitations

When integrating and using the functionality of choosing the currency in the payment form, consider the following special aspects and limitations:

• The customer selects the currency only out of those that are available. You can manage the availability of currencies for selection.

  In general, 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. The options are as follows:

  • Selecting currency out of all available.
  • Selecting currency out of those relevant for the country where the card was issued (determined by the card number) or, if relevant currencies are not available, out of the remaining available currencies.

    For example, if the customer uses the card issued in Brazil, and the Brazilian real is supported as an operational currency for the project in question, the available currencies can be the initial currency specified in the request and the Brazilian real.

    This option is supported only for standard card payments, and when it is used, the list of available currencies is shown to the customer only after the card number has been entered.

  • Selecting currency out of those relevant for the country where the card was issued (determined by the card number) or, if relevant currencies are not available, the option to choose the currency can be removed and the payment request currency can be used instead.

    For example, if the customer uses the card issued in Brazil, and the Brazilian real is not supported as an operational currency for the project in question, only the payment request currency can be shown for selection.

    This option is supported only for standard card payments, and when it is used, the list of available currencies is shown to the customer only after the card number has been entered.

  You can compile lists of available currencies for each project and can also decide on the option of filtering the available currencies for card payments. Thus, the list of available currencies can differ depending on the project, payment method, and payment instrument.

• Dollars, euros, or pounds sterling can be used as balance currencies.

  If the customer selects to pay in euros, US dollars, or pounds sterling, and the payment is processed in the selected currency and the balances in the relevant currencies have been configured, the merchant receives the funds in this currency. In all other cases, the merchant receives the funds in US dollars.

• Currency conversion is performed with the use of exchange rates set by Flashpay.

  These rates are calculated by Flashpay according to the market data provided by the speciliased partner services. To monitor payments with conversion, you can use different interfaces of the payment platform (details). You can also contact your account manager to learn more about exchange rates and the specifics of how they are applied.

Workflow

You do not need to update your web service to support payment currency selection by the customer (as far as standard processing workflows for payments of a specific type are concerned). The following is a workflow of a one-step purchase that requires conversion to the currency selected by the customer.

When the currency selected by the customer differs from the one specified in the payment request, payment result callbacks can contain (if it has been configured) the sum_customer object with the following parameters:with the information about the payment amount and the currency selected by the customer in the amount and currency parameters.

• amount—the operation amount in the smallest units of the currency selected by the customer
• currency—the code of the currency selected by the customer in ISO-4217 alpha-3

This information is used as complementary to the data about the amount and currency passed in the operation object:

• sum_initial—the initial amount and currency of the request
• sum_converted—the converted amount and currency that were actually used to perform the operation

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.

{
    "payment":{
        "method":"card",
        "sum":{
            "amount":9500, // payment amount in the requested payment currency  
            "currency":"USD" // code of the requested payment currency
        },
        "id":"11006",
        "type":"purchase",
        "status":"success",
        "date":"2022-06-23T13:32:09+0000",
        "description":""
    },
    "customer":{
        "id":"12"
    },
    "sum_customer":{
        "amount":48500, // amount in the customer selected currency
        "currency":"BRL" // code of the customer selected currency
    },
    "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, // operation amount in the requested payment currency
            "currency":"USD" // code of the requested payment currency
        },
        "sum_converted":{
            "amount":48500, // operation amount in the actual operational currency
            "currency":"BRL" // code of the actual operational currency
        },
        "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=="
}

Setup

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

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