Ważne zmiany w integracji protokołu Classic API opartym o interfejs WEBAPI/SOAP. Dowiedz się więcej!
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.
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>
Używanie znaków specjalnych w opisach transakcji nie jest zalecane przez PayU. Niektóre znaki nie są akceptowane przez banki.
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} | dwuliterowy kod kraju klienta zgodny z ISO-3166. |
Nie | STR {1,100} | adres email; Jeżeli wartość tego parametru nie zostanie podana użytkownik będzie proszony o uzupełnienie danych na stronie PayU, a płatności typu Raty lub Płacę później mogą być niedostępne. |
|
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 dla strony wyboru metody płatności: cs, en i pl , dla formatki dla kart płatniczych: 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"
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 |
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”. 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). Transakcje w tym statusie są obecnie automatycznie zwracane, tj. przechodzą w status 7. |
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. |
W przypadku wyłączonej opcji autoodbioru wpłat:
W przypadku włączonej opcji autoodbioru wpłat:
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 |
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ę |
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%
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 |
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).
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”.
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 |
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.&
. 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.
Uwaga: do kodowania należy używać dużych liter (np. "ł" powinno być
zamienione na "%C5%82", a nie "%c5%82").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.
generate_signature(form, secondKey, posId) { sortedValues = sortValuesByItsName(form) foreach value in sortedValues { content = content + parameterName + "=" + urlencode(value) + "&" } content = content + secondKey return sha256(content) }
<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>
&
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
2d373a18641fbd6bcea6c86ec2c0554fa28eed244a2649bb638ee600a66100d2
<input type="hidden" name="sig" value="2d373a18641fbd6bcea6c86ec2c0554fa28eed244a2649bb638ee600a66100d2">
W przypadku pytań prosimy o kontakt.
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)
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 powiadomienie 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 zgodnie z poniższą tabelką:
Próba | Czas od zmiany statusu płatności |
---|---|
1 | natychmiast |
2 | 1 minuta |
3 | 2 minuty |
4 | 5 minut |
5 | 10 minut |
6 | 30 minut |
7 | 1 godzina |
8 | 2 godziny |
9 | 3 godziny |
10 | 6 godzin |
11 | 9 godzin |
12 | 12 godzin |
13 | 15 godzin |
14 | 18 godzin |
15 | 21 godzin |
16 | 24 godziny |
17 | 36 godzin |
18 | 48 godzin |
19 | 60 godzin |
20 | 72 godziny |
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 |
---|---|---|
trans_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 |
---|---|---|
trans_add_cc_classification | response/trans/add_cc_classification | klasyfikacja karty (CREDIT, DEBIT) |
trans_add_cc_mask_pan | response/trans/add_cc_mask_pan | maskowany numer karty (np. 543402******4014) |
trans_add_cc_number_hash | response/trans/add_cc_number_hash | hash numeru karty płatniczej nadawcy płatności |
trans_add_cc_bin | response/trans/add_cc_bin | BIN - numer identyfikacyjny banku - wystawcy karty |
trans_add_cc_profile | response/trans/add_cc_profile | profil karty (np. CONSUMER, BUSINESS) |
trans_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 |
trans_add_cc_scheme | response/trans/add_cc_scheme | Rodzaj karty, np. VS (Visa), MC (MasterCard and Maestro) |
trans_add_cc_response_code | response/trans/add_cc_response_code | kod odpowiedzi, np. 000 |
trans_add_cc_response_code_desc | response/trans/add_cc_response_code_desc | opis kodu, np. 000 - OK |
trans_add_cc_3ds_status | response/trans/add_cc_3ds_status | wynik obsługi 3-D Secure, np. AY – OK |
trans_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) |
trans_add_cc_bin_country | response/trans/add_cc_bin_country | dwuliterowy kod kraju wydawcy karty zgodny z ISO-3166 |
trans_add_card_installment_proposal_id | response/trans/add_card_installment_proposal_id | unikalny identyfikator propozycji ratalnej * |
* - wykorzystywane w usłudze Płać w ratach z Mastercard
- ING
Pole txt | Pole xml | Znaczenie |
---|---|---|
trans_add_cc_number_hash | response/trans/add_cc_number_hash | hash numeru konta bankowego nadawcy płatności (pole uzupełniane po pewnym czasie) |
trans_add_cc_number | response/trans/add_cc_number | numer rachunku bankowego odbiorcy płatności |
trans_add_owner_name | response/trans/add_owner_name | nazwa odbiorcy płatności |
trans_add_owner_address | response/trans/add_owner_address | adres odbiorcy płatności |
trans_add_trans_title | response/trans/add_trans_title | tytuł płatności |
- przelew bankowy
Pole txt | Pole xml | Znaczenie |
---|---|---|
trans_add_cc_number | response/trans/add_cc_number | numer rachunku bankowego odbiorcy płatności |
trans_add_bank_name | response/trans/add_bank_name | nazwa banku odbiorcy płatności |
trans_add_owner_name | response/trans/add_owner_name | nazwa odbiorcy płatności |
trans_add_owner_address | response/trans/add_owner_address | adres odbiorcy płatności |
trans_add_trans_title | response/trans/add_trans_title | tytuł płatności |
trans_add_trans_prev | response/trans/add_trans_prev | link do strony z podglądem druku przelewu bankowego |
trans_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 |
---|---|---|
trans_add_test | response/trans/add_test | zawsze wartość "1" |
trans_add_testid | response/trans/add_testid | identyfikator transakcji |
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.
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").
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>
Ważne zmiany w integracji protokołu Classic API opartym o interfejs WEBAPI/SOAP. Dowiedz się więcej!
Do opisywanych procedur istnieje również interfejs WEBAPI/SOAP znajdujący się pod adresem:
https://secure.payu.com/api/classic/services/payments
Odpowiedni plik WSDL można pobrać z adresu:
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.
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>
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>
PayU umożliwia włączenie lub wyłączenie autoodbioru dla danego punktu płatności.
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 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.
Aby ręcznie zatwierdzić transakcję w Panelu Menadżerskim przy wyłączonymAutoodbiorze:
Uwaga: Informacje o obsłudze transakcji za pomocą API znajdziesz w sekcji Wymiana informacji.
Autoodbiór konfiguruje się tak, jak standardowe metody płatności.
Informacje pokrewne