Classic API (NewPayment)

1 Ważne

Dokumentacja Classic API udostępniana tylko dla istniejących integracji - jeśli chcesz integrować usługi PayU, użyj REST API. Protokół Classic API nie jest już rozwijany i wszelkie nowe usługi są udostępniane poprzez REST API.

2 Tworzenie nowej płatności

W celu utworzenia nowej płatności należy na swojej stronie umieścić odpowiedni formularz, który przekieruje klienta do serwisu PayU do procedury NewPayment (patrz: "adresy aplikacji PayU"). Zalecane jest korzystanie z metody POST, jeżeli jest to utrudnione można ewentualnie użyć metody GET. Lista parametrów oraz ich znaczenie zawarta jest na podstronie: "parametry nowej płatności".

Po zakończonej płatności Klient zostanie przekierowany na adres Adres powrotu - poprawnie lub Adres powrotu - błąd za pomocą metody GET. Może się też zdarzyć, że Klient nie powróci wcale do aplikacji Sklepu, dlatego informacja przekazywana za pomocą tych adresów nie ma znaczenia wiążącego, nie można na jej podstawie podejmować żadnych decyzji dotyczących płatności.

Sposób przekazywania informacji o transakcjach jest opisany na podstronie: "wymiana informacji".

Przykładowy formularz z minimalną liczbą parametrów:

<form action="https://secure.payu.com/paygw/UTF/NewPayment" method="POST" name="payform">
    Name: <input type="text" name="first_name" value=""><br/>
    Surname: <input type="text" name="last_name" value=""><br/>
    E-mail: <input type="text" name="email" value=""><br/>
    <input type="hidden" name="pos_id" value="178893">
    <input type="hidden" name="pos_auth_key" value="gQJQrgD">
    <input type="hidden" name="session_id" value="Yy0cyTCtkbiR7LOpNzrkddZXkgbFbo6A.">
    <input type="hidden" name="amount" value="1000">
    <input type="hidden" name="desc" value="Opis płatności">
    <input type="hidden" name="client_ip" value="123.123.123.123">
    <input type="hidden" name="js" value="0">
    <input type="hidden" name="ts" value="124321878">
    <input type="hidden" name="sig" value="9920f89e75c6c47135a1f1357d0ad9f415fc8a990de8cfa428319ae3bb20c7d3">
    <input type="submit" value="Zapłać poprzez PayU">
</form>
<script language="JavaScript" type="text/javascript">
    <!--
    document.forms['payform'].js.value=1;
    -->
</script>

3 Parametry nowej płatności

Parametr Wymagany Typ danych Opis
pos_id Tak INT wartość nadana przez PayU
pos_auth_key Tak STR {7,7} wartość nadana przez PayU
pay_type Nie ENUM opcjonalny1
session_id Tak STR {1,1024} identyfikator płatności - unikalny dla klienta (para identyfikatorów pos_id, session_id musi być unikalna w systemie - czyli session_id nie może się powtórzyć w ramach tego samego POS’a)
amount Tak NUM {1,10} kwota w groszach
desc Tak STR {1,50} krótki opis - pokazywany klientowi, trafia na wyciągi
order_id Nie STR {1,1024} numer zamówienia
desc2 Nie STR {0,1024} dowolna informacja
trsDesc Nie STR {0,27} dodatkowy opis transakcji dla przelewów bankowych
first_name Tak STR {1,100} imię
last_name Tak STR {1,100} nazwisko
street Nie STR {0,100} ulica
street_hn Nie STR {0,10} numer domu
street_an Nie STR {0,10} numer mieszkania
city Nie STR {0,100} miasto
post_code Nie STR {0,20} kod pocztowy
country Nie STR {0,100} kod kraju klienta (dwuliterowy) zgodnie z ISO-3166
email Tak STR {1,100} adres email
phone Nie STR {0,100} numer telefonu, można podać kilka numerów rozdzielając je przecinakami
language Nie ENUM kod języka zgodnie z ISO-639-1 - pozwala sterować językiem strony wyboru metody płatności serwowanej przez PayU (dostępne wersje: cs, en i pl); uwaga: język formularza do płatności kartą jest wykrywany automatycznie - zob. dostępne wersje językowe
client_ip Tak STR {7,15} adres IP klienta w formacie D{1,3}.D{1,3}.D{1,3}.D{1,3}
js Nie ENUM (0,1) wartość określa czy przeglądarka klienta ma włączoną obsługę JavaScript
sig Tak STR {64} suma kontrolna przesyłanych parametrów formularza2
ts Tak STR znacznik czasowy wykorzystywany do obliczenia wartości sig

