Płatności wielowalutowe (ang. Multi-Currency Pricing) to usługa włączona domyślnie w Twoim sklepie, jeśli korzystasz z formatek płatniczych PayU. Umożliwia ona obciążenie kart płatniczych klientów w różnych walutach, bez konieczności posiadania w PayU salda w tych walutach. Klient, po wyborze płatności kartą w formatce płatniczej, wybiera w jakiej walucie chce zapłacić, dzięki czemu nie ponosi kosztów przewalutowania.
| Term currency | Base currency |
|---|---|
| CZK | EUR |
| CZK | GBP |
| CZK | USD |
| PLN | DKK |
| PLN | EUR |
| PLN | GBP |
| PLN | NOK |
| PLN | SEK |
| PLN | USD |
Term currency - (waluta końcowa - waluta sklepu) - w tej walucie odbiorca otrzyma płatność (waluta ustawiona dla sklepu w systemie PayU).
Base currency - (waluta początkowa - waluta płacącego) - w tej walucie zostanie obciążony płatnik (waluta rozliczeniowa karty płatniczej).
Jeśli korzystasz z transparentnej integracji REST API, możesz rozbudować usługę
płatności wielowalutowych w taki sposób, by klient mógł zobaczyć cenę produktu w
Twoim sklepie w wybranej przez siebie walucie. W takim przypadku konieczna będzie
implementacja dodatkowego żądania w celu pobierania tabeli kursowej. Ponadto
komunikat OrderCreateRequest należy rozszerzyć o obiekt mcpData.
Uwaga: przed rozpoczęciem rozszerzonej integracji należy uzyskać mcpPartnerId
i odpowiednio skonfigurować POS - w tym celu prosimy o kontakt z opiekunem handlowym
w PayU.
Działanie usługi:
W celu pobrania tabeli kursowej od PayU, należy pobrać token OAuth, a następnie wykonać żądanie HTTP GET na adres /api/v2_1/mcp-partners/{mcpPartnerId}/fx-table.
Uwaga: można użyc dowolnego punktu płatności REST API, aby uzyskać token OAuth.
Przykładowe żądanie:
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"Przykładowa odpowiedź (uwaga: PayU udostępnia więcej par walutowych niż podano w przykładzie):
{
"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"
}
]
}
gdzie:
mcpFxTableId w OrderCreateRequest).Zgodnie z regulacjami obowiązującymi w krajach Unii Europejskiej, dostawcy usług płatniczych oraz strony oferujące w punkcie sprzedaży usługi przeliczenia waluty są zobowiązane podać kwotę łącznych opłat za przeliczenie waluty jako wartość procentową marży w stosunku do najbardziej aktualnego referencyjnego kursu wymiany euro ogłoszonego przez Europejski Bank Centralny (EBC).
Aby ułatwić spełnienie tego obowiązku, PayU oferuje możliwość pobrania odświeżanych codzienne kursów referencyjnych, gdzie dostępne są nie tylko kursy publikowane przez EBC względem EUR, ale także pary walutowe obliczane za pomocą tzw. triangulacji poprzez EUR (np. PLN/USD, PLN/GBP itp.).
W celu pobrania tabeli kursowej od PayU, należy pobrać token OAuth,
a następnie wykonać żądanie HTTP GET na adres /api/v2_1/fx-providers/ecb/fx-rates.
Uwaga: można użyc dowolnego punktu płatności REST API, aby uzyskać token OAuth.
Przykładowe żądanie, parametr termCurrency oznacza walutę z jakiej wykonujemy
przewalutowanie:
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"Przykładowa odpowiedź (uwaga: PayU udostępnia więcej par walutowych niż podano w przykładzie):
{
"effectiveDate": "2021-02-25",
"fxRates": [
{
"baseCurrency": "EUR",
"termCurrency": "PLN",
"midRate": 4.5122
},
{
"baseCurrency": "CZK",
"termCurrency": "PLN",
"midRate": 0.172815
}
]
}
gdzie:
Marżę dla danej waluty należy wyliczyć wg następującego wzoru:
(kurs referencyjny - kurs wymiany) / kurs referencyjny * 100%)
Przykładowo, w przypadku kiedy chcemy pokazać marżę dla przewalutowania z PLN do EUR (tj. chcemy otrzymać PLN, ale obciążyć płatnika w EUR), a kurs wymiany to 4,2556 PLN i kurs referencyjny to 4,5122 PLN, wówczas wyliczona marża którą należy zaprezentować to 5,69%.
Aby skorzystać z przewalutowania płatności, konieczna jest transparentna integracja REST API.
Obecnie opcja ta działa tylko dla płatności kartą, dlatego obiekt payMethods.payMethod musi mieć "type" ustawiony jako 'CARD_TOKEN' i w polu "value" zawierać token.
Aby dowiedzieć się jak uzyskać token kartowy, przejdź do sekcji "Pobranie danych karty".
Uwaga: w polachcurrencyCodeitotalAmountnależy podać walutę sklepu w systemie PayU i oryginalną kwotę w tej walucie.
Ponadto, żądanie powinno zawierać obiekt mcpData które zawiera m.in.
kwotę po przewalutowaniu (tj. kwota w jakiej zostanie obciążony płatnik). Obiekt powinien
zawierać:
Poniżej przykład OrderCreateRequest z 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", //waluta sklepu
"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 z tabeli kursowej
"mcpCurrency": "EUR",
//totalAmount podzielona przez mcpRate (1000 / 4.2556)
//zaokrąglona do najbliższej liczby całkowitej
"mcpAmount": "235",
"mcpRate": "4.2556",
//tego ID można używać na Sandboksie
"mcpPartnerId": "6283a549-8b1a-430d-8a62-eea64327440e"
}
}