Wprowadzenie

1 Wprowadzenie

PayU umożliwia łatwą akceptację płatności na Twojej stronie lub urzadzeniu mobilnym.

Oferujemy pełen zestaw API, które pozwalają tworzyć, rozliczać, anulować i pobierać zamówienia, wykonywać wypłaty i pobierać raporty.

W celu uproszczenia integracji, można użyć jednej z naszych wtyczek lub naszego PHP SDK.

Ponadto, wiele platform sklepowych oferuje wbudowaną integrację z PayU. Jeśli platforma jakiej używasz do nich należy, postępuj zgodnie z podanymi w niej instrukcjami aby szybko skonfigurować płatność przez PayU.

1.1 Jak zacząć?

Na początek należy założyć konto PayU dla sprzedawców (obiorców płatności). Może to być konto produkcyjne (rejestruj lub skontaktuj się z partnerem PayU lub przedstawicielem handlowym) lub konto testowe na sandboksie (rejestruj).

Po zalogowaniu się do panelu administracyjnego konta PayU, stwórz Sklep i Punkt Płatności w typie REST API.

Uwaga: jeżli zacząłeś od razu od konta produkcyjnego, nie będzie ono w pełni aktywne, dopóki nie zostanie przez nas zakończona wymagana prawem weryfikacja. Jednakże płatność testowa dostępna jest dla Ciebie już od samego początku.

1.2 Model integracji

Przed rozpoczęciem integracji, warto wybrać jej właściwy model. Dostępne są różne opcje, a usługi i konfiguracja konta PayU mogą zależeć od odpowiedzi na poniższe pytania:

Czy każde zamówienie opłacone przez PayU będzie zrealizowane?

Jeśli nie, wyłącz auto-odbiór na swoim punkcie płatności i każdorazowo decyduj, czy zamówienie odebrać i rozliczyć lub anulować i zwrócić środki.

Czy sprzedawane są wysokokwotowe towary lub usługi?

Jeśli tak, zwiększ sprzedaż dzięki usłudze Raty | PayU.

Czy często będą wykonywane zwroty środków do płacących?

Jeśli tak, należy rozważyć wykonywanie zwrotów poprzez API zamiast wykonywać je poprzez Panel.

Czy chciałbyś umożliwić swoim klientom wybór metody płatności już na stronie Twojego serwisu?

Jeśli tak, zdecyduj się na "transparentną" integrację.

Czy dla swoich klientów będziesz tworzyć konta użytkowników?

Jeśli tak, użyj usługi PayU | Express a dane kart płatniczych Twoich klientów zostaną bezpiecznie zapisane w PayU. Dzięki temu przy kolejnej płatności nie będzie trzeba podawać numeru karty, a płatności będzie można dokonać jednym kliknięciem.

Czy będziesz cyklicznie obciążał swoich klientów (np. co miesiąc)?

Jeśli tak, skorzystaj z usługi płatności cyklicznych.

Czy masowo wystawiasz faktury, które wymagają płatności na dedykowane subkonta bankowe?

Jeśli tak, wdróż usługę Mass Collect.

Czy musisz rozliczać odebrane płatności z innymi podmiotami?

Jeśli tak użyj API do wypłat aby usprawnić rozliczenia ze swoimi partnerami biznesowymi.

Sprawdź naszą ofertę handlową, aby dowiedzieć się więcej.

1.3 Wsparcie integracji

Jeśli potrzebujesz pomocy, skontaktuj się z naszym działem wsparcia IT pod adresem tech@payu.pl.

W przypadku pytań o konkretne zamówienia i wywołania naszego API, podaj wartość nagłówka Correlation-Id w odpowiedzi zwróconej przez system PayU.

2 Przykłady

Strona płatności PayU

Kliknij przycisk - zostaniesz przekierowany na stronę podsumowania płatności serwowaną przez system PayU.

Powyższy przykład pokazuje integrację za pomocą formularza implementującego protokół REST API, zalecana jest jednak integracja za pomocą komunikatów JSON, ponieważ daje więcej możliwości rozszerzenia integracji.

Widget PayU

Kliknij w przycisk - wywoła on widget służący do bezpiecznego pobrania danych karty. Widget możesz również wlać w swoją stronę.