W zależności od typu płatności, może być wymagane podanie wartości oznaczonych w tej tabelce jako niewymagane. Dodatkowe informacje znajdują się przy opisach poszczególnych typów płatności na podstronie "typy płatności".

1 W przypadku braku parametru pay_type wyświetli się okno z wyborem wszystkich typów płatności dostępnych dla danego pos_id (lista typów płatności dostępna na podstronie: "typy płatności")

2Więcej informacji: "podpisywanie parametrów"

4 Statusy transakcji

Wartość Opis
1 nowa
2 anulowana
3 odrzucona
4 rozpoczęta
5 oczekuje na odbiór
7 płatność zwrócona, otrzymano środki od klienta po wcześniejszym anulowaniu transakcji, lub nie było możliwości zwrotu środków w sposób automatyczny, sytuacje takie będą monitorowane i wyjaśniane przez zespół PayU
99 płatność odebrana - zakończona
888 błędny status - prosimy o kontakt

Dodatkowe informacje o statusach transakcji

Status 2 „anulowana” pojawi się automatycznie po określonej liczbie dni (patrz: "typy płatności") od utworzenia lub rozpoczęcia transakcji (Statusy 1 lub 4), jeśli do tego czasu nie zostanie ona rozliczona (nie wpłyną środki do systemu PayU). Status ten pojawi się również po wywołaniu akcji „anuluj” w panelu administracyjnym bądź po wywołaniu metody Payment/cancel dla transakcji będącej w statusie 1 lub 4.
Status 3 „odrzucona” pojawi się wówczas, gdy użytkownik dla transakcji będącej w statusie 5 -„oczekuje na odbiór” wywoła akcję „anuluj” w panelu lub metodę Payment/cancel, a wybrany typ płatności nie pozwala na automatyczne zwrócenie środków do klienta (czyli w większości dostępnych typów płatności). Status 3 - „odrzucona” pojawi się również gdy w przypadku „anulowanej” (status 2) transakcji nastąpi jej rozliczenie (wpływ środków do systemu PayU). W przypadku odebrania transakcji (akcja „odbierz” w panelu lub wywołanie metody Payment/confirm ), która posiada status 3 - „odrzucona” transakcja przejdzie do statusu 99 - „zakończona” (zarówno w przypadku gdy sklep ma włączony autoodbiór jak i w przypadku gdy nie ma włączonego autoodbioru). W przypadku gdy zaś chcemy zwrócić do klienta środki z transakcji będącej w statusie 3, należy wykonać dla tej transakcji akcję „anuluj” w panelu bądź wywołać metodę Payment/cancel.
Status 4 „rozpoczęta” jest stanem pośrednim i nie musi wystąpić transakcja może przejść do stanu „oczekuje na odbiór” lub „zakończona” (w przypadku włączonej opcji autoodbiór wpłat) bezpośrednio ze stanu „nowa”.
Status 5 „oczekuje na odbiór” pojawi się tylko wtedy gdy mamy wyłączoną opcje „Automatyczne odbieranie”, w takim przypadku Sklep ma określoną ilość dni na odebranie płatności (czas ten jest zgodny z czasem automatycznego anulowania płatności podanym w tabeli na podstronie "Typy płatności" i ustalany odrębnie dla każdego typu płatności). Gdy płatność taka nie zostanie odebrana w odpowiednim terminie zostanie ona automatycznie anulowana. Odebranie płatności należy wykonać wywołując metodę Payment/confirm lub poprzez panel administracyjny serwisu.
Status 7 „zwrócona” pojawi się wówczas gdy transakcja ma status 3 „odrzucona” a użytkownik wykona akcję „anuluj” w panelu lub wywoła metodę Payment/cancel.

4.1 Przejścia pomiędzy stanami transakcji

W przypadku wyłączonej opcji autoodbioru wpłat:

W przypadku włączonej opcji autoodbioru wpłat:

5 Kody błędów

