Skip to main content

Multi-Currency Pricing

Multi-Currency Pricing is a default service offered by PayU when you utilize their payment forms. It permits you to bill your customers' payment cards in different currencies, even if you don't possess a balance in those currencies within your PayU account. Once a customer selects the card payment option in the checkout process, they can choose the currency in which they wish to conduct the transaction. This functionality eliminates the need for customers to incur currency conversion fees.

There are two types of currencies linked to the Multi-Currency Pricing service:

  • Term currency (final currency – shop currency) - currency in which the recipient will receive payment (currency of the shop in the PayU system).

  • Base currency (initial currency – payer currency) - currency selected by the payer and in which the payment will be charged (card settlement currency).

Possible Conversions
Term CurrencyBase currency
CZK
EUR
CZK
GBP
CZK
USD
PLN
DKK
PLN
EUR
PLN
GBP
PLN
NOK
PLN
SEK
PLN
USD

Expanding the Service​

If you're utilizing your custom checkout page while integrating with PayU, you can extend your multi-currency payment service to enable customers to view the product prices in your shop using their preferred currency. To achieve this, you will need to implement an additional REST API endpoint to obtain the foreign exchange (FX) rates. Subsequently, you should enhance the order request by incorporating the mcpData object.

Notes

Before you commence integration, you need to acquire the mcpPartnerId parameter value from PayU. Additionally, ensure that your POS (Point of Sale) is appropriately configured. To facilitate this process, please reach out to your Account Manager at PayU.

How does it work?

  1. You download FX rates daily from PayU.
  2. Then you convert prices of products/services from your term currency (e.g. CZK, PLN) to the base currency using the foreign currencies daily rates provided by PayU (e.g. EUR/PLN, GBP/CZK, USD/PLN).
  3. Your customers can now checkout and pay via card in either the shop currency or in the settlement currency of the card (in this case the amount is calculated based on the rate provided by PayU).
  4. After the payment is completed you receive funds from PayU in your term currency, no need to keep bank account in all the currencies.

Retrieving Rate Table​

GET Request Body

When making GET requests, please remember not to include any data in the request body, as specified in the RFC 9110 standard. Requests that do not adhere to this requirement will be rejected by PayU with an HTTP 403 status.

To retrieve the rate table from PayU, you must first acquire an OAuth access token. After obtaining the token, proceed to execute an HTTP GET request to the /api/v2_1/mcp-partners/{mcpPartnerId}/fx-table endpoint.

For testing purposes, you can use the value 6283a549-8b1a-430d-8a62-eea64327440e as the mcpPartnerId.

Notes

You may use any REST API POS ID to get the access token.

Request Example​

Rate Table Retrieve Request on Production
curl -X GET https://secure.payu.com/api/v2_1/mcp-partners/7124ecb8-a9a9-4dff-bdbc-520041eb05dd/fx-table \
 -H "Authorization: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd"

For details on parameters, please refer to the Retrieve Rate Table section in our API Reference.

Response Example​

Notes

PayU offers a broader range of currency pairs beyond those presented below.

Rate Table Retrieve Response
{
    "id": "3050",
    "validTo": "2017-06-27T20:20:00Z",
    "currencyPairs": [
        {
            "baseCurrency": "PLN",
            "exchangeRate": 0.23753,
            "termCurrency": "USD"
        },
        {
            "baseCurrency": "USD",
            "exchangeRate": 3.8125,
            "termCurrency": "PLN"
        },
        {
            "baseCurrency": "EUR",
            "exchangeRate": 4.2556,
            "termCurrency": "PLN"
        }
    ]
}

Reference Rates​

As per regulations in European Union countries, payment service providers and entities offering currency conversion services during transactions are required to display the overall currency conversion charges as a percentage mark-up over the most recent euro foreign exchange reference rates provided by the European Central Bank (ECB).

To assist you in adhering to this regulation, PayU furnishes a reference rate table that is updated daily. This table encompasses rates released by the European Central Bank (ECB) against EUR, as well as additional rates that are triangulated using EUR (e.g., PLN/USD, CZK/GBP, etc.).

Retrieving Referece Rates​

GET Request Body

When making GET requests, please remember not to include any data in the request body, as specified in the RFC 9110 standard. Requests that do not adhere to this requirement will be rejected by PayU with an HTTP 403 status.

To access the rate table from PayU, you must first acquire an OAuth access token. Once you have the token, proceed to make an HTTP GET request to the /api/v2_1/fx-providers/ecb/fx-rates endpoint.

Notes

You may use any REST API POS ID to get the access token.

Reference Rates Retrieval Request Example on Production
curl -X GET https://secure.payu.com/api/v2_1/fx-providers/ecb/fx-rates?termCurrency=PLN \
 -H "Authorization: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd"

termCurrency parameter represents the currency to convert.

Reference Rates Retrieval Response Example
{
    "effectiveDate": "2021-02-25",
    "fxRates": [
        {
            "baseCurrency": "EUR",
            "termCurrency": "PLN",
            "midRate": 4.5122
        },
        {
            "baseCurrency": "CZK",
            "termCurrency": "PLN",
            "midRate": 0.172815
        }
    ]
}

For details on parameters, please refer to the FX Reference section in our API Reference.

Calculating Mark-up​

You can calculate mark-up as follows:

(exchange rate - reference rate) / reference rate * 100%

Notes

In case of:

  • conversion from PLN to EUR (i.e. you want to receive PLN, but charge in EUR),
  • given exchange rate of 4.2556 PLN,
  • reference rate of 4.5122 PLN.

The mark-up equals 5.69%.

Enhancing Order Request​

If you want to charge your customers in a foreign currency, you must have created your own checkout page.

Currently, the currency conversion is only available for white-label card payments, therefore the payMethods.payMethod object must have the type parameter set to CARD_TOKEN and contain a card token as the value of the value parameter.

Notes

To learn how to obtain a card token, please refer to Capturing Card Data section.

currencyCode and totalAmount parameters should include shop currency in the PayU system and original amount in this currency.

In addition, the request should include an mcpData object. This object contains the converted amount (i.e. the amount and the currency in which the payer will be charged).

For details on mcpData object, please refer to the Create an Order section in our API Reference.

Example

Here's how the mcpAmount was calculated for the following request example

mcpAmount = totalAmount / mcpRate

mcpAmount = 1000 / 4.2556

mcpAmount = round(234,98) = 235

Request example​

Order Request Body Example with mcpData
{
    "continueUrl": "http://payer.will.be.redirected.here",
    "notifyUrl": "https://notifications.will.be.sent.here",
    "customerIp": "123.3.2.1",
    "merchantPosId": "your POS ID",
    "description": "multi-currency pricing",
    "currencyCode": "PLN", // shop currency
    "totalAmount": 1000,
    "products": [
        {
            "name": "a thing",
            "unitPrice": 1000,
            "quantity": 1
        }
    ],
    "buyer": {
        "email": "some@email.com",
        "firstName": "Some",
        "lastName": "Person"
    },
    "payMethods": {
        "payMethod": {
            "type": "CARD_TOKEN",
            "value": "TOK_1JJMRQ9EORTY62ixm0f8Ic9ySRZT"
        }
    },
    "mcpData": {
        "mcpFxTableId": "132331",
        // baseCurrency from FX rate table
        "mcpCurrency": "EUR",
        "mcpRate": "4.2556",
        // totalAmount divided by mcpRate (1000 / 4.2556)
        // rounded half up to nearest integer
        "mcpAmount": "235",
        // you can use this id on Sandbox
        "mcpPartnerId": "6283a549-8b1a-430d-8a62-eea64327440e"
    }
}

On this page