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.
| 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).
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:
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:
mcpFxTableId in OrderCreateRequest).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).
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:
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%.
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: fieldscurrencyCodeandtotalAmountshould 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:
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"
}
}