Classic API (NewPayment)

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>

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

¹ 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")

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

Dodatkowe informacje o statusach transakcji

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

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

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ą:

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:

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:

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:

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. Uwaga: do kodowania należy używać dużych liter (np. "ł" powinno być zamienione na "%C5%82", a nie "%c5%82").
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

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

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

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:

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ą:

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:

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:

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

- mBank, BZWBK

- karta płatnicza (w tym Masterpass)

* - wykorzystywane w usłudze Płać w ratach z Mastercard

- ING

- przelew bankowy

- płatność testowa

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>
                

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:

https://secure.payu.com/api/classic/services/payments?wsdl

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:

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

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:

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>
                

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