Wartość Opis
100 brak lub błędna wartość parametru pos_id
101 brak parametru session_id
102 brak parametru ts
103 brak lub błędna wartość parametru sig
104 brak parametru desc
105 brak parametru client_ip
106 brak parametru first_name
107 brak parametru last_name
108 brak parametru street
109 brak parametru city
110 brak parametru post_code
111 brak parametru amount
112 błędny numer konta bankowego
113 brak parametru email
114 brak numeru telefonu
200 inny chwilowy błąd
201 inny chwilowy błąd bazy danych
202 POS o podanym identyfikatorze jest zablokowany
203 niedozwolona wartość pay_type dla danego parametru pos_id
204 podana metoda płatności (wartość pay_type) jest chwilowo zablokowana dla danego parametru pos_id, np. przerwa konserwacyjna bramki płatniczej
205 kwota transakcji mniejsza od wartości minimalnej
206 kwota transakcji większa od wartości maksymalnej
207 przekroczona wartość wszystkich transakcji dla jednego klienta w ostatnim przedziale czasowym
208 POS działa w wariancie ExpressPayment lecz nie nastąpiła aktywacja tego wariantu współpracy (czekamy na zgodę działu obsługi klienta)
209 błędny numer pos_id lub pos_auth_key
211 nieprawidłowa waluta transakcji
212 próba utworzenia transakcji częściej niż raz na minutę - dla nieaktywnej firmy
500 transakcja nie istnieje
501 brak autoryzacji dla danej transakcji
502 transakcja rozpoczęta wcześniej
503 autoryzacja do transakcji była już przeprowadzana
504 transakcja anulowana wcześniej
505 transakcja przekazana do odbioru wcześniej
506 transakcja już odebrana
507 błąd podczas zwrotu środków do Klienta
508 Klient zrezygnował z płatności
599 błędny stan transakcji, np. nie można uznać transakcji kilka razy lub inny, prosimy o kontakt
777 utworzenie transakcji spowoduje przekroczenie limitu transakcji dla firmy w trakcie weryfikacji, weryfikacja odbędzie się w ciągu jednego dnia roboczego
999 inny błąd krytyczny - prosimy ponowić operację

6 Konstrukcja adresów UrlPozytywny i UrlNegatywny

Po zakończonym procesie płatności Klient może zostać przekierowany pod podany przez Sklep adres URL. W zależności od statusu transakcji zostanie wykorzystany odpowiedni adres UrlPozytywny lub UrlNegatywny. Adresy powrotu do Sklepu mają tylko charakter informacyjny, nie można na ich podstawie podejmować żadnych decyzji.

Adresy powrotu mogą zawierać następujące stałe, które zostaną zamienione na odpowiednie wartości zgodnie z poniższą tabelką:

Stała Opis
%transId% identyfikator nowej transakcji utworzonej w aplikacji PayU
%posId% wartości pos_id
%payType% wartości pay_type
%sessionId% wartości session_id
%amountPS% wartości amount - jako separator kropka
%amountCS% wartości amount - jako separator przecinek
%orderId% wartości order_id
%error% numer błędu zgodnie z tabelką podaną na podstronie "kody błędów" jest wykorzystywany tylko przy Adres powrotu - błąd

Przykłady:

http://www.sklep.pl/status_ok.html?pos_id=%posId%&session_id=%sessionId%

http://www.sklep.pl/status_error.html?pos_id=%posId%&session_id=%sessionId%&error=%error%

7 Adresy aplikacji PayU oraz dostępne procedury

Adres URL dla aplikacji PayU tworzymy według następującego schematu:

URL = UrlSecure.payu.com.pl/Kodowanie/NazwaProcedury

gdzie:

