Integrować system Paysera do strony internetowej można poprzez pobranie przez nas przygotowanej biblioteki o otwartym kodzie – libwebtopay. Z jej pomocą można sprawdzić wszystkie potrzebne parametry bezpieczeństwa podawanych i otrzymywanych danych.

  • WebToPay dla PHP (z BitBucket).
    $ hg clone https://bitbucket.org/paysera/libwebtopay
  • WebToPay dla .NET (z GitHub).
    $ git clone https://github.com/evp/webtopay-lib-dotnet.git

Z archiwum pobierz plik libwebtopay/WebToPay.php. Pozostałe pliki są przeznaczone do testowania, przykładów i pojaśnień. Najnowszą wersję tylko pliku libwebtopay/WebToPay.php można pobrać pod następującym adresem: WebToPay.php

Integrować system Paysera do strony internetowej można poprzez pobranie przygotowanej biblioteki o otwartym kodzie.

  • Omnipay 2.x - PHP biblioteka przetwarzania płatności. (iš GitHub).
    $ git clone https://github.com/povils/omnipay-paysera.git
  • Omnipay 3.x - PHP biblioteka przetwarzania płatności. (iš GitHub).
    $ git clone https://github.com/semyonchetvertnyh/omnipay-paysera.git
Uwaga Z libwebtopay można korzystać i dla mikro, i dla makro usług. wystarczy wezwać dwie metody, jedna z których przygotowuje dane do wysłania, a inna sprawdza otrzymaną odpowiedź o wykonanej płatności.

Poniżej jest podany w pełni roboczy przykład. Pola, w które należy wpisać dane dostępu do Paysera są oznaczone komentarzami.

1. Utwórz katalog.

UTWÓRZ katalog, i zmień NAZWĘ na libwebtopay. w katalogu będą przechowywane wszystkie pliki, powiązane z integracją płatności.

2. Pobierz bibliotekę libwebtopay.

W utworzony katalog libwebtopay POBIERZ plik WebToPay.php.

3. Utwórz plik, który będzie przekierowywał użytkownika na stronę Paysera.

W katalogu libwebtopay UTWÓRZ plik redirect.php. Treść danego pliku ma być następująca:

<?php

require_once('WebToPay.php');

function get_self_url() {
    $s = substr(strtolower($_SERVER['SERVER_PROTOCOL']), 0,
                strpos($_SERVER['SERVER_PROTOCOL'], '/'));

    if (!empty($_SERVER["HTTPS"])) {
        $s .= ($_SERVER["HTTPS"] == "on") ? "s" : "";
    }

    $s .= '://'.$_SERVER['HTTP_HOST'];

    if (!empty($_SERVER['SERVER_PORT']) && $_SERVER['SERVER_PORT'] != '80') {
        $s .= ':'.$_SERVER['SERVER_PORT'];
    }

    $s .= dirname($_SERVER['SCRIPT_NAME']);

    return $s;
}

try {
    $self_url = get_self_url();

    $request = WebToPay::redirectToPayment(array(
        'projectid'     => 0,
        'sign_password' => 'd41d8cd98f00b204e9800998ecf8427e',
        'orderid'       => 0,
        'amount'        => 1000,
        'currency'      => 'EUR',
        'country'       => 'LT',
        'accepturl'     => $self_url.'/accept.php',
        'cancelurl'     => $self_url.'/cancel.php',
        'callbackurl'   => $self_url.'/callback.php',
        'test'          => 0,
    ));
} catch (WebToPayException $e) {
    // handle exception
} 
    

Zamiast metody WebToPay::redirectToPayment można korzystać z WebToPay::buildRequest, która przyjmuje te same parametry i wraca macierz danych, potrzebnych do pobrania.

Pełny spis parametrów metody WebToPay::buildRequest() z opisami:

Parametr Długość Obowiązkowy Opis
projectid 11 Tak Unikalny numer projektu. Tylko potwierdzone projekty mogą przyjmować płatności.
orderid 40 Tak Numer zamówienia z Twojego systemu.
accepturl 255 Tak Pełny adres internetowy (URL), na który klient jest przekierowywany po pomyślnym dokonaniu płatności.
cancelurl 255 Tak Pełny adres internetowy (URL), na który klient jest przekierowywany po odwołaniu płatności lub w razie nieudanej płatności.
callbackurl 255 Tak Pełny adres (URL), na który sprzedawca otrzymuje informację o wykonanej płatności.

Skrypt powinien wrócić tekst "OK". Tylko wówczas nasz system zanotuje, że pomyślnie powiadomiliśmy Twój system o płatności.

