Przejdź do głównej zawartości

Płatności wielowalutowe

Jeśli korzystasz z formatek płatniczych PayU, Płatności wielowalutowe (ang. Multi-Currency Pricing) są włączone domyślnie w twoim sklepie. To rozwiązanie pozwala na 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.

Istnieją dwa rodzaje walut powiązanych z usługą Multi-Currency Pricing:

  • 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).

Możliwe przewalutowania
Term Currency (walute końcowa)Base currency (waluta początkowa)
CZK
EUR
CZK
GBP
CZK
USD
PLN
DKK
PLN
EUR
PLN
GBP
PLN
NOK
PLN
SEK
PLN
USD

Możliwości rozszerzenia usługi​

Jeśli korzystasz z własnej strony płatności 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 pobrania tabeli kursowej. Ponadto zamówienie należy rozszerzyć o obiekt mcpData.

Notatka

Przed rozpoczęciem rozszerzonej integracji należy uzyskać mcpPartnerId i odpowiednio skonfigurować POS - w tym celu prosimy o kontakt z opiekunem handlowym w PayU.

Jak działa usługa?

  1. Sklep pobiera kursy walut w trybie dziennym od PayU.
  2. Sklep przelicza swoje ceny towarów/usług z waluty sklepu (Term currency - np. CZK, PLN) do waluty płacącego (Base currency), wg kursów walut otrzymanych z PayU (np. EUR/PLN, GBP/CZK, USD/PLN).
  3. Klienci mogą wybrać opcję zapłaty kartą płatniczą w walucie sklepu (bez przeliczenia kursu) lub w walucie rozliczeniowej swojej karty płatniczej (wówczas kwota jest przeliczana wg kursu otrzymanego z PayU).
  4. Sklep otrzymuje środki z PayU w walucie końcowej (Term currency), nie ma więc konieczności utrzymywania salda w każdej z walut.

Pobieranie tebeli kursów​

Ciało żądania metody GET

Wysyłając żądania z metodą GET upewnij się, że w ciele żądania nie przesyłasz żadnych danych. Zgodnie ze standardem RFC 9110 żądania, które nie spełniają tego wymogu, zostaną odrzucone przez PayU i zwrócony zostanie kod HTTP 403.

W celu pobrania tabeli kursowej od PayU, należy pobrać token OAuth, a następnie wykonać żądanie z metodą HTTP GET na endpoint /api/v2_1/mcp-partners/{mcpPartnerId}/fx-table.

Do celów testowych możesz użyć wartości 6283a549-8b1a-430d-8a62-eea64327440e jako mcpPartnerId.

Notatka

Możesz użyć dowolnego punktu płatności REST API, aby uzyskać token OAuth.

Przykład zamówienia​

Przykład pobrania tabeli kursowej
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"

Szczegóły parametrów znajdziesz w sekcji Retrieve Rate Table w naszej referencji API.

Przykład odpowiedzi​

Notatka

PayU udostępnia więcej par walutowych niż podano w przykładzie

Przykład odpowiedzi po pobraniu tablicy kursowej
{
    "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"
        }
    ]
}

Kursy referencyjne​

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.).

Pobieranie kursów referencyjnych​

Ciało żądania metody GET

Wysyłając żądania z metodą GET upewnij się, że w ciele żądania nie przesyłasz żadnych danych. Zgodnie ze standardem RFC 9110 żądania, które nie spełniają tego wymogu, zostaną odrzucone przez PayU i zwrócony zostanie kod HTTP 403.

W celu pobrania tabeli kursowej od PayU, należy pobrać token OAuth, a następnie wykonać żądanie z metodą HTTP GET na endpoint /api/v2_1/fx-providers/ecb/fx-rates.

Notatka

Możnesz użyć dowolnego punktu płatności REST API, aby uzyskać token OAuth.

Przykład pobrania kursów referencyjnych
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"

Parametr termCurrency reprezentuje walutę do przeliczenia.

Przykład odpowiedzi na pobranie kursów referencyjnych
{
    "effectiveDate": "2021-02-25",
    "fxRates": [
        {
            "baseCurrency": "EUR",
            "termCurrency": "PLN",
            "midRate": 4.5122
        },
        {
            "baseCurrency": "CZK",
            "termCurrency": "PLN",
            "midRate": 0.172815
        }
    ]
}

Szczegóły parametrów znajdziesz w sekcji Retrieve Reference Rates w naszej referencji API.

Obliczanie marży​

Marżę dla danej waluty wyliczysz według następującego wzoru

**(kurs referencyjny - kurs wymiany) / kurs referencyjny * 100%)

Przykład obliczenia marży

W przypadku:

  • przewalutowanie z PLN do EUR (tj. chcemy otrzymać PLN, ale obciążyć płatnika w EUR),
  • kurs wymiany to 4,2556 PLN
  • kurs referencyjny to 4,5122 PLN

Wyliczona marża którą należy zaprezentować to 5,69%.

Roszerzenie zamówienia​

Aby skorzystać z przewalutowania płatności, konieczna jest integracja white-label.

Obecnie opcja ta działa tylko dla płatności kartą, dlatego obiekt payMethods.payMethod musi mieć parametr type ustawiony jako CARD_TOKEN i zawierać token w polu value.

Notatka

Aby dowiedzieć się jak uzyskać token kartowy, przejdź do sekcji Odbieranie danych karty.

w polach currencyCode i totalAmount należy podać walutę sklepu w systemie PayU i oryginalną kwotę w tej walucie.

Ponadto, do żądania powinno się dodać obiekt mcpData które zawiera m.in. kwotę po przewalutowaniu (tj. kwota w jakiej zostanie obciążony płatnik - mcpAmount).

Szczegóły na temat obiektu mcpData znajdziesz w sekcji Create an Order w naszej referencji API.

Przykład obliczenia mcpAmount

Oto jak obliczono mcpAmount dla poniższego przykładu żądania

mcpAmount = totalAmount / mcpRate

mcpAmount = 1000 / 4.2556

mcpAmount = round(234,98) = 235

Przykład żądania​

Przykład zamówienia z obiektem 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",
        "mcpRate": "4.2556",
        // totalAmount podzielona przez mcpRate (1000 / 4.2556)
        // zaokrąglona do najbliższej liczby całkowitej
        "mcpAmount": "235",
        // tego ID można używać na Sandboksie
        "mcpPartnerId": "6283a549-8b1a-430d-8a62-eea64327440e"
    }
}

Na tej stronie