Multi-Currency Pricing

1 Introduction

Multi-Currency Pricing is a service enabled by default in your shop if you use PayU payment forms. It allows you to charge your customers' payment cards in different currencies without the need to have a balance in those currencies in PayU. After choosing to pay with a card in the payment form, the customer chooses the currency in which he wants to pay, so that he doesn’t have to pay for currency conversions.

Currency conversion is possible from PLN and CZK:

Term currency Base currency
CZK EUR
CZK GBP
CZK USD
PLN DKK
PLN EUR
PLN GBP
PLN NOK
PLN SEK
PLN USD

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 in which payer will be charged for payment (card settlement currency).

2 Possibilities to expand the service

If you use transparent REST API integration, you can expand your multi-currency payment service so that the customer can see the price of the product in your shop in the currency of his choice. In this case you will need to implement additional REST API endpoint to get the FX rates and enhance OrderCreateRequest with mcpData object.

Note: you will need to obtain mcpPartnerId parameter value from PayU and have your POS(s) configured before you start integration - please contact your Account Manager.

The service works as follows:

  1. you download FX rates daily from PayU.
  2. 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. you are receiving funds from PayU in your term currency, no need to keep bank account in all the currencies.

3 Rate table retrieval

In order to retrieve rate table from PayU, you need to obtain OAuth access token and then perform a HTTP GET request to /api/v2_1/mcp-partners/{mcpPartnerId}/fx-table endpoint.

Note: you may use any REST API POS ID to get the access token.

Sample request:

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"
curl -X GET https://secure.snd.payu.com/api/v2_1/mcp-partners/6283a549-8b1a-430d-8a62-eea64327440e/fx-table \
    -H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47"

Sample response (note: PayU provides more currency pairs than shown below):

{
    "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"
        }
    ]
}
            

Explanation:

  • id - rate table id (corresponds with mcpFxTableId in OrderCreateRequest).
  • validTo - table validity time (always in UTC). New table should be retrieved right after the validity ends.
  • baseCurrency - initial currency - this is the currency in which the payer will be charged (card settlement currency).
  • termCurrency - final currency - this is the currnecy of the shop at which the payment will be processed (currency set for the shop in the PayU system).

4 Reference rates

According to regulations in the European Union countries, payment service providers and parties providing currency conversion services at the point of sale are obliged to express the total currency conversion charges as a percentage mark-up over the latest available euro foreign exchange reference rates issued by the European Central Bank (ECB).

To help you achieve compliance with this regulation, PayU provides reference rate table (refreshed daily) which includes the rates published by the ECB against EUR and also other rates triangulated using EUR (eg. PLN/USD, CZK/GBP etc).

Reference rates retrieval

In order to retrieve rate table from PayU, you need to obtain OAuth access token and then perform a HTTP GET request to /api/v2_1/fx-providers/ecb/fx-rates endpoint.

Note: you may use any REST API POS ID to get the access token.

Sample request, termCurrency parameter represents the currency to convert:

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"
curl -X GET https://secure.snd.payu.com/api/v2_1/fx-providers/ecb/fx-rates?termCurrency=PLN \
    -H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47"

Sample response (note: PayU provides more currency pairs than shown below):

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

where:

  • effectiveDate - reference rate table validity. You need to refresh the table daily.
  • baseCurrency - initial currency - this is the currency in which the payer will be charged (card settlement currency).
  • termCurrency - final currency - this is the currnecy of the shop at which the payment will be processed (currency set for the shop in the PayU system).
  • midRate - midrate to be used to calculate the percentage mark-up.

Mark-up calculation

The mark-up should be calculated as follows:

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

For example, in case of conversion from PLN to EUR (i.e. you want to receive PLN, but charge in EUR), and given is exchange rate of 4.2556 PLN and reference rate of 4.5122 PLN, the mark-up equals 5.69%.

5 OrderCreateRequest enhancement

To charge your customer in foreign currency, you need to have a transparent REST API integration.

Currently the currency conversion is possible only for transparent card payments, therefore the payMethods.payMethod object must have "type" set to 'CARD_TOKEN' and contain card token as "value".

To learn how to obtain a card token, please refer to "Capturing card data"section.

Note: fields currencyCode and totalAmount should contain shop currency in the PayU system and original amount in this currency.

Additionally, the request should include mcpData object. The object includes converted amount (i.e. amount and currency in which the payer will be charged).

mcpData properties explained:

  • mcpPartnerId - id obtained from PayU.
  • mcpFxTableId - rate table id.
  • mcpCurrency - baseCurrency from the rate table - payer currency.
  • mcpAmount - amount calculated in shop currency (totalAmount).
  • mcpRate - rate used (exchangeRate) from the Fx table.
Example of calculating mcpAmount:
  • mcpAmount = totalAmount / mcpRate
  • mcpAmount = 1000 / 4.2556
  • mcpAmount = round(234,98) = 235

Example of OrderCreateRequest 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" 
  }
}