Aby zobaczyć wszystkie możliwości akceptacji płatności kartą zobacz sekcję poświęconą formatkom płatniczym.

3 Testowanie integracji

W przypadku integracji podstawowej, obejmującej jedynie przekierowanie na stronę PayU, w zupełności wystarczy użycie testowej metody płatności. Jednak w przypadku potrzeby testów wszystkich komunikatów API, łącznie z m.in. zwrotami, należy skorzystać z konta na sandboksie.

Poniżej znajduje się krótka list przypadków testowych. Sprawdź jak Twoja strona obsługuje następujące sytuacje:

  1. Czy po wykonaniu żądania POST na endpoint /api/v2_1/orders następuje przekierowanie na adres przekazany przez PayU w odpowiedzi z kodem HTTP 302?
  2. Czy Twój system odbiera i parsuje powiadomienia wysyłane przez PayU? Czy w odpowiedzi na powiadomienie wysyłany jest kod HTTP 200?
  3. Czy prawidłowo ustalasz status zamówienia w PayU? Pamiętaj, status zamówienia jest przekazywany wyłącznie w notyfikacji, status zwrócony w odpowiedzi dotyczy danego żądania, a nie całego zamówienia(!).
  4. Czy podajesz parametr continueUrl? Czy po zakończonej płatności użytkownik jest przekierowywany na ten adres?
  5. Czy obsługujesz komunikat o nieudanej płatności doklejany jako query string do adresu strony podanej jako continueUrl?
  6. Jak obsługujesz status REJECTED?*
  7. W przypadku integracji usługi PayU|Express, czy Twój system obsługuje wszystkie scenariusze uwierzytelnienia płatności?

