Overview

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

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

Poniższa metoda płatności jest na razie dostępne tylko dla płatności w PLN.

Nazwa Wartość transakcji Czas auto anulowania (dni) Opis
ai 300,00 - 20000,00 5 Raty PayU

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
b 0,50 - 999999,99 10 Przelew bankowy
pu W zależności od wyboru kanału płatności parametr przyjmuje wartość odpowiednią dla danego kanału płatności. Konto PayU. Więcej informacji o koncie PayU znajduje się w sekcji "Konto PayU"
ai 300,00 - 20000,00 5 Raty PayU
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 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 POST 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

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