Jeżeli nie otrzymujemy odpowiedzi "OK", wiadomość wysyłamy 4 razy (od razu, za godzinę, za trzy godziny i za dzień).
version 9 Tak Numer wersji specyfikacji (API) systemu płatniczego Paysera.
lang 3 Nie Można podać język użytkownika (ISO 639-2/B: LIT, RUS, ENG, itp.). Jeżeli system Paysera nie obsługuje wybranego języka, język będzie wybrany według adresu IP lub język angielski będzie używany domyślnie.
amount 11 Nie Kwota w centach, którą klient musi zapłacić.
currency 3 Nie Waluta płatności (np. USD, EUR, itp.), w której chcesz otrzymać płatność od klienta. Jeżeli podana waluta poprzez wybrany sposób płatności nie może być przyjęta, system automatycznie ją wymieni na obsługiwaną walutę według kursu dnia. W odpowiedzi na Twoją stronę będą przekazane payamount i paycurrency.
payment 20 Nie Sposób zapłaty. Jeżeli podany, płatność będzie wykonywana poprzez ten sposób zapłaty. Jeżeli niewskazany, użytkownikowi będzie podana tabela z listą sposobów zapłaty. Sposoby zapłaty można otrzymać i w czasie rzeczywistym, za pomocą biblioteki WebToPay
country 2 Nie Państwo płatnika (LT, EE, LV, GB, PL, DE). Jeżeli państwo jest wpisane, dla płatnika są podawane tylko te sposoby zapłaty, które są obsługiwane w danym państwie. Jeżeli państwo nie jest wpisane, system określa państwo według adresu IP użytkownika. Płatnikowi pozostawiana jest możliwość zmiany państwa.
paytext 255* Nie Tytuł płatności, który wyświetla się wykonując przelew. Jeżeli nie jest podany, wyświetla się domyślny tekst o treści:
Płatność za towary i usługi (Nr [order_nr]) ([site_name]).

Jeżeli podajesz tytuł płatności, obowiązkowo musisz włączyć następujące zmienne, które w ostatecznym tekście tytułu będą zamienione na odpowiednie wartości:

  • [order_nr] - numer zamówienia.
  • [site_name] lub [owner_name] - adres strony internetowej lub nazwa przedsiębiorstwa.

Jeżeli dane kryteria nie będą podane, będzie wyświetlać się domyślny tekst tytułu płatności.

Przykład tytułu płatności:

Płatność za towar według zamówienia [order_nr] na stronie internetowej [site_name].
p_firstname 255 Nie Imię kupującego. Preferowane w większości sposobów zapłaty. Obowiązkowe wykonując płatność niektórymi sposobami zapłaty.
p_lastname 255 Nie Nazwisko kupującego. Preferowane w większości sposobów zapłaty. Obowiązkowe wykonując płatność niektórymi sposobami zapłaty.
p_email 255 Nie E-mail kupującego jest obowiązkowy. Jeżeli adres nie będzie otrzymany, system poprosi klienta go wpisać. Na dany adres system Paysera powiadomi płatnika o statusie zapłaty.
p_street 255 Nie Adres kupującego, na który będzie wysyłany towar (np.: Ul. Mėnulio 7 - 7). Preferowany. Obowiązkowy wykonując płatność niektórymi sposobami zapłaty.
p_city 255 Nie Miasto kupującego, do którego jest wysyłany towar (np.: Wilno). Preferowane. Obowiązkowe wykonując płatność niektórymi sposobami zapłaty.
p_state 20 Nie Kod stanu kupującego (obowiązkowy tylko kupując w USA). Preferowany. Obowiązkowy wykonując płatność niektórymi sposobami zapłaty.
p_zip 20 Nie Kod pocztowy kupującego. Kody pocztowe Polski można znaleźć tutaj. Preferowany. Obowiązkowy wykonując płatność niektórymi sposobami zapłaty.
p_countrycode 2 Nie Kod państwa kupującego. Kody państw można znaleźć tutaj. Preferowany. Obowiązkowy wykonując płatność niektórymi sposobami zapłaty.
only_payments 0 Nie Wyświetlać tylko listę sposobów zapłaty, oddzielnych przecinkiem.
disalow_payments 0 Nie Nie wyświetlać listy sposobów zapłaty, oddzielonych przecinkiem.
test 1 Nie Parametr, który pozwala na testowanie połączenia. W taki sposób płatność nie jest wykonywana, a rezultat jest wracany od razu, jak gdyby płatność była wykonana. Aby można było testować, obowiązkowo należy aktywować tryb testowy przy wybranym projekcie, po zalogowaniu do systemu: "Zarządzanie projektami" -> "Usługa pobierania płatności" (przy wybranym projekcie) -> "Pozwól na płatności testowe" (zaznacz).
time_limit 19 Nie Parametr, który wskazuje do kiedy można zapłacić za zamówienie zapytania. Data jest podawana w formacie "yyyy-mm-dd HH:MM:SS". Minimalna wartość 15 minut od momentu zapytania, maksymalna - 3 dni. Uwaga: działa tylko z niektórymi sposobami zapłaty.
personcode 255 Nie Z danego parametru można korzystać do identyfikacji użytkownika. Jeżeli przekażesz PESEL użytkownika razem z callback, Paysera zwróci parametr personcodestatus, który wskaże czy PEEL użytkownika zgadza się z podanym.
developerid 11 Nie Jeżeli w naszym systemie jesteś oznaczony jako deweloper, w projekcie (projektach), które instalujesz, musisz przekazywać dany parametr. Znaczenie parametru – Twój numer użytkownika.

