Płatności wielowalutowe

1 Wprowadzenie

Płatności wielowalutowe (ang. Multi-Currency Pricing) to usługa umożliwiająca obciążenie klientów w różnych walutach bez potrzeby posiadania w PayU salda w tych walutach.

Usługa działa następująco:

  1. Sklep pobiera kursy walut w trybie dziennym od PayU.
  2. Sklep przelicza ceny towarów/usług z waluty bazowej (np. CZK, PLN) do walut przesłanych przez PayU (np. EUR, GBP, USD).
  3. Klienci mogą wybrać opcję zapłaty kartą płatniczą w każdej z walut (bazowej i przeliczonych).
  4. Sklep otrzymuje środki z PayU w walucie bazowej, nie ma konieczności utrzymywania salda w każdej z walut.

Usługa ta wymaga transparentnej integracji REST API oraz implementacji dodatkowego żądania w celu pobierania tabeli kursowej. Ponadto, komunikat OrderCreateRequest należy rozszerzyć o obiekt mcpData.

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

2 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 w której zostanie obciążony płatnik.
  • termCurrency - waluta bazowa, czyli waluta punktu płatności na którym będzie wykonana płatność.

3 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ę punktu płatności (POSa) i 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 - baseCurrency z tabeli kursowej.
  • mcpRate - użyty kurs.
  • mcpAmount - kwota walucie POSa (totalAmount) przeliczona do baseCurrency.

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