* Status REJECTED zdarza się niekiedy dla niektórych płatności szybkimi przelewami. Oznacza on, że bank początkowo odpowiedział statusem CANCELED, ale później obciążył konto bankowe płacącego i przelał środki do PayU. W tym przypadku PayU wysyła powiadomienie o zmianie statusu. Możliwe opcje to: 1/ odebranie i realizacja zamówienia, 2/ anulowanie zamówienia w PayU, aby jak najszybciej zwrócić środki do płacącego, 3/ brak reakcji (zamówienie zostanie anulowane automatycznie, a środki zwrócone po liczbie dni podanej dla danej metody płatności. Aby zasymulować ten przypadek, należy: utworzyć zamówienie i wykonać przekierowanie (w celu uzyskania statusu PENDING), anulować płatność poprzez panel (status CANCELED), wrócić do strony płatności i dokończyć płatność (status REJECTED).

Opcje 1 i 2 mogą zostać wykonane poprzez Panel lub API.

3.1 Testowa płatność

Metoda "t" służy do generowania płatności testowych, środki pozyskane z takich transakcji nie są przekazywane do Sklepu. Metoda ta nie wymaga żadnych dodatkowych parametrów dla nowej płatności.

Transakcje testowe są domyślnie wyłączone, są również automatycznie blokowane po 3 dniach od ostatniego ich użycia. W celu przeprowadzania testów należy aktywować ten rodzaj płatności za pomocą opcji Moje sklepy > Nazwa sklepu > Lista punktów płatności > Nazwa punktu, następnie zmieniamy status dla „Płatności testowej” poprzez kliknięcie w kolumnie Stan.

Koniecznie pamiętaj o wyłączeniu tej metody, kiedy udostępnisz płatności swoim klientom!
Nazwa Wartość transakcji Czas auto anulowania (dni) Opis Księgowanie
t 0,50 - 1000,00 1 płatność testowa - zostanie wyświetlony formularz, w którym można bezpośrednio zmienić status transakcji

Płatności testowej można również użyć na produkcyjnym punkcie płatności:

Dane produkcyjnego POSa testowego

               
Id punktu płatności (pos_id):       145227
Drugi klucz (MD5):                  13a980d4f851f3d9a1cfc792fb1f5e50
Protokół OAuth (client_id):         145227
Protokół OAuth (client_secret):     12f071174cb7eb79d4aac5bc2f07563f

3.2 Sandbox

Sandbox to niemal identyczna kopia produkcyjnego systemu PayU, której można używać do integracji i testów. Aby skorzystać z sandboksa, należy się osobno zarejestrować (wymagany jest jedynie adres email). Po rejestracji, należy utworzyć sklepy i punkty płatności. Przydatne adresy:

Dane publicznego punktu płatności na sandboksie.

Można również skorzystać z publicznego POSa testowego bez rejestracji:

                
Id punktu płatności (pos_id):       300746
Drugi klucz (MD5):                  b6ca15b0d1020e8094d9b5f8d163db54
Protokół OAuth (client_id):         300746
Protokół OAuth (client_secret):     2ee86a66e5d97e3fadc400c9f19b065d

Karty na środowisku sandbox.

W celu przetestowania płatności kartą, należy użyć poniższych danych.

Wystawca Numer Miesiąc Rok CVV 3-D Secure Zachowanie
Visa 4444333322221111 01 19 123 nie Autoryzacja pozytywna
MasterCard 5434021016824014 01 19 123 nie Autoryzacja pozytywna
Maestro 5099802211165618 01 19 123 nie Autoryzacja pozytywna. CVV nie jest wymagane dla płatności jednym kliknięciem (PayU | Express)
Visa 4012001037141112 01 19 123 tak Autoryzacja pozytywna
Maestro 5000105018126595 01 19 123 nie Autoryzacja negatywna
Visa 4000398284360 01 19 123 nie Autoryzacja negatywna

Funkcjonalność na sandboxie.

Lista funkcjonalności możliwa do sprawdzenia na środowisku sandbox:

4 Metody płatności

Poniżej znajduje się lista metod płatności dostępnych poprzez PayU.

4.1 Metody płatności oparte na kartach płatniczych

Nazwa Wartość transakcji Czas auto anulowania (dni) Opis Księgowanie
c 0,50 - 999999,99 5 Karta płatnicza - płatność w każdej obsługiwanej walucie poza CZK i HUF 24h/7
c 3,00 - 999999,99 5 Karta płatnicza - płatność w CZK 24h/7
c 10,00 - 99999999,99 5 Karta płatnicza - transakcja w HUF 24h/7
ma tak jak powyżej dla kart płatniczych 5 Masterpass to źródło danych karty - autoryzacja i rozliczenie odbywa się tak jak dla standardowej transakcji kartą płatniczą. W Panelu oraz na zestawieniach, transakcje te oznaczone są tak samo jak inne płatności kartą, tj. używając wartości 'ma' można wywołać płatność metodą Masterpass, jednak utworzona płatność będzie już oznaczona metodą 'c'. O fakcie użycia Masterpass mówi parametr "payment flow", dostępny poprzez payment/get lub Transaction Data Retrieve. 24h/7
vc tak jak powyżej dla kart płatniczych 5 Visa Checkout to źródło danych karty - autoryzacja i rozliczenie odbywa się tak jak dla standardowej transakcji kartą płatniczą. W Panelu oraz na zestawieniach, transakcje te oznaczone są tak samo jak inne płatności kartą, tj. używając wartości 'vc' można wywołać płatność metodą Visa Checkout, jednak utworzona płatność będzie już oznaczona metodą 'c'. O fakcie użycia Visa Checkout mówi parametr "payment flow", dostępny poprzez payment/get lub Transaction Data Retrieve. 24h/7

4.2 Raty i Płacę poźniej

Poniższe metody płatności są na razie dostępne tylko dla waluty PLN.

Nazwa Wartość transakcji Czas auto anulowania (dni) Opis
ai 300,00 - 20000,00 5 PayU | Raty
dp 100,00 - 2000,00 5 PayU | Płacę później

4.3 Szybkie przelewy pay-by-link w PLN

Nazwa Wartość transakcji (PLN) Czas auto anulowania (dni) Opis Księgowanie
blik 1,00 - 999999,99 10 BLIK 24h/7
m 0,37 - 999999,99 10 mTransfer - mBank 24h/7
mtex 1,00 - 999999,99 10 mTransfer mobilny - mBank(*) 24h/7
w 0,37 - 7000,00 10 BZWBK - Przelew24 24h/7
o 0,37 - 999999,99 10 Pekao24Przelew - Bank Pekao 24h/7
i 0,37 - 999999,99 10 Płacę z Inteligo 24h/7
p 0,37 - 999999,99 10 Płać z iPKO 24h/7
pkex 1,00 - 999999,99 10 PayU Express Bank Pekao(*) 24h/7
g 0,37 - 999999,99 10 Płać z ING 24h/7
gbx 1,00 - 999999,99 10 Płacę z Getin Bank 24h/7
gbex 1,00 - 999999,99 10 GetIn Bank PayU Express(*) 24h/7
nlx 1,00 - 999999,99 10 Płacę z Noble Bank 24h/7
nlex 1,00 - 999999,99 10 Noble Bank PayU Express(*) 24h/7
ib 0,50 - 999999,99 10 Paylink Idea - IdeaBank 03:00-22:00
l 0,50 - 999999,99 10 Credit Agricole 03:00-24:00
as 0,37 - 999999,99 10 Płacę z T-mobile Usługi Bankowe dostarczane przez Alior Bank 24h/7
exas 1,00 - 500 (po przekroczeniu max. wartości lub w przypadku negatywnej oceny ryzyka transakcji przez PayU transakcja jest realizowana typem płatności  Płacę z T-mobile Usługi Bankowe dostarczane przez Alior Bank [as]) 10 PayU Express T-mobile Usługi Bankowe(*) 24h/7
u 0,37 - 999999,99 10 Eurobank 05:00-22:00
ab 0,37 - 999999,99 10 Płacę z Alior Bankiem 24h/7
exab 0,37-500 (po przekroczeniu max. wartości lub w przypadku negatywnej oceny ryzyka transakcji przez PayU transakcja jest realizowana typem płatności  Płacę z AliorBankiem [ab]) 10 PayU Express z Alior Bankiem(*) 24h/7
ps 0,37 - 999999,99 10 Płacę z PBS 1:30-23:30
wm 0,37 - 999999,99 10 Przelew z Millennium 24h/7
wd 0,50 - 999999,99 10 Przelew z Deutsche Banku 24h/7
wr 1,00 - 999999,99 10 Raiffeisen POLBANK(**) 05:00-22:00
wc 0,37 - 999999,99 10 Przelew z Citi Handlowego 24h/7
bo 0,37 - 999999,99 10 Płać z BOŚ 24h/7
bnx 0,37 - 999999,99 10 Płacę z BNP Paribas 24h/7
bnex 0,37 - 999999,99 10 BNP Paribas PayU Express(*) 24h/7
orx 1,00 - 999999,99 10 Płacę z Orange 24h/7
orex 1,00 - 999999,99 10 PayU Express Orange(*) 24h/7
bs 0,50 - 999999,99 10 Banki Spółdzielcze
sgb 0,50 - 999999,99 10 SGB-Bank
plsb 0,50 - 999999,99 10 Plus Bank
b 0,50 - 999999,99 10 Przelew bankowy
t 0,50 - 1000,00 1 płatność testowa - zostanie wyświetlony formularz, w którym można bezpośrednio zmienić status transakcji

(*) typ platności dostepny jest dla: Konta PayU oraz PayU | Express

(**) proces półautomatyczny

4.4 Szybkie przelewy pay-by-link w CZK

Nazwa Wartość transakcji (CZK) Czas auto anulowania (dni) Opis
cs 3,00 - 999999,99 10 PLATBA 24 - Česká spořitelna
mp 3,00 - 999999,99 10 mTransfer - mBank
kb 3,00 - 999999,99 10 MojePlatba – Komerční banka
rf 3,00 - 999999,99 10 ePlatby pro eKonto - Raiffeisenbank
pg 3,00 - 999999,99 10 Moneta Money Bank
pv 3,00 - 999999,99 10 Sberbank
pf 3,00 - 999999,99 10 Fio banka
era 3,00 - 999999,99 10 Era - Poštovní spořitelna
cb 3,00 - 999999,99 10 ČSOB
uc 3,00 - 999999,99 10 UniCredit
bt 3,00 - 999999,99 14 Bankovní převod
pt 3,00 - 999999,99 14 Převod přes poštu (poštovní poukázkou)

4.5 Międzynarodowe metody płatności

Poniższe metody są dostępne tylko dla płatności w EUR. Skontaktuj się z opiekunem handlowym w celu ich udostępnienia.
Nazwa Wartość transakcji (EUR) Czas auto anulowania (dni) Opis
gp 1,00 - 999999,99 10 GiroPay
it 1,00 - 999999,99 10 InstantTransfer
pscd 1,00 - 1000,00 10 PaySafeCard
sp 1,00 - 999999,99 10 SafetyPay
sb 1,00 - 999999,99 10 Sofort Banking
trp 1,00 - 999999,99 10 TrustPay

5 Dostępne waluty

Transakcje płatnicze w walutach wymienionych poniżej są rozliczane jeden do jednego (płatnik jest obciążony w tej samej walucie, w której następuje wypłata środków do odbiorcy płatności) poza oznaczonymi znakiem * które są rozliczane w EUR.

W zależności od wybranej waluty mogą wystąpić dodatkowe opłaty i ograniczenia częstotliwości wypłat.

Dostępne metody płatności zależą od waluty - karty są dostępne dla każdej, a inne metody (np. szybkie przelewy) są dostępne tylko dla CZK, EUR and PLN.

Kod Nazwa
BGN* lewa bułgarska
CHF frank szwajcarski
CZK korona czeska
DKK korona duńska
EUR euro
GBP funt szterling
HRK kuna chorwacka
HUF forint węgierski
NOK korona norweska
PLN złoty polski
RON lej rumuński
RUB* rubel rosyjski
SEK korona szwedzka
UAH* hrywna ukraińska
USD dolar amerykański

6 Dostępne wersje językowe

Poniższe parametry mogą być podane jako wartość pola language w obiekcie <Buyer>.

Tabela pokazuje wersje językowe dla strony wyboru metody płatności ("paywall"), formatki płatności kartą oraz wiadomości email z informacjami o płatności wysyłanej do płatnika.

Kod Język Strona wyboru metody Formatka kartowa Email
pl polski tak tak tak
en angielski tak tak tak
cs czeski tak tak tak
bg bułgarski nie tak nie
de niemiecki tak tak nie
el grecki nie tak tak
es hiszpański nie tak tak
et estoński nie tak nie
fi fiński nie tak nie
fr francuski nie tak nie
hr chorwacki nie tak nie
hu węgierski nie tak tak
it włoski nie tak tak
lt litewski nie tak tak
lv łotewski nie tak tak
pt portugalski nie tak nie
ro rumuński nie tak tak
ru rosyjski nie tak nie
sk słowacki nie tak nie
sl słoweński nie tak nie
sv szwedzki nie tak tak
uk ukraiński nie tak tak

7 Zestawienie endpointów

Przed rozpoczęciem analizy pełnej dokumentacji REST API, warto zapoznać się z wszystkim żądaniami oferowanymi w tym protokole integracji.

Adres hosta

Produkcja:

https://secure.payu.com/

Sandbox:

https://secure.snd.payu.com/
Adres Metoda HTTP Komentarz Pełne omówienie
/pl/standard/user/oauth/authorize POST Dostarcza token autoryzacyjny (OAuth). Uwierzytelnienie komunikatów
api/v2_1/paymethods GET Dostarcza aktualnie dostępne metody płatności. Pobranie metod płatności
/api/v2_1/orders POST Tworzy zamówienie i umożliwia przeprowadzenie płatności. Tworzenie nowego zamówienia przez API
/api/v2_1/orders/{orderId} GET Pozwala pobrać dane i status zamówienia. Pobrania danych zamówienia
/api/v2_1/orders/{orderId} DELETE Pozwala anulować zamówienie. Anulowanie zamówienia
/api/v2_1/orders/{orderId}/transactions GET Pozwala pobrać szczegóły płatności (dane konta bankowego lub karty płatniczej). Pobranie danych transakcji
/api/v2_1/orders/{orderId}/status PUT Pozwala odebrać (rozliczyć) opłacone zamówienie. Odebranie zamówienia
/api/v2_1/orders/{orderId}/refunds POST Pozwala na pełne lub częściowe zwroty (uznania) do płatności. Zwroty
/api/v2_1/payouts POST Pozwala zlecić wypłatę bezpośrednio z aplikacji sklepu (wypłaty automatyczne i ad hoc są też dostępne poprzez Panel). Wypłaty
api/v2_1/mcp-partners/{mcpPartnerId}/fx-table GET Pozwala pobrać tabelę kursową. Płatności wielowalutowe
/api/v2_1/reports/{reportId} GET Pozwala pobrać wygenerowane zestawienie transakcji (zestawienia automatyczne i ad hoc są też dostępne poprzez Panel). Zestawienia transakcji
/api/visa-checkout/proxy/payment/data/{callId} GET Pozwala pobrać dane (maskowany numer karty, adres wysyłki itp.) z Visa Checkout. Visa Checkout

8 Szyfrowanie połączenia

Od 30 czerwca 2018 PayU wspierać będzie wyłącznie protokół TLS 1.2.

Zaprzestanie wspierania starszych protokołów jest podyktowane względami bezpieczeństwa. Protokół TLS 1.2 to najlepszy sposób szyfrowania połączenia, zgodny z najwyższym standardem bezpieczeństwa PCI DSS 3.2.

Zmiana dotyczy wszelkiej komunikacji za pomocą HTTPS z systemem PayU i obejmuje wszystkie adresy REST API i Classic API.

Większość dostawców rozwiązań e-commerce oraz firm hostingowych dba o aktualizację oprogramowania, dlatego jeśli Twój serwis działa na gotowej platformie, najprawdopodobniej nie masz się czego obawiać. Możesz skontaktować się z dostawcami usług i zapytać, czy dokonali tej aktualizacji.

Jeśli Twój serwis korzysta z dedykowanego rozwiązania, upewnij się, że jest oparte o aktualną wersję protokołu. Poniższe informacje mogą być przydatne.

JAVA

Java 1.5 i wersje niższe nie wspierają TLS 1.2. Dla Javy 1.6, TLS 1.2 nie jest wspierany w publicznych aktualizacjach. Protokół ten jest wspierany w business editions od Oracle java version 6u115 b32.

W Java 1.7, TLS 1.2 jest wspierany, ale musi być jawnie włączony poprzez wybór protokołu w czasie tworzenia instancji SSLSocket & SSLEngine.

Więcej szczegółów: https://blogs.oracle.com/java-platform-group/jdk-8-will-use-tls-12-as-default

cURL

Curl wspiera TLS 1.2 od wersji 7.34.0. Poniższe polecenie testuje wersję szyfrowania połączenia.

Uwaga: test można wykonać dla dowolnego adresu - zob. zestawienie adresów REST API i Classic API.

curl --tlsv1.2 https://secure.payu.com/api/v2_1/orders
Jeśli połączenie działa, pojawi się komunikat "Unauthorized".

cURL+PHP

                    php -r '$ch = curl_init(); 
                    curl_setopt($ch, CURLOPT_URL, "https://secure.payu.com/api/v2_1/orders"); 
                    curl_setopt ($ch, CURLOPT_SSLVERSION, 6); 
                    var_dump(curl_exec($ch)); 
                    var_dump(curl_error($ch));'               
Jeśli połączenie działa, pojawi się komunikat "Unauthorized". TLS 1.1 i TLS 1.2 są wspierane od wersji OpenSSL 1.0.1. Wymuszanie TLS 1.1 i 1.2 jest wspierane dopiero od curl 7.34.0.

9 Terminologia

PayU Licencjonowany dostawca usług płatniczych (tzw. PSP) oraz acquirer (członek organizacji Visa i MasterCard). Dla celów tej dokumentacji PayU oznacza także aplikację do rozliczania płatności.
Merchant Merchant (lub akceptant płatności) to podmiot, który zawarł umowę z PayU i został zarejestrowany w PayU. Na poziomie aplikacji PayU, "merchant" to zestaw encji: Firma/Sklep/POS (zob. wpisy poniżej).
Panel Panel Menadżera lub Panel Administracyjny to interfejs użytkownika aplikacji PayU udostępniany merchantom. Odnośnik do panelu jest wysyłany do użytkowników w trakcie rejestracji merchanta w PayU. Opis panelu można pobrać tutaj.
Firma Podmiot korzystający z mechanizmów PayU w celu odbioru środków pieniężnych od klienta. Cechami Firmy są nazwa, adres, numer identyfikacji podatkowej itp.
Sklep Sklep internetowy odbierający płatności; jedna firma może posiadać kilka sklepów.
POS / punkt płatności Punkt usługowy realizujący odbieranie płatności. Dla danego punktu usługowego definiowane są wszystkie parametry usługi. Jeden Sklep może posiadać kilka punktów usługowych.
Klient / Płacący / Kupujący Osoba dokonująca płatności, klient sklepu internetowego.