* Długość ostateczna może się różnić w zależności od specyfikacji typu płatności

4. Utwórz accept.php

W katalogu libwebtopay UTWÓRZ plik accept.php. Zawartość danego pliku ma być następująca:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
        <meta http-equiv="Content-Type" content="text/html;charset=UTF-8" />
        <title></title>
</head>
<body>
        Thank you for buying
</body>
</html> 
    

5. Utwórz cancel.php

W katalogu libwebtopay UTWÓRZ plik cancel.php. Zawartość danego pliku ma być następująca:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
        <meta http-equiv="Content-Type" content="text/html;charset=UTF-8" />
        <title></title>
</head>
<body>
        Payment canceled
</body>
</html>
    

6. Przetwarzanie wykonanych płatności.

W katalogu libwebtopay UTWÓRZ plik callback.php. Zawartość danego pliku ma być następująca:

<?php

require_once('WebToPay.php');

try {
        $response = WebToPay::checkResponse($_GET, array(
            'projectid'     => 0,
            'sign_password' => 'd41d8cd98f00b204e9800998ecf8427e',
        ));

        if ($response['test'] !== '0') {
            throw new Exception('Testing, real payment was not made');
        }
        if ($response['type'] !== 'macro') {
            throw new Exception('Only macro payment callbacks are accepted');
        }

        $orderId = $response['orderid'];
        $amount = $response['amount'];
        $currency = $response['currency'];
        //@todo: sprawdzić, czy zamówienie z $orderId jest potwierdzone (wywołanie zwrotne można powtórzyć kilka razy)
        //@todo: sprawdzić, czy kwota i waluta zamówienia są zgodne $kwotą i $walutą
        //@todo: potwierdzić zamówienie
        echo 'OK';
} catch (Exception $e) {
        echo get_class($e) . ': ' . $e->getMessage();
} 
    
Uwaga! Przekazane parametry są wracane przez WebToPay::checkResponse lub WebToPay::validateAndParseData. Dane są zakodowane, dlatego z parametrów GET ich otrzymać zwykle nie jest możliwe.
Uwaga! Jeżeli wszystko jest pomyślnie wykonane, skrypt Callback powinien wrócić odpowiedź, rozpoczynającą się od lub zawierającą tylko "OK". Parametry wracane przez Callback możesz znaleźć w szczegółowej specyfikacji.

Kodowane parametry

Parametr Opis
projectid Unikalny numer projektu. Tylko potwierdzone projekty mogą przyjmować płatności.
orderid Numer zamówienia z Twojego systemu.
lang Można podać język użytkownika (ISO 639-2/B: LIT, RUS, ENG, itp.). Jeżeli system Paysera nie obsługuje wybranego języka, język będzie wybrany według adresu IP lub język angielski będzie używany domyślnie.
amount Kwota w centach, którą klient musi zapłacić.
currency Waluta płatności (np. USD, EUR, itp.), w której chcesz otrzymać płatność od klienta. Jeżeli podana waluta poprzez wybrany sposób płatności nie może być przyjęta, system automatycznie ją wymieni na obsługiwaną walutę według kursu dnia. W odpowiedzi na Twoją stronę będą przekazane payamount i paycurrency.
payment Sposób zapłaty. Jeżeli podany, płatność będzie wykonywana poprzez ten sposób zapłaty. Jeżeli niewskazane, użytkownikowi będzie podana tabela z listą sposobów zapłaty. Sposoby zapłaty można otrzymać i w czasie rzeczywistym, za pomocą biblioteki WebToPay.
country Państwo płatnika (LT, EE, LV, GB, PL, DE). Jeżeli państwo jest wpisane, dla płatnika są podawane tylko te sposoby zapłaty, które są obsługiwane w danym państwie. Jeżeli państwo nie jest wpisane, system określa państwo według adresu IP użytkownika. Płatnikowi pozostawiana jest możliwość zmiany państwa.
paytext Tytuł płatności, który wyświetla się wykonując przelew.
name Imię płatnika, otrzymane od systemu płatniczego. Przekazywane tylko jeżeli system płatniczy je nadaje.
surename Nazwisko płatnika, otrzymane od systemu płatniczego. Przekazywane tylko jeżeli system płatniczy je nadaje.
status Status płatności:
  • 0 - płatność nie została wykonana
  • 1 - płatność pomyślna
  • 2 - zlecenie płatnicze przyjęte, ale jeszcze nie wykonane (dany status nie gwarantuje, że płatność zostanie wykonana)
  • 3 - dodatkowa informacja o płatności
