Płatności wielowalutowe

1 Wprowadzenie

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.

Przewalutowanie możliwe jest z PLN i 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 - (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).

2 Możliwości rozszerzenia usługi

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:

  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.

3 Kursy wymiany

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:

  • id - id tabeli kursowej (odpowiednik mcpFxTableId w OrderCreateRequest).
  • validTo - ważność tabeli kursowej (zawsze w czasie uniwersalnym/UTC). Nowa tabela powinna zostać pobrana zaraz po upływie ważności poprzedniej.
  • baseCurrency - waluta początkowa - waluta płacącego, w której zostanie obciążony płatnik (waluta rozliczeniowa karty płatniczej);
  • termCurrency - waluta końcowa - waluta sklepu, czyli waluta punktu płatności, w którym będzie wykonana płatność (waluta ustawiona dla sklepu w systemie PayU).

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

Pobranie tabeli kursów referencyjnych

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:

  • effectiveDate - ważność tabeli kursowej. Tabela powinna być odświeżana raz dziennie.
  • baseCurrency - waluta początkowa - waluta płacącego, w której zostanie obciążony płatnik (waluta rozliczeniowa karty płatniczej);
  • termCurrency - waluta końcowa - waluta sklepu, czyli waluta punktu płatności, w którym będzie wykonana płatność (waluta ustawiona dla sklepu w systemie PayU).
  • midRate - kurs średni, który należy wykorzystać do obliczenia procentowej marży od wykonanego przewalutowania.

Wyliczenie marży

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

5 Rozszerzenie OrderCreateRequest

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 polach currencyCode i totalAmount należ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ć:

  • mcpPartnerId - parametr uzyskany od PayU.
  • mcpFxTableId - id tabeli kursowej.
  • mcpCurrency - waluta początkowa - płacącego (baseCurrency) z tabeli kursowej;
  • mcpRate - exchangeRate (kurs) z tabeli kursowej;.
  • mcpAmount - przeliczona kwota w walucie końcowej sklepu (termCurrency).
Przykład obliczania mcpAmount:
  • mcpAmount = totalAmount / mcpRate
  • mcpAmount = 1000 / 4.2556
  • mcpAmount = round(234,98) = 235

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