UrlSecure.payu.com Adres bazowy aplikacji PayU (https://secure.payu.com/paygw)
Kodowanie Jedna z wartości: ISO, UTF, WIN
Nazwa procedury Jedna z wartości: NewPayment, Payment/get, Payment/confirm, Payment/cancel

7.1 Kodowanie

W zależności od tego, jakiej strony kodowej używa aplikacja Sklepu należy wybrać odpowiednie kodowanie przy odwołaniu do procedur PayU, i tak:

Nazwa w PayU Użyte kodowanie
ISO ISO-8859-2
UTF UTF-8
WIN Windows-1250

Wybrane kodowanie powinno być zgodne z kodowaniem ustawionym na danym POSie (punkcie płatności).

7.2 Format danych

Dla procedur: Payment/get, Payment/confirm, Payment/cancel, możemy jeszcze podać format w jakim mają być przesłane dane, czyli mamy następujący schemat:

URL = UrlSecure.payu.com/Kodowanie/Nazwa Procedury/Format

gdzie Format może być jedną z wartości: „xml” lub „txt”, domyślnie jest wybierany „xml”.

8 Podpisywanie parametrów przekazywanych do nowej płatności

Aplikacja Sklepu musi dodać do formularza nowej płatności (NewPayment) sumę kontrolną wszystkich przekazywanych parametrów.

W tym celu dodajemy do formularza dodatkowy parametr:

sig Podpis przesłanej informacji

Algorytm generowania podpisu parametrów formularza

  1. Posortuj wszystkie pola formularza alfabetycznie według nazw parametrów (atrybut name elementu input) w porządku rosnącym. Jeżeli dana wartość nie jest przekazywana w formularzu tworzącym nową płatność używamy pustego ciągu znaków.
  2. Dokonaj konkatenacji kluczy i wartości wszystkich pól formularza zgodnie z wcześniej wyznaczonym porządkiem (klucz=wartość), rozdzielając je znakiem ampersand &. Wartości parametrów muszą być poddane kodowaniu URL (URL encoding, application/x-www-form-urlencoded, znak spacji zamieniany na '+') przy użyciu odpowiedniego kodowania strony.
  3. Do tak powstałego ciągu znaków dodaj swój klucz prywatny (widoczny w Panelu Managera jako Drugi klucz (MD5)).
  4. Użyj funkcji skrótu SHA-256.

W przypadku gdy wartość sig zostanie błędnie wyliczona lub zostaną zmienione wartości innych przekazywanych parametrów nowa płatność nie zostanie utworzona. Klient zostanie przekierowany na UrlNegatywny z kodem błędu 103.

Pseudokod algorytmu generowania podpisu parametrów formularza

generate_signature(form, secondKey, posId) {
    sortedValues = sortValuesByItsName(form)

    foreach value in sortedValues {
        content = content + parameterName + "=" + urlencode(value) + "&"
    }

    content = content + secondKey
        
    return sha256(content)
    }

Podpis przykładowego formularza

Przykładowe wartości formularza do podpisu:
<form action="https://secure.payu.com/paygw/UTF/NewPayment" method="POST" name="payform">
    Name: <input type="text" name="first_name" value="Dagmara Maria"><br/>
    Surname: <input type="text" name="last_name" value="Testowa"><br/>
    E-mail: <input type="text" name="email" value="email@email.com"><br/>
    <input type="hidden" name="pos_id" value="999999">
    <input type="hidden" name="pos_auth_key" value="abcDEF">
    <input type="hidden" name="session_id" value="Zz0cyTCtkbiR7LOpNzrkddZXkgbFbo6A.">
    <input type="hidden" name="amount" value="1000">
    <input type="hidden" name="desc" value="Opis płatności">
    <input type="hidden" name="client_ip" value="123.123.123.123">
    <input type="hidden" name="js" value="1">
    <input type="hidden" name="ts" value="124321879">
    <input type="submit" value="Pay via PayU">
</form>
Posortowanie wszystkich pól formularza alfabetycznie według nazw parametrów oraz dokonanie konkatenacji kluczy i wartości wszystkich pól formularza zgodnie z wcześniej wyznaczonym porządkiem (klucz=wartość), rozdzielając je znakiem ampersand & z dodanym na końcu swoim kluczem prywatnym (widocznym w Panelu Managera jako Drugi klucz (MD5)). W tym przykładzie użyjemy fałszywego klucza 098f6bcd4621d373cade4e832627b4f6:
amount=1000&client_ip=123.123.123.123&desc=Opis+p%C5%82atno%C5%9Bci&email=email%40email.com&first_name=Dagmara+Maria&js=1&last_name=Testowa&pos_auth_key=abcDEF&pos_id=999999&session_id=Zz0cyTCtkbiR7LOpNzrkddZXkgbFbo6A.&ts=124321879&098f6bcd4621d373cade4e832627b4f6
Powyższa wartość jest użyta do podpisu za pomocą funkcji skrótu SHA-256:
2d373a18641fbd6bcea6c86ec2c0554fa28eed244a2649bb638ee600a66100d2                
Element formularza zawierający wygenerowany podpis:
<input type="hidden" name="sig" value="2d373a18641fbd6bcea6c86ec2c0554fa28eed244a2649bb638ee600a66100d2">

W przypadku pytań prosimy o kontakt z zespołem wsparcia IT: tech@payu.pl.

9 Wymiana informacji o transakcjach

Aplikacja Sklepu jest zobowiązana do sprawdzania podpisów przekazywanych informacji.

Każde przesłanie polecania (z wyjątkiem utworzenia nowej płatności) oraz każda odpowiedź generowana przez PayU zawiera podpis MD5, dzięki temu można zweryfikować poprawność danych.

Podpisy tworzymy według następującego schematu (znak „+” - oznacza operację łączenia łańcuchów znaków):

sig = md5( pos_id + session_id + value1 + value2 + ... + valuen + ts + key )

gdzie

pos_id Wartość nadana przez PayU
session_id Identyfikator płatności - unikalny dla klienta
wartosc1...n Lista dodatkowych wartości, zostanie podana przy opisie poszczególnych metod
ts Dowolny losowy ciąg znaków, proponowany aktualny czas w sekundach
key Ciąg znaków znany przez PayU oraz Sklep

W aplikacji PayU dla danego pos_id są przypisane dwie wartości key:

key1 - klucz używany podczas sprawdzania podpisu przysłanego przez Sklep (widoczny jako Klucz(MD5) w Panelu Managera)

key2 - klucz używany do generowania podpisu wysyłanego do Sklepu (Drugi Klucz(MD5) w Panelu Managera)

9.1 Powiadamianie sklepu o zmianie statusu transakcji

Każdorazowa zmian stanu transakcji jest raportowana do aplikacji Sklepu. Na podany adres raportów jest wysyłane żądanie POST z następującymi parametrami:

Nazwa Opis
pos_id identyfikator POS’a
session_id wartość podana przez Sklep w trakcie tworzenia płatności wartość podana przez Sklep w trakcie tworzenia płatności
ts znacznik czasowy, wartość potrzebna w celu weryfikacji podpisu
sig podpis przesłanej informacji

Gdzie wartość sig, obliczamy według następującego wzoru:

sig = md5( pos_id + session_id + ts + key2 )

Wysłanie komunikatu o zmianie statusu transakcji nie niesie żadnej informacji, szczegóły transakcji i jej aktualny status aplikacja Sklepu MUSI odczytać i odpowiednio przeanalizować samodzielnie za pomocą mechanizmów opisanych na podstronie "wymiana informacji" (sekcja "odczytywanie stanu transakcji").

Po otrzymaniu takiego wywołania aplikacja Sklepu MUSI w odpowiedzi wysłać ciąg znaków „OK”, w przypadku otrzymania innej odpowiedzi zostanie ona zapisana w bazie i powiadomienie będzie uznane jako nieodebrane.

Aplikacja Sklepu powinna uwzględnić sytuację, gdy powiadomie zostanie wysłane kilka razy dla tej samej transakcji o tym samym statusie. Na każde powtórzone powiadomienie też należy odpowiedzieć „OK”.

Dla jednego POS’a w tym samym czasie jest wysyłane jedno żądanie POST, należy jednak uwzględnić możliwość wysłania kilku żądań równolegle dla tego samego POS’a.

Powiadomienia są wysyłane natychmiast po zmianie statusu płatności, w przypadku gdy powiadomienie nie zostanie odebrane przez aplikację Sklepu zostanie ono wysłane ponownie po zadanym czasie zgodnie z poniższą tabelką:

Próba Opóźnienie
0 - 10 1 minuta
11 - 15 3 minuty
16 - 20 5 minut
21 - 25 10 minut
26 - 50 15 minut
51 - 75 30 minut
76 - 99 60 minut
>= 100 stop wysyłania

9.2 Odczytywanie stanu transakcji

W celu odczytania aktualnego stanu transakcji należy wywołać procedurę Payment/get (patrz: "adresy aplikacji PayU") metodą POST, podając następujące parametry:

Nazwa Opis
pos_id identyfikator POS’a
session_id wartość podana przez Sklep w trakcie tworzenia płatności
ts znacznik czasowy, wartość potrzebna w celu weryfikacji podpisu
sig podpis przesłanej informacji (patrz: "podpisy MD5")

Gdzie wartość sig, obliczamy według następującego wzoru:

sig = md5( pos_id + session_id + ts + key1 )

W odpowiedzi otrzymamy następujące strony zawierające informacje

Format „txt”:

status:OK
trans_id:7
trans_pos_id:1
trans_session_id:417419
trans_order_id:
trans_amount:200
trans_status:5
trans_pay_type:t
trans_pay_gw_name:pt
trans_desc:Wpłatadlatest@test.pl
trans_desc2:
trans_create:2004-08-2310:39:52
trans_init:2004-08-3113:42:43
trans_sent:2004-08-3113:48:13
trans_recv:
trans_cancel:
trans_auth_fraud:0
trans_ts:1094205761232
trans_sig:b6d68525f724a6d69fb1260874924759
trans_add_client_name: JAN KOWALSKI
trans_add_client_street: UL.NOWOWIEJSKIEGO 8
trans_add_client_city: WARSZAWA
trans_add_client_post_code: 02-638
trans_add_client_account: 80607787095718703296721164
trans_add_client_address: 
            

Format „xml”:

<?xml version="1.0"encoding="UTF-8" ?>
<response>
    <status>OK</status>
    <trans>
        <id>7</id>
        <pos_id>1</pos_id>
        <session_id>417419</session_id>
        <order_id></order_id>
        <amount>200</amount>
        <status>5</status>
        <pay_type>t</pay_type>
        <pay_gw_name>pt</pay_gw_name>
        <desc>Wpłatadlatest@test.pl</desc>
        <desc2></desc2>
        <create>2004-08-2310:39:52</create>
        <init>2004-08-3113:42:43</init>
        <sent>2004-08-3113:48:13</sent>
        <recv></recv>
        <cancel></cancel>
        <auth_fraud>0</auth_fraud>
        <ts>1094205828574</ts>
        <sig>a95dc2145079b16a3668175279c35736</sig>
        <add_client_name>JAN KOWALSKI</add_client_name>
        <add_client_street>UL.NOWOWIEJSKIEGO 8</add_client_street>
        <add_client_city>WARSZAWA</add_client_city>
        <add_client_post_code>02-638</add_client_post_code>
        <add_client_account>80607787095718703296721164</add_client_account>
        <add_client_address></add_client_address>
    </trans>
</response>
            

W danych odesłanych przez PayU wartość sig, obliczamy według następującego wzoru:

sig = md5( pos_id + session_id + order_id + status + amount + desc + ts + key2 )

Znaczenie poszczególnych pól komunikatu opisują poniższe tabelki.

Pola podstawowe:

Pole txt Pole xml Znaczenie
status response/status status przetworzenia komunikatu - dla prawidłowego „OK”
trans_id response/trans/id unikalny identyfikator transakcji nadawany przez PayU
trans_pos_id response/trans/pos_id identyfikator POS’a dla jakiego utworzono transakcję
trans_session_id response/trans/session_id wartość nadana przez aplikację Sklepu podczas tworzenia transakcji
trans_order_id response/trans/order_id wartość nadana przez aplikację Sklepu podczas tworzenia transakcji
trans_amount response/trans/amount aktualna wartość transakcji w groszach
trans_status response/trans/status aktualny status transakcji zgodny ze statusami dostępnymi na podstronie "statusy transkacji"
trans_pay_type response/trans/pay_type typ płatności zgodny z typami dostępnymi na podstronie: "typy płatności"
trans_pay_gw_name response/trans/pay_gw_name nazwa bramki realizującej transakcję - informacja wewnętrzna aplikacji PayU
trans_desc response/trans/desc wartość nadana przez aplikację Sklepu podczas tworzenia transakcji
trans_desc2 response/trans/desc2 wartość nadana przez aplikację Sklepu podczas tworzenia transakcji
trans_create response/trans/create data utworzenia transakcji
trans_init response/trans/init data rozpoczęcia transakcji
trans_sent response/trans/sent data przekazania transakcji do odbioru
trans_recv response/trans/recv data odbioru transakcji
trans_cancel response/trans/cance data anulowania transakcji
trans_auth_fraud response/trans/auth_fraud informacja wewnętrzna aplikacji PayU
trans_ts response/trans/ts wartość potrzebna do obliczenia podpisu
trans_sig response/trans/sig podpis komunikatu - wynik funkcji md5
trans_add_client_name response/trans/add_client_name nazwa klienta
trans_add_client_street response/trans/add_client_street ulica klienta
trans_add_client_city response/trans/add_client_city miejscowosc klienta
trans_add_client_post_code response/trans/add_client_post_code kod pocztowy klienta
trans_add_client_account response/trans/add_client_account numer rachunku bankowego klienta
trans_add_client_address response/trans/add_client_address pelny adres klienta

Pola dodatkowe dla wybranych typów płatności:

- mBank, BZWBK

Pole txt Pole xml Znaczenie
add_cc_number_hash response/trans/add_cc_number_hash hash numeru konta bankowego nadawcy płatności (pole uzupełniane po pewnym czasie)

- karta płatnicza (w tym Masterpass)

Pole txt Pole xml Znaczenie
add_cc_classification response/trans/add_cc_classification klasyfikacja karty (CREDIT, DEBIT)
add_cc_mask_pan response/trans/add_cc_mask_pan maskowany numer karty (np. 543402******4014)
add_cc_number_hash response/trans/add_cc_number_hash hash numeru karty płatniczej nadawcy płatności
add_cc_bin response/trans/add_cc_bin BIN - numer identyfikacyjny banku - wystawcy karty
add_cc_profile response/trans/add_cc_profile profil karty (np. CONSUMER, BUSINESS)
add_cc_payment_flow_type response/trans/add_cc_payment_flow_type typ płatności (np. CARD /standardowa płatność kartą/, MASTERPASS, ONE_CLICK_CARD, ONE_CLICK_CARD_RECURRING
add_cc_scheme response/trans/add_cc_scheme Rodzaj karty, np. VS (Visa), MC (MasterCard and Maestro)
add_cc_response_code response/trans/add_cc_response_code kod odpowiedzi, np. 000
add_cc_response_code_desc response/trans/add_cc_response_code_desc opis kodu, np. 000 - OK
add_cc_3ds_status response/trans/add_cc_3ds_status wynik obsługi 3-D Secure, np. AY – OK
add_cc_eci_code response/trans/add_cc_eci_code Electronic Commerce Indicator, np. 2 - pełna autentykacja (dla MasterCard), 5 - pełna autentykacja (dla Visa)
add_cc_bin_country response/trans/add_cc_bin_country kraj wydawcy karty, np. PL

- ING

Pole txt Pole xml Znaczenie
add_cc_number_hash response/trans/add_cc_number_hash hash numeru konta bankowego nadawcy płatności (pole uzupełniane po pewnym czasie)
add_cc_number response/trans/add_cc_number numer rachunku bankowego odbiorcy płatności
add_owner_name response/trans/add_owner_name nazwa odbiorcy płatności
add_owner_address response/trans/add_owner_address adres odbiorcy płatności
add_trans_title response/trans/add_trans_title tytuł płatności

- przelew bankowy

Pole txt Pole xml Znaczenie
add_cc_number response/trans/add_cc_number numer rachunku bankowego odbiorcy płatności
add_bank_name response/trans/add_bank_name nazwa banku odbiorcy płatności
add_owner_name response/trans/add_owner_name nazwa odbiorcy płatności
add_owner_address response/trans/add_owner_address adres odbiorcy płatności
add_trans_title response/trans/add_trans_title tytuł płatności
add_trans_prev response/trans/add_trans_prev link do strony z podglądem druku przelewu bankowego
add_trans_add_desc response/trans/add_trans_add_desc dodatkowy opis transakcji umieszczany na druku przelewu bankowego

- płatność testowa

Pole txt Pole xml Znaczenie
add_test response/trans/add_test zawsze wartość "1"
add_testid response/trans/add_testid identyfikator transakcji

9.3 Odbieranie płatności

Odebranie płatności, czyli zatwierdzenie transakcji wykonujemy wywołując procedurę Payment/confirm metodą POST, podając takie same parametry jak w przypadku odczytu informacji o transakcji (patrz: "wymiana informacji").

Wywoływanie tej metody jest konieczne tylko w przypadku wyłączenia opcji „Autoodbiór” dla danego typu płatności.

9.4 Odrzucanie (anulowanie) płatności

W celu anulowania lub odrzucenia płatności wywołujemy procedurę Payment/cancel metodą POST, podając takie same parametry jak w przypadku odczytu informacji o transakcji (patrz: "wymiana informacji").

9.5 Status wykonania transakcji

Dla procedur Payment/confirm oraz Payment/cancel otrzymujemy w odpowiedzi następujące strony:

Poprawne wykonanie - format „txt”:

status:OK
trans_id:7
trans_pos_id:1
trans_session_id:417419
trans_ts:1094206530505
trans_sig:9da7c868407fedae6f1b6aca9054632b
                

Poprawne wykonanie - format „xml”:

<?xml version="1.0" encoding="UTF-8" ?>
<response>
    <status>OK</status>
    <trans>
        <id>7</id>
        <pos_id>1</pos_id>
        <session_id>417419</session_id>
        <ts>1094205828574</ts>
        <sig>a95dc2145079b16a3668175279c35736</sig>
    </trans>
</response>
                

W danych odesłanych przez PayU wartość sig, obliczamy według następującego wzoru:

sig = md5( pos_id + session_id + ts + key2 )

Błąd - format "txt":

status:ERROR
error_nr:503
error_message:
                

Błąd - format „xml”:

<?xml version="1.0" encoding="UTF-8" ?>
<response>
    <status>ERROR</status>
    <error>
        <nr>503</nr>
        <message></message>
    </error>
</response>
                

10 Wymiana informacji o transakcjach za pomocą WEBAPI/SOAP

Do opisywanych procedur istnieje również interfejs WEBAPI/SOAP znajdujący się pod adresem:

https://secure.payu.com/paygw/webapi/Payments

Odpowiedni plik WSDL można pobrać z adresu:

https://secure.payu.com/paygw/webapi/Payments?wsdl

11 Narzędzia WWW

PayU oferuje zbiór narzędzi, które można wykorzystać na stronie sprzedawcy aby zwiększyć doświadczenie użytkownika (UX) w trakcie procesu płatności. Narzędzia te można podzielić na dwie kategorie.

Pierwsza kategoria to zbiór narzędzi umożliwiających pobranie metod płatności w celu wyświetlenia ich na stronie systemu sprzedawcy. Dostępne jest narzędzie javascript "wstrzykujące" dostepne metody płatności. Druga opcja to możliwość pobrania tych samych danych w formacie xml, które można przetworzyć na serwerze systemu sprzedawcy.

Natomiast druga kategoria zawiera możliwość definiowania koszyka za pomocą linku. Jest to o tyle wygodne gdyż umożliwia ekstremalnie prostą integrację. Więcej informacji można znaleźć w poniższych sekcjach.

11.1 Dynamiczna lista typów płatności – JavaScript

Aktualną listę płatności dla danego POS’a możemy umieścić na swojej stronie poprzez odwołanie do kodu JavaScript, pobranego z PayU.

Kod znajduje siępod adresem:

URL = UrlPlatnosci.pl/Kodowanie/js/PosId/K/paytype.js

gdzie:

UrlPlatnosci.pl Adres bazowy aplikacji PayU (https://secure.payu.com/paygw)
Kodowanie Jedna z wartości: ISO, UTF, WIN
PosId Identyfikator POS'a
K Dwa pierwsze znaki z wartości Key1

W pliku paytype.js znajdują się następujące metody:

PlnDrawSelect() Wydrukowanie elementu <select> z dostępną listąpłatności
PlnDrawRadio() Wydrukowanie lista elementów radio z nazwami form płatności
PlnDrawRadioImg(cols) Wydrukowanie lista elementów radio z nazwami oraz logotypami form płatności, parametr cols - liczba kolumn jaka zostanie użyta do przedstawienia tabelki

Przykład zastosowania:

<script language='JavaScript' type='text/JavaScript'
src='https://secure.payu.com/paygw/ISO/js/1234/xx/paytype.js'>
</script>
<form action="https://secure.payu.com/paygw/ISO/NewPayment"
method="POST" name="payform">
    <input type="hidden" name="pos_id" value="12345">
    <input type="hidden" name="session_id" value="1234565">
    <input type="hidden" name="amount" value="1000">
    <input type="hidden" name="desc" value="Payment description">
    <script language='JavaScript'type='text/JavaScript'>
    PlnDrawSelect();
    </script>
    <input type="hidden" name="client_ip" value="123.123.123.123">
    <input type="hidden" name="js" value="0">
    <input type="submit" value="Pay via PayU">
</form>
<script language="JavaScript" type="text/javascript">
<!--
document.forms['payform'].js.value=1;
-->
</script>
                

11.2 Dynamiczna lista typów płatności – xml

Listę aktualnych typów płatności dla danego POS’a można też pobrać w postaci pliku xml.

Odpowiedni plik xml znajduje się pod następującym adresem:

URL = UrlPlatnosci.pl/Kodowanie/xml/PosId/K/paytype.xml

gdzie:

UrlPlatnosci.pl Adres bazowy aplikacji PayU (https://secure.payu.com/paygw)
Kodowanie Jedna z wartości: ISO, UTF, WIN
PosId Identyfikator POS'a
K Dwa pierwsze znaki z wartości Key1

Przykładowa zawartość pobranego pliku:

<?xml version="1.0"encoding="UTF-8" ?>
<paytypes>
    <paytype>
        <type>c</type>
        <name>Payment card</name>
        <enable>true</enable>
        <img>https://secure.payu.com/paygw/images/paytype/on-c.gif</img>
        <min>1.01</min>
        <max>4000.0</max>
    </paytype>
    <paytype>
        <type>m</type>
        <name>mTransfer</name>
        <enable>true</enable>
        <img>https://secure.payu.com/paygw/images/paytype/on-m.gif</img>
        <min>0.5</min>
        <max>999999.99</max>
    </paytype>
...
</paytypes>
                

12 Autoodbiór

PayU umożliwia włączenie lub wyłączenie autoodbioru dla danego punktu płatności.

Autoodbiór włączony

Autoodbiór konfiguruje się tak, jak standardowe metody płatności.

Jeżeli status Autoodbioru został ustawiony na Włączony, transakcje przetwarzane są automatycznie bez konieczności ręcznego zatwierdzenia.

Autoodbiór wyłączony

Autoodbiór konfiguruje się tak, jak standardowe metody płatności.

Jeżeli status Autoodbioru został ustawiony na Wyłączony, transakcje przetwarzane są dopiero po ręcznym zatwierdzeniu.

Ręczne zatwierdzanie transakcji

Aby ręcznie zatwierdzić transakcję w Panelu Menadżerskim przy wyłączonymAutoodbiorze:

  1. Przejdź do Panelu Menadżerskiego.
  2. Przejdź do Transakcje > Lista transakcji.
  3. W polu Status wybierz Oczekuje na odbiór. Możliwe jest także ustawienie innych parametrów wyszukiwania.
  4. Kliknij Pokaż.
  5. Aby zatwierdzić transakcję, w kolumnie Akcja kliknij Odbierz.
  6. Sprawdź poprawność danych i kliknij OK.

Uwaga: Informacje o obsłudze transakcji za pomocą API znajdziesz w sekcji Wymiana informacji.

Konfigurowanie Autoodbioru

Autoodbiór konfiguruje się tak, jak standardowe metody płatności.

Informacje pokrewne

Przejścia pomiędzy stanami transakcji