test Parametr, który pozwala na testowanie połączenia. W taki sposób płatność nie jest wykonywana, a rezultat jest wracany od razu, jak gdyby płatność była wykonana. Aby można było testować, obowiązkowo należy aktywować tryb testowy przy wybranym projekcie, po zalogowaniu do systemu: "Zarządzanie projektami" -> "Usługa pobierania płatności" (przy wybranym projekcie) -> "Pozwól na płatności testowe" (zaznacz).
payment_country Państwo sposobu zapłaty. Jeżeli sposób zapłaty jest dostępny w kilku państwach (międzynarodowy) - parametr nie jest podawany. Państwo jest podawane w formacie dwucyfrowym (ISO 3166-1 alpha-2). Np.: LT, PL, RU, EE
payer_ip_country Państwo płatnika, które jest określane według adresu IP płatnika. Państwo jest podawane w formacie dwucyfrowym (ISO 3166-1 alpha-2). Np.: LT, PL, RU, EE.
payer_country Państwo płatnika, które jest określane według państwa sposobu zapłaty, a jeżeli sposób zapłaty jest międzynarodowy – według adresu IP płatnika. Państwo jest podawane w formacie dwucyfrowym (ISO 3166-1 alpha-2). Np.: LT, PL, RU, EE.
p_email E-mail kupującego jest obowiązkowy. Jeżeli adres nie będzie otrzymany, system poprosi klienta go wpisać. Na dany adres system Paysera powiadomi płatnika o statusie zapłaty.
requestid Numer zapytania, który otrzymujemy gdy kupujący klika na bank i który podajemy w link, znajdujący się w polu "callbackurl".
payamount Kwota w centach, która została przelana. Może różnić się, jeżeli była wymieniana na inną walutę.
paycurrency Waluta płatności (np. USD, EUR, itp.), którą przelałeś. Może różnić się od tej, o którą prosiłeś, jeżeli wybrany sposób płatności nie obsługuje danej waluty.
version Numer wersji specyfikacji (API) systemu płatniczego Paysera.
account Numer konta, z którego była wykonana płatność.
personcodestatus Jeżeli w czasie zaptania był przekazany personcode, dany parametr wskazuje, czy zgadza się podany PESEL z prawdziwym numerem PESEL użytkownika. Możliwe znaczenia:
  • 0 - PESEL jeszcze nie jest znany
  • 1 - PESEL zgadza się
  • 2 - PESEL nie zgadza się
  • 3 - PESEL nie jest znany
Jeżeli podzas callback PESEL jeszcze nie jest znany, będzie wykonany jeszcze jeden callback z parametrem status 3, gdy będzie wiadomo czy numery zgadzają się.

Zawsze sprawdzaj przekazywany status płatności - tylko wartość status 1 znaczy, że płatność została wykonana pomyślnie.
Sprawdzaj także czy usługa według danego zamówienia jeszcze nie była świadczona (według parametru orderid),czy płatność nie jest testowa (według parametru test), a także czy zgadza się kwota i waluta z kwotą i walutą projektu.

Przekazywanie parametrów w accepturl

Takie same parametry, jak i w wypadku callback, są przekazywane na wskazany przez Ciebie accepturl, na który przekierowywany jest płatnik. Prawie zawsze w tym czasie płatność jeszcze nie jest pomyślnie wykonana, i parametr status wynosi 2. Zawsze sprawdzaj, aby za jedną płatność usługa była świadczona tylko jeden raz - jeżeli użytkownik odświeży stronę accepturl, Twój system otrzyma informację o płatności powtórnie.