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 Pobranie tabeli kursowej

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 (pary walut, kursy oraz token OAuth i mcpPartnerId są przykładowe):

curl -v -X GET https://secure.payu.com/api/v2_1/mcp-partners/b955e44b-f68f-42e1-ad6c-3735ba1e2954/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 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" 
  }
}