Skocz do: nawigacja, szukaj

Płatności internetowe


Spis treści

1. Przebieg Transakcji

Klient po skompletowaniu zamówienia klika na przycisk "zapłać". System Sprzedawcy przesyła żądanie transakcji (rejestrację) do systemu Przelewy24 i otrzymuje zwrotnie unikalny TOKEN. Następnie Klient jest przekierowany na panel transakcyjny Przelewy24.

W przypadku anulowania płatności Klient jest przekierowany na adres p24_url_return.

Po poprawnej transakcji Klient jest kierowany na adres podany w parametrze p24_url_return, jednocześnie system Przelewy24 wysyła potwierdzenie transakcji na adres podany w parametrze p24_url_status.

Dla potwierdzenia wiarygodności otrzymanego potwierdzenia w odpowiedzi na potwierdzenie wpłaty system Sprzedawcy weryfikuje wynik żądaniem zwrotnym.

Schemat przebiegu transakcji

2. Obsługa transakcji

2.1 Testowanie Połączenia

Aby przetestować połączenie z systemem Przelewy24 można wykorzystać operację:

Metoda testConnection

post https://secure.przelewy24.pl/testConnection
Parametry Wejścia
Nazwa_pola Typ Opis
p24_merchant_id T ID sprzedawcy
p24_pos_id INT ID sprzedawcy
p24_sign STRING(100) to wartość funkcji MD5 z połączonych ze sobą pól: p24_pos_id oraz klucza CRC. Łącznikiem pól jest znak
Parametry Wyjścia
Nazwa_pola Typ Opis
error INT Rezultat żądania
ErrorMessage String Informacja o zaistniałym błędzie w wywołaniu. Występuje tylko gdy error!=0

Metoda TestAccess

<?php
$soap = new SoapClient("https://secure.przelewy24.pl/external/9999.wsdl");
$test = $soap->TestAccess("9999", "anuniquekeyretrievedfromprzelewy24");
if ($test)
 echo 'Access granted';
else
 echo 'Access denied';
?>

Encoding: https://sandbox.przelewy24.pl/external/{SHOPID}.wsdl

Literal: https://sandbox.przelewy24.pl/external/{SHOPID}s.wsdl

Parametry wejściowe
nazwa typ opis
login string ID Sprzedawcy
pass string Klucz do WS uzyskany z Przelewy24
Parametry wyjściowe
typ opis
bool true – w przypadku poprawnych danych, false – w przeciwnym przypadku

2.2 Rejestracja Transakcji

Przed wysłaniem żądania transakcji należy zapisać jej dane do lokalnej bazy danych sprzedawcy. W szczególności należy zachować informacje o identyfikatorze sesji i kwocie transakcji.

Żądanie powinno zostać wykonane poprzez sprzedawcę na jeden ze sposobów:

<form action="https://secure.przelewy24.pl/trnRegister" method="POST" class="form">
    <input type="text" name="p24_session_id" value="SESSION_ID"/> 
    <input type="text" name="p24_merchant_id" value="TWÓJID_SPRZEDAWCY"/> 
    <input type="text" name="p24_pos_id" value="TWÓJID_SPRZEDAWCY"/> 
    <input type="text" name="p24_amount" value="KWOTA W WALUTA/100"/> 
    <input type="text" name="p24_currency" value="PLN"/> 
    <input type="text" name="p24_description" value="TYTUŁ"/> 
    <input type="text" name="p24_client" value="Jan Kowalski"/> 
    <input type="text" name="p24_address" value="ul. Polska 33/33"/> 
    <input type="text" name="p24_zip" value="66-777"/> 
    <input type="text" name="p24_city" value="Poznań"/> 
    <input type="text" name="p24_country" value="PL"/> 
    <input type="text" name="p24_email" value="email@host.pl"/> 
    <input type="text" name="p24_language" value="pl"/> 
    <input type="text" name="p24_url_status" value="http://myhost.pl/skrypt_st.php"/>
    <input type="text" name="p24_url_return" value="http://myhost.pl/skrypt_ok.php"/>
    <input type="text" name="p24_api_version" value="3.2"/> 
    <input type="hidden" name="p24_sign" value="e2c43dec9578633c518e1f514d3b434b"/> 
    <input name="submit_send" value="wyślij" type="submit"/> 
</form>
error=0&token={TOKEN}
error={KOD_BŁĘDU}&errorMessage=field1:desc1&field2:desc2...

errorMessage może zawierać informacje dotyczące wielu błędów.

post https://secure.przelewy24.pl/trnRegister

Parametry POST wywołania

Nazwa pola Typ Wymagane Opis
p24_merchant_id INT T ID sprzedawcy
p24_pos_id INT T ID Sklepu (domyślnie ID sprzedawcy)
p24_session_id STRING(100) T Unikalny identyfikator z systemu sprzedawcy.
p24_amount INT T Kwota transakcji wyrażona w WALUTA/100 (1.23 PLN = 123)
p24_currency STRING(3) T Waluta w jakiej ma być przyjęta płatność. (PLN,EUR,GBP,CZK...)
p24_description STRING(1024) T Opis transakcji
p24_email STRING(50) T Adres email klienta
p24_client STRING(100) N** Imię i nazwisko Klienta
p24_adress STRING(80) N** Adres Klienta
p24_zip STRING(10) N** Kod pocztowy klienta
p24_city STRING(50) N** Miasto Klienta
p24_country STRING(2) T Kody krajów zgodne z ISO 3166
p24_phone STRING(12) N Telefon klienta w formacie: 48111222333
p24_language STRING(2) N pl/ en / de / es / it
p24_method INT N Identyfikator metody płatności. Lista metod płatności widoczna w panelu lub dostępna przez API.
p24_url_return STRING(250) T Adres powrotny, na który zostanie przekierowany Klient, bez względu na wynik płatności.
p24_url_status STRING(250) N Adres URL na który zostaną przekazane informacje o wpłacie w przypadku poprawnej płatności.
p24_time_limit INT N Limit czasu na wykonanie transakcji przez Klienta.

0 - brak limitu, maks. 99(czas w minutach)

p24_wait_for_result INT N Oczekiwanie na przekazanie notyfikacji o płatności transakcji

0 - nie, 1 - tak

p24_channel INT N
p24_shipping INT N Koszt dostawy / wysyłki / etc.
p24_transfer_label STRING(20) N Opis pojawiający się w tytule przelewy 1
p24_api_version STRING(5) T Wersja API wg której realizowane jest wdrożenie. Zalecane: 3.2
p24_sign STRING(100) T Suma kontrolna wyliczana według wzoru opisanego w Obliczanie p24_sign
p24_encoding STRING(15) N System kodowania przesyłanych znaków:

ISO-8859-2, UTF-8, Windows-1250

Lista zakupów, gdzie X jest liczbą od 1 do 100 (opcjonalne 2)
p24_name_X STRING(127) T Nazwa towaru
p24_description_X STRING(127) N Dodatkowy opis towaru
p24_quantity_X INT T Ilość sztuk towaru
p24_price_X INT T Cena jednostkowa towaru
p24_number_X INT N ID towaru w systemie sprzedawcy
Parametry Wyjścia
Nazwa_pola Typ Opis
error INT Rezultat żądania
token String Identyfikator wywołania, stosowany m.in. w TrnRequest, Występuje tylko gdy error=0
ErrorMessage String Informacja o zaistniałym błędzie w wywołaniu. Występuje tylko gdy error!=0

Encoding: https://secure.przelewy24.pl/external/{SHOPID}.wsdl

Literal: https://secure.przelewy24.pl/external/{SHOPID}s.wsdl

Metoda RegisterTransaction

$details = array(
     array('name'=>'p24_session_id','value'=>'SESSION_ID'), 
     array('name'=>'p24_merchant_id','value'=>'9999'), 
     array('name'=>'p24_pos_id','value'=>'9999'), 
     array('name'=>'p24_amount','value'=>'KWOTA W WALUTA/100'), 
     array('name'=>'p24_currency','value'=>'PLN'), 
     array('name'=>'p24_description','value'=>'TYTUŁ'), 
     array('name'=>'p24_client','value'=>'Jan Kowalski'), 
     array('name'=>'p24_address','value'=>'ul. Polska 33/33'), 
     array('name'=>'p24_zip','value'=>'66-777'), 
     array('name'=>'p24_city','value'=>'Poznań'), 
     array('name'=>'p24_country','value'=>'PL'), 
     array('name'=>'p24_email','value'=>'email@host.pl'), 
     array('name'=>'p24_language','value'=>'pl'), 
     array('name'=>'p24_url_status','value'=>'http://myhost.pl/skrypt_st.php'),
     array('name'=>'p24_url_return','value'=>'http://myhost.pl/skrypt_ok.php'),
     array('name'=>'p24_api_version','value'=>'3.2'), 
     array('name'=>'p24_sign','value'=>md5('SESSION_ID|9999|KWOTA W WALUTA/100|PLN|KLUCZ_CRC'))
    );
$soap = new SoapClient("https://secure.przelewy24.pl/external/wsdl/9999.wsdl");
$res = $soap->RegisterTransaction("9999", "anuniquekeyretrievedfromprzelewy24", $details);
Parametry wejściowe
nazwa typ opis
login string ID Sprzedawcy
pass string Klucz do WS uzyskany z Przelewy24
details array Tablica parametrów w formacie:

"<item><name>[Nazwa parametru]</name><value>[wartość]</value></item>"

(patrz tabela poniżej)

Parametry wyjściowe
nazwa typ
result Token transakcji
error GeneralError
GeneralError
Obiekt z informacją o błędach.
dostępne pola typ opis
errorCode int unikalny kod błędu
errorMessage string

Parametry tablicy details mogą przyjąć następujące wartości:

Nazwa pola Typ Wymagane Opis
p24_merchant_id INT T ID sprzedawcy
p24_pos_id INT T ID Sklepu (domyślnie ID sprzedawcy)
p24_session_id STRING(100) T Unikalny identyfikator z systemu sprzedawcy.
p24_amount INT T Kwota transakcji wyrażona w WALUTA/100 (1.23 PLN = 123)
p24_currency STRING(3) T Waluta w jakiej ma być przyjęta płatność. (PLN,EUR,GBP,CZK...)
p24_description STRING(1024) T Opis transakcji
p24_email STRING(50) T Adres email klienta
p24_client STRING(100) N** Imię i nazwisko Klienta
p24_adress STRING(80) N** Adres Klienta
p24_zip STRING(10) N** Kod pocztowy klienta
p24_city STRING(50) N** Miasto Klienta
p24_country STRING(2) T Kody krajów zgodne z ISO 3166
p24_phone STRING(12) N Telefon klienta w formacie: 48111222333
p24_language STRING(2) N pl/ en / de / es / it
p24_method INT N Identyfikator metody płatności. Lista metod płatności widoczna w panelu lub dostępna przez API.
p24_url_return STRING(250) T Adres powrotny, na który zostanie przekierowany Klient, bez względu na wynik płatności.
p24_url_status STRING(250) N Adres URL na który zostaną przekazane informacje o wpłacie w przypadku poprawnej płatności.
p24_time_limit INT N Limit czasu na wykonanie transakcji przez Klienta.

0 - brak limitu, maks. 99(czas w minutach)

p24_wait_for_result INT N Oczekiwanie na przekazanie notyfikacji o płatności transakcji

0 - nie, 1 - tak

p24_channel INT N
p24_shipping INT N Koszt dostawy / wysyłki / etc.
p24_transfer_label STRING(20) N Opis pojawiający się w tytule przelewy 1
p24_api_version STRING(5) T Wersja API wg której realizowane jest wdrożenie. Zalecane: 3.2
p24_sign STRING(100) T Suma kontrolna wyliczana według wzoru opisanego w Obliczanie p24_sign
p24_encoding STRING(15) N System kodowania przesyłanych znaków:

ISO-8859-2, UTF-8, Windows-1250

Lista zakupów, gdzie X jest liczbą od 1 do 100 (opcjonalne 2)
p24_name_X STRING(127) T Nazwa towaru
p24_description_X STRING(127) N Dodatkowy opis towaru
p24_quantity_X INT T Ilość sztuk towaru
p24_price_X INT T Cena jednostkowa towaru
p24_number_X INT N ID towaru w systemie sprzedawcy

2.3 Przejście do panelu transakcyjnego

get https://secure.przelewy24.pl/trnRequest/{TOKEN}

gdzie {TOKEN} został pobrany w wyniku zarejestrowania transakcji (patrz: Obsługa transakcji)


2.4 Odbiór wyniku transakcji

Po zakończeniu procesu płatności wywołany zostaje adres p24_url_return. W przekierowaniu nie są wysyłane żadne dodatkowe pola, adres jest dokładnie taki, jak w żądaniu transakcji. Jest to zwykłe przekierowanie metodą GET. Informacja o płatności jest wysyłana wyłącznie asynchronicznie na adres p24_url_status.

Powiadomienie o poprawnej transakcji

Po poprawnej transakcji zostaje wywoływany adres p24_url_status. Powiadomienie następuje niezależnie od tego, czy Klient został przekierowany na p24_url_return, czy też nie. Powiadomienie zostaje wysłane tylko i wyłącznie dla poprawnej wpłaty. System nie wysyła informacji o wpłatach, które nie zostały wykonane, bądź zostały wykonane niepoprawnie.

post p24_url_status

Parametry wyjścia
Nazwa pola Typ Opis
p24_merchant_id INT ID Sprzedawcy
p24_pos_id INT ID Sklepu (domyślnie IDSprzedawcy)
p24_session_id STRING(100) Unikalny identyfikator z systemu sprzedawcy
p24_amount INT Kwota transakcji wyrażona w WALUTA/100 (1.23 PLN = 123)
p24_currency STRING(3) PLN, EUR, GBP, CZK
p24_order_id INT Numer transakcji nadany przez Przelewy24
p24_method INT Metoda płatności użyta przez klienta
p24_statement STRING Tytuł przelewu
p24_sign STRING Suma kontrolna wyliczana wg opisu poniżej (Dział Obliczanie p24_sign) z pól:p24_session_id, p24_order_id, p24_amount ,p24_currency i pola „Klucz CRC”
Exclam.svg Ważne Transakcja zostaje uznana za potwierdzoną po jej weryfikacji. Jeżeli klient dokona transakcji, wróci na stronę sprzedawcy, ale sprzedawca nie zweryfikuje transakcji, dana kwota nie zostanie przekazana sprzedawcy ani uwzględniona w rozliczeniach. Pozostanie ona do dyspozycji klienta w formie przedpłaty.

2.5 Weryfikacja Transakcji

Po odebraniu powiadomienia, system Sprzedawcy musi wykonać dodatkową operację mającą na celu potwierdzenie autentyczności powiadomienia. Operacja ta polega na wywołaniu odpowiedniego skryptu serwisu Przelewy24.pl.

post https://secure.przelewy24.pl/trnVerify

Parametry Wejścia
Nazwa pola Typ Opis
p24_merchant_id INT ID sprzedawcy
p24_pos_id INT ID sklepu (domyślnie ID Sprzedawcy)
p24_session_id STRING(100) Unikalny identyfikator z systemu sprzedawcy
p24_amount INT Kwota transakcji wyrażona w WALUTA*100 (1.23 PLN = 123)
p24_currency STRING(3) PLN, EUR, GBP, CZK
p24_order_id INT Numer transakcji nadany przez Przelewy24
p24_sign STRING Suma kontrolna wyliczana według wzoru opisanego w Obliczanie p24_sign z pól: p24_session_id, p24_order_id, p24_amount, p24_currency i pola Klucz CRC.

Metoda VerifyTransaction

<?php
$soap = new SoapClient("https://secure.przelewy24.pl/external/9999.wsdl");
$res = $soap-> VerifyTransaction('9999', 'keyfromprzelewy24', 123456, 'abcdef', 1000);
if ($res->error->errorCode) {
 echo 'Something went wrong: ' . $res->error->errorMessage;
} else {
 echo 'Transaction OK';
}
?>

Encoding: https://secure.przelewy24.pl/external/{SHOPID}.wsdl

Literal: https://secure.przelewy24.pl/external/{SHOPID}s.wsdl

Parametry wejściowe
nazwa typ opis
login string ID Sprzedawcy
pass string Klucz do WS uzyskany z Przelewy24
orderId int Numer transakcji nadany przez Przelewy24
sessionId string Session ID
amount int Kwota wyrażona w danej walucie, w setnej części (1/100 waluty podstawowej)
currency string Waluta: PLN / EUR / CHF / USD / GBP (default: PLN)
Parametry wyjściowe
nazwa typ opis
result bool true jeżeli transakcja jest poprawna, w przeciwnym wypadku false
error GeneralError


Powiązane typy danych
GeneralError
Obiekt z informacją o błędach.
dostępne pola typ opis
errorCode int unikalny kod błędu
errorMessage string

2.6 Automatyczne przekazywanie wyniku transakcji

W sytuacji, gdy pierwsze powiadomienie o wyniku transakcji nie zostanie poprawnie odebrane przez system Partnera, system Przelewy24 wyśle kolejne powiadomienia.

Powiadomienia zostaną wysłane po: 3, 5, 15, 30, 60, 150 i 450 minutach(+/- 5 min.).

Parametry POST są takie same, jak w przypadku pierwszego powiadomienia.

2.7 Obliczanie p24_sign

Celem dodatkowej weryfikacji danych formularza przesyłanego do serwisu Przelewy24 udostępnione jest pole p24_sign. Pole to ma na celu weryfikację, czy parametry wejściowe są prawidłowe i nie zostały zmodyfikowane.

W panelu transakcyjnym, w zakładce Moje Dane jest ciąg o nazwie Klucz do CRC. Wartość z tego pola (16 znaków alfanumerycznych) jest potrzeba do obliczania sumy kontrolnej.

Sumę kontrolną p24_sign obliczamy za pomocą funkcji MD5 z połączonych ze sobą następujących pól, w zależności od wywołania.

Test Połączenia

  • p24_pos_id
  • klucz CRC

Rejestracja Transakcji

  • p24_session_id,
  • p24_merchant_id,
  • p24_amount,
  • p24_currency,
  • klucza CRC.

Verifikacja Transakcji

  • p24_session_id,
  • p24_order_id,
  • p24_amount,
  • p24_currency,
  • klucza CRC.


Łącznikiem pól jest znak | (pionowa kreska, pipe, ASCII 124)

Przykład: md5 dla p24_sign obliczanego przy rejestracji transakcji

 abcdefghijk|9999|2500|PLN|a123b456c789d012

wynosi:

 6c7f0bb62c046fbc89921dc3b2b23ede

2.8 Adresy IP serwerów

Zalecamy zabezpieczenie skryptów przed podejrzanymi wywołaniami, stosując filtrację adresów IP dla przychodzących połączeń.

Zakresy IP serwerów to:

91.216.191.181 - 91.216.191.185
92.43.119.144 - 92.43.119.159

3. Środowisko Testowe

Podczas implementowania mechanizmów w Twoim systemie możesz skorzystać ze środowiska testowego. Środowisko to umożliwia zweryfikowanie poprawności instalacji bez konieczności dokonywania przelewów.

Transakcje testowe będą widoczne w panelu testowym pod adresem: https://sandbox.przelewy24.pl/panel

Aby uzyskać dostęp do środowiska testowego należy po zalogowaniu do panelu produkcyjnego wybrać opcję: "Konto w SANDBOX".


Adres URL do połączeń do środowiska testowego:

Test połączenia:

post https://sandbox.przelewy24.pl/testConnection

Rejestracja:

post https://sandbox.przelewy24.pl/trnRegister

Wywołanie:

get https://sandbox.przelewy24.pl/TrnRequest/{TOKEN}

Weryfikacja:

post https://sandbox.przelewy24.pl/trnVerify

Warn.svg Uwaga! Środowisko testowe nie może być wykorzystywane do realizacji transakcji produkcyjnych!

4 Kody błędów

Kody błędów
Kod Opis błędu
err00 Nieprawidłowe wywołanie skryptu
err01 Nie uzyskano od sklepu potwierdzenia odebrania odpowiedzi autoryzacyjnej
err02 Nie uzyskano odpowiedzi autoryzacyjnej
err03 To zapytanie było już przetwarzane
err04 Zapytanie autoryzacyjne niekompletne lub niepoprawne
err05 Nie udało się odczytać konfiguracji sklepu internetowego
err06 Nieudany zapis zapytania autoryzacyjnego
err07 Inna osoba dokonuje płatności
err08 Nieustalony status połączenia ze sklepem
err09 Przekroczono dozwoloną liczbę poprawek danych
err10 Nieprawidłowa kwota transakcji!
err49 Zbyt wysoki wynik oceny ryzyka transakcji
err51 Nieprawidłowe wywołanie strony
err52 Błędna informacja zwrotna o sesji
err53 Błąd transakcji!
err54 Niezgodność kwoty transakcji
err55 Nieprawidłowy kod odpowiedzi!
err56 Nieprawidłowa karta
err57 Niezgodność flagi TEST!
err58 Nieprawidłowy numer sekwencji!
err59 Nieprawidłowa waluta transakcji!
err101 Błąd wywołania strony. W żądaniu transakcji brakuje któregoś z wymaganych parametrów lub pojawiła się niedopuszczalna wartość
err102 Minął czas na dokonanie transakcji
err103 Nieprawidłowa kwota przelewu
err104 Transakcja oczekuje na potwierdzenie
err105 Transakcja dokonana po dopuszczalnym czasie
err161 Żądanie transakcji przerwane przez użytkownika. Klient przerwał procedurę płatności wybierając przycisk "Powrót" na stronie wyboru formy płatności.
err162 Żądanie transakcji przerwane przez użytkownika. Klient przerwał procedurę płatności wybierając przycisk "Rezygnuj" na stronie z instrukcją płatności.

5. Dodatkowe funkcjonalności

5.1 Formy płatności w aplikacji Partnera

Aby uprościć proces płatności możliwe jest przeniesienie wyboru formy płatności przez klienta już na etapie składania zamówienia w sklepie. Jeżeli dodatkowo w sklepie klient zaakceptuje warunki regulaminu Przelewy24 (w żądaniu należy ustawić pole p24_regulation_accept = true) zostanie on po kliknięciu przycisku „zapłać” przeniesiony bezpośrednio ze strony sklepu do banku / formularza kart płatniczych.

Przygotowanie własnego szablonu form płatności

Prezentowanie metod wewnątrz własnej aplikacji pozwala na grupowanie, promowanie lub wyszczególnianie formy ostatnio użytej przez klienta Aby pobrać listę metod płatności należy skorzystać z metody webservice PaymentMethods

<?php
$soap = new SoapClient("https://secure.przelewy24.pl/external/9999.wsdl");
$res = $soap->PaymentMethods('9999', 'anuniquekeyretrievedfromprzelewy24', 'en');
// $res->result contains data about payment methods
if ($res->error->errorCode) {
 echo 'Something went wrong: ' . $res->error->errorMessage;
} else {
 echo 'Payment methods: ';
 $LIST = $res->result;
foreach ($LIST as $pm) {
 // data of payment method: $pm->name, $pm->id, $pm->status
 // ...
 }
}
?>

Encoding: https://secure.przelewy24.pl/external/{SHOPID}.wsdl

Literal: https://secure.przelewy24.pl/external/{SHOPID}s.wsdl

Parametry wejściowe
nazwa typ opis
login string ID Sprzedawcy
pass string Klucz do WS uzyskany z Przelewy24
lang string(2) Język, jedna z dwóch wartości: “pl” , “en”


Parametry wyjściowe
nazwa typ
result array of PaymentMethod
error GeneralError


Powiązane typy danych
PaymentMethod
Obiekt pojedynczej metody płatności
dostępne pola typ opis
name string
id int
status bool
avaibilityHours
GeneralError
Obiekt z informacją o błędach.
dostępne pola typ opis
errorCode int unikalny kod błędu
errorMessage string

Przekierowanie klienta do wybranej metody

Aby przekierować klienta bezpośrednio do wybranej przez niego metody płatności w żądaniu transakcji należy identyfikator danej metody przekazać w parametrze p24_method.

5.2 Formatka Kartowa - AJAX

Przebieg procesu

  • Rejestracja transakcji poprzez trnRegister i pobranie Tokenu transakcji
  • Przygotowanie elementu DIV w treści strony, gdzie ma zostać zamieszczony formularz płatności kartą.
  • Przygotowanie skryptu Javascript, który zostanie wywołany po zakończeniu transakcji

Przygotowanie pola do zamieszczenia formularza rejestracji karty

Do przygotowania miejsca na stronie, gdzie ma zostać wyświetlony formularz rejestracji karty można wykorzystać tag DIV. Atrybut ID tego elementu należy ustawić na wartość "P24FormContainer". Kod pola wygląda następująco:

Parametry wyjścia
{P24SIGN} suma kontrolna taka sama, jak użyta w żądaniu trnRegister
{FinishpaymentFunction} nazwa funkcji wywołanej w przypadku poprawnie zakończonej transakcji
{PaymentErrorFunction} nazwa funkcji wywołanej w przypadku transakcji zakończonej błędem.
{DICTIONARY JSON} słownik terminów użytych w formularzu rejestracji karty
DICTIONARY JSON
{ 
       "cardHolderLabel":"Cardholder name", 
       "cardNumberLabel":"Card number", 
       "cvvLabel":"cvv", 
       "expDateLabel":"Expiry date", 
       "payButtonCaption":"Pay", 
       "threeDSAuthMessage":"3DSAuthentication"
}

Do strony należy załączyć skrypt generujący formularz w wewnątrz DIV#P24FormContainer:

get http s ://secure.przelewy24.pl/inchtml/ajaxPayment/ajax.js?token ={TOKEN}

Gdzie, w miejsce {TOKEN} należy wstawić Token otrzymany w wyniku działania funkcji trnRegister. Opcjonalnie można wykorzystać style CSS dla formularza rejestracji karty, lub alternatywnie zastosować własne. Adres URL domyślnych styli: https://secure.przelewy24.pl/inchtml/card/register_card/ajax.css

W przypadku transakcji wymagającej dodatkowej autoryzacji (3DSecure) po wypełnieniu formularza na stronie pojawi się link prowadzący do nowego okna z formularzem autoryzacji (np. wpisanie SMSa wysłanego z banku). Po poprawnej autoryzacji okno zostanie zamknięte i nastąpi wywołanie funkcji Javascript dla poprawnej transakcji.

Adres powrotny powinien prowadzić do skryptu zamieszczonego na tej samej domenie co skrypt żądania. Powinien on uruchamiać następującą funkcję:

window.setTimeout(function(){
opener.P24_Transaction.threeDSReturn(window);
window.close();
},1000);

5.3 Blik Level 0

Wstęp

Funkcjonalność pozwalająca przenieść formularz BLIK bezpośrednio do aplikacji klienta.

Przebieg Procesu

<form action="https://secure.przelewy24.pl/trnRegister" method="POST" class="form">
    <input type="text" name="p24_session_id" value="SESSION_ID"/> 
    <input type="text" name="p24_merchant_id" value="TWÓJID_SPRZEDAWCY"/> 
    <input type="text" name="p24_pos_id" value="TWÓJID_SPRZEDAWCY"/> 
    <input type="text" name="p24_amount" value="KWOTA W WALUTA/100"/> 
    <input type="text" name="p24_currency" value="PLN"/> 
    <input type="text" name="p24_description" value="TYTUŁ"/> 
    <input type="text" name="p24_client" value="Jan Kowalski"/> 
    <input type="text" name="p24_address" value="ul. Polska 33/33"/> 
    <input type="text" name="p24_zip" value="66-777"/> 
    <input type="text" name="p24_city" value="Poznań"/> 
    <input type="text" name="p24_country" value="PL"/> 
    <input type="text" name="p24_email" value="email@host.pl"/> 
    <input type="text" name="p24_language" value="pl"/> 
    <input type="text" name="p24_url_status" value="http://myhost.pl/skrypt_st.php"/>
    <input type="text" name="p24_url_return" value="http://myhost.pl/skrypt_ok.php"/>
    <input type="text" name="p24_api_version" value="3.2"/> 
    <input type="hidden" name="p24_sign" value="e2c43dec9578633c518e1f514d3b434b"/> 
    <input name="submit_send" value="wyślij" type="submit"/> 
</form>
error=0&token={TOKEN}
error={KOD_BŁĘDU}&errorMessage=field1:desc1&field2:desc2...

errorMessage może zawierać informacje dotyczące wielu błędów.

post https://secure.przelewy24.pl/trnRegister

Parametry POST wywołania

Nazwa pola Typ Wymagane Opis
p24_merchant_id INT T ID sprzedawcy
p24_pos_id INT T ID Sklepu (domyślnie ID sprzedawcy)
p24_session_id STRING(100) T Unikalny identyfikator z systemu sprzedawcy.
p24_amount INT T Kwota transakcji wyrażona w WALUTA/100 (1.23 PLN = 123)
p24_currency STRING(3) T Waluta w jakiej ma być przyjęta płatność. (PLN,EUR,GBP,CZK...)
p24_description STRING(1024) T Opis transakcji
p24_email STRING(50) T Adres email klienta
p24_client STRING(100) N** Imię i nazwisko Klienta
p24_adress STRING(80) N** Adres Klienta
p24_zip STRING(10) N** Kod pocztowy klienta
p24_city STRING(50) N** Miasto Klienta
p24_country STRING(2) T Kody krajów zgodne z ISO 3166
p24_phone STRING(12) N Telefon klienta w formacie: 48111222333
p24_language STRING(2) N pl/ en / de / es / it
p24_method INT N Identyfikator metody płatności. Lista metod płatności widoczna w panelu lub dostępna przez API.
p24_url_return STRING(250) T Adres powrotny, na który zostanie przekierowany Klient, bez względu na wynik płatności.
p24_url_status STRING(250) N Adres URL na który zostaną przekazane informacje o wpłacie w przypadku poprawnej płatności.
p24_time_limit INT N Limit czasu na wykonanie transakcji przez Klienta.

0 - brak limitu, maks. 99(czas w minutach)

p24_wait_for_result INT N Oczekiwanie na przekazanie notyfikacji o płatności transakcji

0 - nie, 1 - tak

p24_channel INT N
p24_shipping INT N Koszt dostawy / wysyłki / etc.
p24_transfer_label STRING(20) N Opis pojawiający się w tytule przelewy 1
p24_api_version STRING(5) T Wersja API wg której realizowane jest wdrożenie. Zalecane: 3.2
p24_sign STRING(100) T Suma kontrolna wyliczana według wzoru opisanego w Obliczanie p24_sign
p24_encoding STRING(15) N System kodowania przesyłanych znaków:

ISO-8859-2, UTF-8, Windows-1250

Lista zakupów, gdzie X jest liczbą od 1 do 100 (opcjonalne 2)
p24_name_X STRING(127) T Nazwa towaru
p24_description_X STRING(127) N Dodatkowy opis towaru
p24_quantity_X INT T Ilość sztuk towaru
p24_price_X INT T Cena jednostkowa towaru
p24_number_X INT N ID towaru w systemie sprzedawcy
Parametry Wyjścia
Nazwa_pola Typ Opis
error INT Rezultat żądania
token String Identyfikator wywołania, stosowany m.in. w TrnRequest, Występuje tylko gdy error=0
ErrorMessage String Informacja o zaistniałym błędzie w wywołaniu. Występuje tylko gdy error!=0

Encoding: https://secure.przelewy24.pl/external/{SHOPID}.wsdl

Literal: https://secure.przelewy24.pl/external/{SHOPID}s.wsdl

Metoda RegisterTransaction

$details = array(
     array('name'=>'p24_session_id','value'=>'SESSION_ID'), 
     array('name'=>'p24_merchant_id','value'=>'9999'), 
     array('name'=>'p24_pos_id','value'=>'9999'), 
     array('name'=>'p24_amount','value'=>'KWOTA W WALUTA/100'), 
     array('name'=>'p24_currency','value'=>'PLN'), 
     array('name'=>'p24_description','value'=>'TYTUŁ'), 
     array('name'=>'p24_client','value'=>'Jan Kowalski'), 
     array('name'=>'p24_address','value'=>'ul. Polska 33/33'), 
     array('name'=>'p24_zip','value'=>'66-777'), 
     array('name'=>'p24_city','value'=>'Poznań'), 
     array('name'=>'p24_country','value'=>'PL'), 
     array('name'=>'p24_email','value'=>'email@host.pl'), 
     array('name'=>'p24_language','value'=>'pl'), 
     array('name'=>'p24_url_status','value'=>'http://myhost.pl/skrypt_st.php'),
     array('name'=>'p24_url_return','value'=>'http://myhost.pl/skrypt_ok.php'),
     array('name'=>'p24_api_version','value'=>'3.2'), 
     array('name'=>'p24_sign','value'=>md5('SESSION_ID|9999|KWOTA W WALUTA/100|PLN|KLUCZ_CRC'))
    );
$soap = new SoapClient("https://secure.przelewy24.pl/external/wsdl/9999.wsdl");
$res = $soap->RegisterTransaction("9999", "anuniquekeyretrievedfromprzelewy24", $details);
Parametry wejściowe
nazwa typ opis
login string ID Sprzedawcy
pass string Klucz do WS uzyskany z Przelewy24
details array Tablica parametrów w formacie:

"<item><name>[Nazwa parametru]</name><value>[wartość]</value></item>"

(patrz tabela poniżej)

Parametry wyjściowe
nazwa typ
result Token transakcji
error GeneralError
GeneralError
Obiekt z informacją o błędach.
dostępne pola typ opis
errorCode int unikalny kod błędu
errorMessage string

Parametry tablicy details mogą przyjąć następujące wartości:

Nazwa pola Typ Wymagane Opis
p24_merchant_id INT T ID sprzedawcy
p24_pos_id INT T ID Sklepu (domyślnie ID sprzedawcy)
p24_session_id STRING(100) T Unikalny identyfikator z systemu sprzedawcy.
p24_amount INT T Kwota transakcji wyrażona w WALUTA/100 (1.23 PLN = 123)
p24_currency STRING(3) T Waluta w jakiej ma być przyjęta płatność. (PLN,EUR,GBP,CZK...)
p24_description STRING(1024) T Opis transakcji
p24_email STRING(50) T Adres email klienta
p24_client STRING(100) N** Imię i nazwisko Klienta
p24_adress STRING(80) N** Adres Klienta
p24_zip STRING(10) N** Kod pocztowy klienta
p24_city STRING(50) N** Miasto Klienta
p24_country STRING(2) T Kody krajów zgodne z ISO 3166
p24_phone STRING(12) N Telefon klienta w formacie: 48111222333
p24_language STRING(2) N pl/ en / de / es / it
p24_method INT N Identyfikator metody płatności. Lista metod płatności widoczna w panelu lub dostępna przez API.
p24_url_return STRING(250) T Adres powrotny, na który zostanie przekierowany Klient, bez względu na wynik płatności.
p24_url_status STRING(250) N Adres URL na który zostaną przekazane informacje o wpłacie w przypadku poprawnej płatności.
p24_time_limit INT N Limit czasu na wykonanie transakcji przez Klienta.

0 - brak limitu, maks. 99(czas w minutach)

p24_wait_for_result INT N Oczekiwanie na przekazanie notyfikacji o płatności transakcji

0 - nie, 1 - tak

p24_channel INT N
p24_shipping INT N Koszt dostawy / wysyłki / etc.
p24_transfer_label STRING(20) N Opis pojawiający się w tytule przelewy 1
p24_api_version STRING(5) T Wersja API wg której realizowane jest wdrożenie. Zalecane: 3.2
p24_sign STRING(100) T Suma kontrolna wyliczana według wzoru opisanego w Obliczanie p24_sign
p24_encoding STRING(15) N System kodowania przesyłanych znaków:

ISO-8859-2, UTF-8, Windows-1250

Lista zakupów, gdzie X jest liczbą od 1 do 100 (opcjonalne 2)
p24_name_X STRING(127) T Nazwa towaru
p24_description_X STRING(127) N Dodatkowy opis towaru
p24_quantity_X INT T Ilość sztuk towaru
p24_price_X INT T Cena jednostkowa towaru
p24_number_X INT N ID towaru w systemie sprzedawcy

  • Przekazanie kodu blik do systemu Przelewy24 Webserwisową metodą execBlik

Literal: wsdl: https://secure.przelewy24.pl/external/wsdl/services_blik.php?wsdl

Parametry wejścia
login string Id of seller account
pass string Webservices password
token string Transaction’s TOKEN
kod string BLIK code
Parametry wyjścia
execBlikResult boolean Notice:

true – code was correct and has been successfully processed by BLIK service. Payment status will be sent to the url-status given during the transaction registration process.

false – code was either wrong, or could not be processed. Status will not be sent.

1 Access denied Occurs if login and/or password are incorrect, or IP address hasn’t been set in Przelewy24 system
631 Internal system error
10000 Unknown error

Środowisko Testowe

W celu wykonania testów dla metody execBlik należy skorzystać z poniższego WSDL. Aby zasymulować prawidłową transakcję należy wprowadzić w elemencie "<kod>" 6 cyfrową liczbę nieparzystą.

Adres wsdl: https://sandbox.przelewy24.pl/external/wsdl/services_blik.php?wsdl (literal)

5.4 MasterPass v.6

Przebieg procesu

  • Rejestracja transakcji (backend sprzedawcy). Po rejestracji otrzymujemy TOKEN, który będzie nam potrzebny do wywołania skryptu.
  • Zgodnie z dokumentacją masterpass umieszczenie na stronie skryptów:
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
<script src="http://sandbox.masterpass.com/lightbox/Switch/integration/MasterPass.client.js" type="text/javascript"></script>
  • Umieszczenie na stronie skryptu przelewowego:
<script src=’https://secure.przelewy24.pl/masterpass/przelewy24Masterpass/TOKEN’> 


gdzie TOKEN to token z uprzednio zarejestrowanej transakcji (patrz wyżej). TOKEN za każdym odświeżeniem strony (wykonaniem request'u, mającego na celu otrzymanie danych do wyświetlenia lightbox'a) powinien być nowy!

Wywołanie przelewowej metody javascript'owej

Przykład

           $(document).ready(function(){var extraData ={ 
           firstExampleParameterName:"firstExampleParameterValue",
           secondExampleParameterName:"secondExampleParameterValue"};var Przelewy24MasterPassConfiguration ={
           authorizeSuccessExtraData: extraData//     callLightboxErrorCallback: function() { /* doSomething */ },//     callLightboxRequestFailedCallback: function() { /* doSomething */ },//        authorizeErrorCallback: function() { /* doSomething */ },//     authorizeRequestFailedCallback: function() { /* doSomething */ },//     authorizeFailureCallback: function() { /* doSomething */ }};
Przelewy24MasterPass.configure(Przelewy24MasterPassConfiguration);
       Przelewy24MasterPass.handle(MasterPass);});

Własnoręczna obsługa metod

  • Funkcja CallLightErrorCallback

Funkcja wykonywana przy zwróceniu błędu podczas wywołania lightbox’a MasterPass. Lightbox się nie pojawia.

Nazwa ogólna Wartość przykładowa Typ Rodzaj błędu !
Error {errorCode: "err196" error message: "Error err196." } * Object Błędna metoda płatności
Error {errorCode:"err197" error message: "Error err 197." } * Object Powrót do poprzedniego okna po wywołaniu posta
Error {errorCode:"err198" error message: "Error err 198."} * Object Błędne ID klienta

*Może występować więcej niż jeden obiekt.

  • Funkcja CallLightboxRequestFailedCallback

Wysyłana w sytuacji, gdy nie udało się wysłać POST’a z systemu sprzedawcy. Wrapper na metodę failure wykonywany po nieudanej próbie post’a za pomocą jQuery. - tutaj przykład danej funkcji-

  • Funkcja AuthorizeErrorCallback

Brak możliwości przeprowadzenia autoryzacji. Wszystkie czynności w oknie lightbox masterpass zostały wykonane poprawnie, ale system przelewy24 nie mógł przeprowadzić autoryzacji. - tutaj przykład danej funkcji-

  • Funkcja AuthorizeRequestFailedCallback

Nie udało się wysłać POST’a z systemu sprzedawcy. Wrapper na metodę failure wykonywaną po nieudanej próbie post’a za pomocą jQuery. - tutaj przykład danej funkcji-

  • Funkcja AuthorizeSuccessExtraData

Dodatkowe dane w formacie Json, które zostaną przesłane wraz z zakończeniem autoryzacji. - tutaj przykład danej funkcji-

  • Funkcja AuthorizeFailureCallback

Błędna odpowiedź z MasterPass. - tutaj przykład danej funkcji-

Obsługa odpowiedzi

W odpowiedzi przychodzi status true/false. Pozostałe dane sklep musiałby przekazać sobie w “authorizeSuccessExtraData”

5.5 Visa Checkout

Wstęp

Visa Checkout to proces pozwalający na uzyskanie danych teleadresowych klienta oraz identyfikatora zamówienia CallID umożliwiającego obciążenie.

W celu skorzystania z usługi konieczna jest aktywacja po stronie operatora VISA. Instrukcja aktywacji usługi VisaCheckout dla merchantów

Przebieg procesu

Schemat przebiegu procesu Visa Checkout

  • Wywołanie skryptu z implementacji VisaCheckout
  • Pozyskanie identyfikatora callId
  • Rejestracja transakcji w systemie Przelewy24
  • Wywołanie skryptu Przelewy24 wraz z callId w celu obciążenia karty klienta
  • Autoryzacja transakcji
  • Odebranie wyniku
  • Weryfikacja transakcji

Wywołanie skryptu z implementacji VisaCheckout

<head>

<script type="text/javascript">
    function onVisaCheckoutReady() {
        
        var configuration = {
            apikey: MERCHANT_API_KEY,
            paymentRequest: {
                currencyCode: "PLN",
                total: "0.10"
            }
        };

        V.init(configuration);

        V.on("payment.success", function (payment) {
            alert("PAYMENT SUCCEEDED");
            processVisaChecoutResponse(payment); // TODO: implement
        });

        V.on("payment.cancel", function (payment) {
            alert("PAYMENT CANCELED");
        });

        V.on("payment.error", function (payment, error) {
            alert("PAYMENT ERROR");
        });
    }
</script>

</head>

<body>
<img alt="Visa Checkout" class="v-button" role="button"
     src="https://sandbox.secure.checkout.visa.com/wallet-services-web/xo/button.png"/>

<script type="text/javascript"
        src="https://sandbox-assets.secure.checkout.visa.com/checkout-widget/resources/js/integration/v1/sdk.js">
</script>
</body>

Zgodnie z dokumentacją Visa Checkout Po stronie Partnera konieczne jest zamieszczenie kodu Javascript pozwalającego na wywołanie okna logowania Visa Checkout. Wywołanie powinno zawierać dane zamówienia dla którego zostanie wykonane obciążenie.

Exclam.svg Ważne Kwoty przekazywane do Visa wyrażone są zgodnie z definicją przypisaną do konta VCO. Domyślna wartość wyrażana jest w podstawowej jednostce monetarnej np. 1.00 PLN.

Pozyskanie identyfikatora callID

Na event: Payment.Success dostarczone są wszystkie parametry będące wynikiem procesu Visa Checkout. Obiekt "payment" zawiera między innymi CallID na podstawie którego wykonane zostanie obciążenie. Visa w parametrze "encPaymentData" przesyła również zaszyfrowane dane kupującego t.j. Imię i nazwisko, numer telefonu, adres e-mail oraz adres zamieszkania czyli te, które są konieczne do realizacji zamówienia.

Przykład kodu deszyfrującego parametr encPaymentData

Rejestracja transakcji

Płatności_internetowe#2.2_Rejestracja_Transakcji Rejestracja transakcji powinna zostać wykonana zgodnie z procesem płatności internetowej Przelewy24.

<form action="https://secure.przelewy24.pl/trnRegister" method="POST" class="form">
    <input type="text" name="p24_session_id" value="SESSION_ID"/> 
    <input type="text" name="p24_merchant_id" value="TWÓJID_SPRZEDAWCY"/> 
    <input type="text" name="p24_pos_id" value="TWÓJID_SPRZEDAWCY"/> 
    <input type="text" name="p24_amount" value="KWOTA W WALUTA/100"/> 
    <input type="text" name="p24_currency" value="PLN"/> 
    <input type="text" name="p24_description" value="TYTUŁ"/> 
    <input type="text" name="p24_client" value="Jan Kowalski"/> 
    <input type="text" name="p24_address" value="ul. Polska 33/33"/> 
    <input type="text" name="p24_zip" value="66-777"/> 
    <input type="text" name="p24_city" value="Poznań"/> 
    <input type="text" name="p24_country" value="PL"/> 
    <input type="text" name="p24_email" value="email@host.pl"/> 
    <input type="text" name="p24_language" value="pl"/> 
    <input type="text" name="p24_url_status" value="http://myhost.pl/skrypt_st.php"/>
    <input type="text" name="p24_url_return" value="http://myhost.pl/skrypt_ok.php"/>
    <input type="text" name="p24_api_version" value="3.2"/> 
    <input type="hidden" name="p24_sign" value="e2c43dec9578633c518e1f514d3b434b"/> 
    <input name="submit_send" value="wyślij" type="submit"/> 
</form>
error=0&token={TOKEN}
error={KOD_BŁĘDU}&errorMessage=field1:desc1&field2:desc2...

errorMessage może zawierać informacje dotyczące wielu błędów.

post https://secure.przelewy24.pl/trnRegister

Parametry POST wywołania

Nazwa pola Typ Wymagane Opis
p24_merchant_id INT T ID sprzedawcy
p24_pos_id INT T ID Sklepu (domyślnie ID sprzedawcy)
p24_session_id STRING(100) T Unikalny identyfikator z systemu sprzedawcy.
p24_amount INT T Kwota transakcji wyrażona w WALUTA/100 (1.23 PLN = 123)
p24_currency STRING(3) T Waluta w jakiej ma być przyjęta płatność. (PLN,EUR,GBP,CZK...)
p24_description STRING(1024) T Opis transakcji
p24_email STRING(50) T Adres email klienta
p24_client STRING(100) N** Imię i nazwisko Klienta
p24_adress STRING(80) N** Adres Klienta
p24_zip STRING(10) N** Kod pocztowy klienta
p24_city STRING(50) N** Miasto Klienta
p24_country STRING(2) T Kody krajów zgodne z ISO 3166
p24_phone STRING(12) N Telefon klienta w formacie: 48111222333
p24_language STRING(2) N pl/ en / de / es / it
p24_method INT N Identyfikator metody płatności. Lista metod płatności widoczna w panelu lub dostępna przez API.
p24_url_return STRING(250) T Adres powrotny, na który zostanie przekierowany Klient, bez względu na wynik płatności.
p24_url_status STRING(250) N Adres URL na który zostaną przekazane informacje o wpłacie w przypadku poprawnej płatności.
p24_time_limit INT N Limit czasu na wykonanie transakcji przez Klienta.

0 - brak limitu, maks. 99(czas w minutach)

p24_wait_for_result INT N Oczekiwanie na przekazanie notyfikacji o płatności transakcji

0 - nie, 1 - tak

p24_channel INT N
p24_shipping INT N Koszt dostawy / wysyłki / etc.
p24_transfer_label STRING(20) N Opis pojawiający się w tytule przelewy 1
p24_api_version STRING(5) T Wersja API wg której realizowane jest wdrożenie. Zalecane: 3.2
p24_sign STRING(100) T Suma kontrolna wyliczana według wzoru opisanego w Obliczanie p24_sign
p24_encoding STRING(15) N System kodowania przesyłanych znaków:

ISO-8859-2, UTF-8, Windows-1250

Lista zakupów, gdzie X jest liczbą od 1 do 100 (opcjonalne 2)
p24_name_X STRING(127) T Nazwa towaru
p24_description_X STRING(127) N Dodatkowy opis towaru
p24_quantity_X INT T Ilość sztuk towaru
p24_price_X INT T Cena jednostkowa towaru
p24_number_X INT N ID towaru w systemie sprzedawcy
Parametry Wyjścia
Nazwa_pola Typ Opis
error INT Rezultat żądania
token String Identyfikator wywołania, stosowany m.in. w TrnRequest, Występuje tylko gdy error=0
ErrorMessage String Informacja o zaistniałym błędzie w wywołaniu. Występuje tylko gdy error!=0

Encoding: https://secure.przelewy24.pl/external/{SHOPID}.wsdl

Literal: https://secure.przelewy24.pl/external/{SHOPID}s.wsdl

Metoda RegisterTransaction

$details = array(
     array('name'=>'p24_session_id','value'=>'SESSION_ID'), 
     array('name'=>'p24_merchant_id','value'=>'9999'), 
     array('name'=>'p24_pos_id','value'=>'9999'), 
     array('name'=>'p24_amount','value'=>'KWOTA W WALUTA/100'), 
     array('name'=>'p24_currency','value'=>'PLN'), 
     array('name'=>'p24_description','value'=>'TYTUŁ'), 
     array('name'=>'p24_client','value'=>'Jan Kowalski'), 
     array('name'=>'p24_address','value'=>'ul. Polska 33/33'), 
     array('name'=>'p24_zip','value'=>'66-777'), 
     array('name'=>'p24_city','value'=>'Poznań'), 
     array('name'=>'p24_country','value'=>'PL'), 
     array('name'=>'p24_email','value'=>'email@host.pl'), 
     array('name'=>'p24_language','value'=>'pl'), 
     array('name'=>'p24_url_status','value'=>'http://myhost.pl/skrypt_st.php'),
     array('name'=>'p24_url_return','value'=>'http://myhost.pl/skrypt_ok.php'),
     array('name'=>'p24_api_version','value'=>'3.2'), 
     array('name'=>'p24_sign','value'=>md5('SESSION_ID|9999|KWOTA W WALUTA/100|PLN|KLUCZ_CRC'))
    );
$soap = new SoapClient("https://secure.przelewy24.pl/external/wsdl/9999.wsdl");
$res = $soap->RegisterTransaction("9999", "anuniquekeyretrievedfromprzelewy24", $details);
Parametry wejściowe
nazwa typ opis
login string ID Sprzedawcy
pass string Klucz do WS uzyskany z Przelewy24
details array Tablica parametrów w formacie:

"<item><name>[Nazwa parametru]</name><value>[wartość]</value></item>"

(patrz tabela poniżej)

Parametry wyjściowe
nazwa typ
result Token transakcji
error GeneralError
GeneralError
Obiekt z informacją o błędach.
dostępne pola typ opis
errorCode int unikalny kod błędu
errorMessage string

Parametry tablicy details mogą przyjąć następujące wartości:

Nazwa pola Typ Wymagane Opis
p24_merchant_id INT T ID sprzedawcy
p24_pos_id INT T ID Sklepu (domyślnie ID sprzedawcy)
p24_session_id STRING(100) T Unikalny identyfikator z systemu sprzedawcy.
p24_amount INT T Kwota transakcji wyrażona w WALUTA/100 (1.23 PLN = 123)
p24_currency STRING(3) T Waluta w jakiej ma być przyjęta płatność. (PLN,EUR,GBP,CZK...)
p24_description STRING(1024) T Opis transakcji
p24_email STRING(50) T Adres email klienta
p24_client STRING(100) N** Imię i nazwisko Klienta
p24_adress STRING(80) N** Adres Klienta
p24_zip STRING(10) N** Kod pocztowy klienta
p24_city STRING(50) N** Miasto Klienta
p24_country STRING(2) T Kody krajów zgodne z ISO 3166
p24_phone STRING(12) N Telefon klienta w formacie: 48111222333
p24_language STRING(2) N pl/ en / de / es / it
p24_method INT N Identyfikator metody płatności. Lista metod płatności widoczna w panelu lub dostępna przez API.
p24_url_return STRING(250) T Adres powrotny, na który zostanie przekierowany Klient, bez względu na wynik płatności.
p24_url_status STRING(250) N Adres URL na który zostaną przekazane informacje o wpłacie w przypadku poprawnej płatności.
p24_time_limit INT N Limit czasu na wykonanie transakcji przez Klienta.

0 - brak limitu, maks. 99(czas w minutach)

p24_wait_for_result INT N Oczekiwanie na przekazanie notyfikacji o płatności transakcji

0 - nie, 1 - tak

p24_channel INT N
p24_shipping INT N Koszt dostawy / wysyłki / etc.
p24_transfer_label STRING(20) N Opis pojawiający się w tytule przelewy 1
p24_api_version STRING(5) T Wersja API wg której realizowane jest wdrożenie. Zalecane: 3.2
p24_sign STRING(100) T Suma kontrolna wyliczana według wzoru opisanego w Obliczanie p24_sign
p24_encoding STRING(15) N System kodowania przesyłanych znaków:

ISO-8859-2, UTF-8, Windows-1250

Lista zakupów, gdzie X jest liczbą od 1 do 100 (opcjonalne 2)
p24_name_X STRING(127) T Nazwa towaru
p24_description_X STRING(127) N Dodatkowy opis towaru
p24_quantity_X INT T Ilość sztuk towaru
p24_price_X INT T Cena jednostkowa towaru
p24_number_X INT N ID towaru w systemie sprzedawcy

Końcowe wartości parametrów związane z transakcją kierowane do Visa Checkout powinny być zgodne z wartościami użytymi przy rejestracji transakcji w systemie Przelewy24.

Parametry powiązane
Opis Visa Checkout Przelewy24
Finalna kwota obciążenia total [wyrażona w złotówkach] p24_amount [wyrażona w groszach]
Waluta transakcji currencyCode p24_currency

Wywołanie skryptu Przelewy24 wraz z callId w celu obciążenia karty klienta

<?php
$token = '1234567890-123456-123456-1234567890'; // TODO
$callId = '1234567890123456789'; // TODO
?>
<!doctype html>
<html lang="en">
<head>
    <script src="<?php echo 'https://secure.przelewy24.pl/api/v1/VisaCheckout/' . $token; ?>"></script>
</head>
<body>
<script>
    document.addEventListener("DOMContentLoaded", function () {
        Przelewy24VisaCheckout.configure({
            errorCallback: function () {
                alert("error");
            },
            requestFailedCallback: function () {
                alert("request failed");
            },
            exceptionCallback: function () {
                alert("exception");
            },
            completePaymentCallback: function () {
                alert("success");
            }
        });
        Przelewy24VisaCheckout.charge({callId: <?php echo "'{$callId}'"; ?>});
    });
</script>
</body>
</html>
<body>

Gotowy kod JavaScript pozwala na wykonanie obciążenia karty klienta oraz aktualizację danych zamówienia zarejestrowanego w procesie Visa Checkout. Wszelkie dane powinny zostać przekazane jako argument funkcji Przelewy24VisaCheckout.charge w formacie JSON.

Możliwe parametry JSON
Parametr Opis Wymagany
callId identyfikator zamówienia pozyskany w procesie VCO TAK
promoCode Kod promocyjny VISA TAK*/NIE
discount Wartość żniżki VISA TAK*/NIE
subtotal Wartość koszyka podana w procesie Visa Checkout NIE
giftWrap Koszt opakowania NIE
shippingHandling Koszt dostawy NIE
tax Wartość podatku NIE

* Obowiązkowe, jeśli zastosowany został rabat w porozumieniu z VISA.

Autoryzacja Transakcji

Wywołanie metody Przelewy24VisaCheckout.charge spowoduje rozpoczęcie procesu autoryzacji.

W zależności od rodzaju karty klienta możliwe są następujące kroki:

  1. Po wywołaniu metody wyświetli się okienko CVV.
  2. Jeśli karta ma dcc, pojawi się okienko z dcc do przewalutowania.
  3. Jeśli karta ma 3d secure, nastąpi przekierowanie na stronę banku i powrót na formatkę z przyciskiem powrotu na stronę sklepu.

Proces może zakończyć się po każdym z kroków.

Odebranie wyniku

Po zakończeniu procesu transakcyjnego w zależności od jego wyniku zostanie wywołana jedna z poniższych funkcji. Niezależnie zostaje również wysłane powiadomienie na p24_url_status

Wywołania zwrotne
Nazwa Parametry Opis
errorCallback Errors: [{

errorMessage: errorCode: }]*

response: [{ action: „display” html: „HTML” info: „cvv” }, {...}*]

Wystąpił błąd (limit, czarna lista etc.)
RequestFailedCallback jqXHR, textStatus, errorThrown Błąd w połączeniu (request się nie udał)
exceptionCallback err Błąd w działaniu skryptu lub nieprawidłowe dane
CompletedPaymentCallback ** Proces płatności zakończony powodzeniem

*Może wystąpić wielokrotnie.

**Występuje zawsze, gdy nie ma przekierowania na 3DSecure.

Exclam.svg Ważne W przypadku 3DSecure klient wróci na adres zdeklarowany w żądaniu transakcji jako p24_url_return

Weryfikacja Transakcji

Weryfikacja transakcji Visa Checkout odbywa się zgodnie z procesem płatności internetowej.

post https://secure.przelewy24.pl/trnVerify

Parametry Wejścia
Nazwa pola Typ Opis
p24_merchant_id INT ID sprzedawcy
p24_pos_id INT ID sklepu (domyślnie ID Sprzedawcy)
p24_session_id STRING(100) Unikalny identyfikator z systemu sprzedawcy
p24_amount INT Kwota transakcji wyrażona w WALUTA*100 (1.23 PLN = 123)
p24_currency STRING(3) PLN, EUR, GBP, CZK
p24_order_id INT Numer transakcji nadany przez Przelewy24
p24_sign STRING Suma kontrolna wyliczana według wzoru opisanego w Obliczanie p24_sign z pól: p24_session_id, p24_order_id, p24_amount, p24_currency i pola Klucz CRC.

Metoda VerifyTransaction

<?php
$soap = new SoapClient("https://secure.przelewy24.pl/external/9999.wsdl");
$res = $soap-> VerifyTransaction('9999', 'keyfromprzelewy24', 123456, 'abcdef', 1000);
if ($res->error->errorCode) {
 echo 'Something went wrong: ' . $res->error->errorMessage;
} else {
 echo 'Transaction OK';
}
?>

Encoding: https://secure.przelewy24.pl/external/{SHOPID}.wsdl

Literal: https://secure.przelewy24.pl/external/{SHOPID}s.wsdl

Parametry wejściowe
nazwa typ opis
login string ID Sprzedawcy
pass string Klucz do WS uzyskany z Przelewy24
orderId int Numer transakcji nadany przez Przelewy24
sessionId string Session ID
amount int Kwota wyrażona w danej walucie, w setnej części (1/100 waluty podstawowej)
currency string Waluta: PLN / EUR / CHF / USD / GBP (default: PLN)
Parametry wyjściowe
nazwa typ opis
result bool true jeżeli transakcja jest poprawna, w przeciwnym wypadku false
error GeneralError


Powiązane typy danych
GeneralError
Obiekt z informacją o błędach.
dostępne pola typ opis
errorCode int unikalny kod błędu
errorMessage string

6. Raporty

6.1 Wstęp

System Przelewy24 pozwala na bezpośrednie pobieranie danych o realizowanych transakcjach do aplikacji Partnera.

6.2 Opis

Raporty WebService są alternatywą dla tych obecnych w panelu transakcyjnym. Udostępnione metody WebService w systemie Przelewy24, pozwalają w łatwy sposób uzyskać wszelkie informacje o przeprowadzonych transakcjach. Dzięki zastosowanej technologii SOAP,REST serwer Przelewy24 może stać się częścią aplikacji partnera jako źródło danych. Mogą one być w dowolny sposób przetworzone w celu uzyskania dokładnie dostosowanych raportów.

Do dyspozycji są:

GetTransactionBySessionId - Szczegółowe informacje dotyczące poszczególnej transakcji.

<?php
$soap = new SoapClient("https://secure.przelewy24.pl/external/9999.wsdl");
$res = $soap->GetTransactionBySessionId
 ('9999', 'anuniquekeyfromp24', 'f3958fjsxndri');
// $res->result contains data about transaction, or object with empty
field in case of error
if ($res->error->errorCode) {
 echo 'Something went wrong: ' . $res->error->errorMessage;
} else {
 echo 'Transaction: ';
 $transaction = $res->result;
 // data of transaction: $transaction->orderId, $transaction->amount,
$transaction->date
}
?>

Encoding: https://secure.przelewy24.pl/external/{SHOPID}.wsdl

Literal: https://secure.przelewy24.pl/external/{SHOPID}s.wsdl

Parametry wejściowe
nazwa typ opis
login string ID Sprzedawcy
pass string Klucz do WS uzyskany z Przelewy24
sessionId string SessionID transakcji
Parametry wyjściowe
nazwa typ
result Transaction
error GeneralError


Powiązane typy danych
Transaction
Obiekt pojedynczej transakcji.
dostępne pola typ opis
orderId int identyfikator transakcji
sessionId string sesja transakcji
status int 0 – brak wpłaty, 1 – przedpłata, 2 – dokonana, 3 – zwrócona
amount int kwota wpłaty
currency string
date string YYYYMMDDHHMM
dateOfTransaction string
clientEmail string
accountMD5 string
paymentMethod int
description string
clientAddress string
clientCity string
clientName string
clientPostcode string
batchId int ID paczki, w której transakcja została przekazana na rachunek bankowy Sprzedawcy. Jeżeli transakcja nie została jeszcze przypisana do paczki pojawi się wartość 0
fee int
statement string Informacja o tytule przelewu przedstawionym klientowi w procesie płatności
GeneralError
Obiekt z informacją o błędach.
dostępne pola typ opis
errorCode int unikalny kod błędu
errorMessage string

GetTransactionsByDate - Lista transakcji wykonanych w danym dniu.

<?php
$soap = new SoapClient("https://secure.przelewy24.pl/external/9999.wsdl"); 
$res = $soap->GetTransactionsByDate
 ('9999', 'anuniquekeyretrievedfromp24', '20110610');
// $res->result contains data about transactions, or object with empty
field in case of error
if ($res->error->errorCode) {
 echo 'Something went wrong: ' . $res->error->errorMessage;
} else {
 echo 'Transaction: ';
 $LIST = $res->result;
 foreach ($LIST as $transaction) {
 // data of transaction: $transaction->orderId, $transaction->amount,
$transaction->date
 // ...
 }
}
?>

Encoding: https://secure.przelewy24.pl/external/{SHOPID}.wsdl

Literal: https://secure.przelewy24.pl/external/{SHOPID}s.wsdl

Parametry wejściowe
nazwa typ opis
login string ID Sprzedawcy
pass string Klucz do WS uzyskany z Przelewy24
date string Data w formacie: YYYYMMDD
Parametry wyjściowe
nazwa typ
result array of Transaction
error GeneralError


Powiązane typy danych
Transaction
Obiekt pojedynczej transakcji.
dostępne pola typ opis
orderId int identyfikator transakcji
sessionId string sesja transakcji
status int 0 – brak wpłaty, 1 – przedpłata, 2 – dokonana, 3 – zwrócona
amount int kwota wpłaty
currency string
date string YYYYMMDDHHMM
dateOfTransaction string
clientEmail string
accountMD5 string
paymentMethod int
description string
clientAddress string
clientCity string
clientName string
clientPostcode string
batchId int ID paczki, w której transakcja została przekazana na rachunek bankowy Sprzedawcy. Jeżeli transakcja nie została jeszcze przypisana do paczki pojawi się wartość 0
fee int
statement string Informacja o tytule przelewu przedstawionym klientowi w procesie płatności
GeneralError
Obiekt z informacją o błędach.
dostępne pola typ opis
errorCode int unikalny kod błędu
errorMessage string

GetTransactionsByBatch - Lista transakcji rozliczonych w danej paczce.

<?php
$soap = new SoapClient("https://secure.przelewy24.pl/external/9999.wsdl");
$res = $soap->GetTransactionsByBatch
 ('9999', 'anuniquekeyretrievedfromp24', '123456');
// $res->result contains data about transactions, or object with empty field in case of error 
if ($res->error->errorCode) {
 echo 'Something went wrong: ' . $res->error->errorMessage;
} else {
 echo 'Transaction: ';
 $LIST = $res->result;
 foreach ($LIST as $transaction) {
 // data of transaction: $transaction->orderId, $transaction-
>amount, $transaction->date
 // ...
 }
}
?>

Encoding: https://secure.przelewy24.pl/external/{SHOPID}.wsdl

Literal: https://secure.przelewy24.pl/external/{SHOPID}s.wsdl

Parametry wejściowe
nazwa typ opis
login string ID Sprzedawcy
pass string Klucz do WS uzyskany z Przelewy24
batch int Unikalny indetyfikator paczki
Parametry wyjściowe
nazwa typ
result array of Transaction
error GeneralError


Powiązane typy danych
Transaction
Obiekt pojedynczej transakcji.
dostępne pola typ opis
orderId int identyfikator transakcji
sessionId string sesja transakcji
status int 0 – brak wpłaty, 1 – przedpłata, 2 – dokonana, 3 – zwrócona
amount int kwota wpłaty
currency string
date string YYYYMMDDHHMM
dateOfTransaction string
clientEmail string
accountMD5 string
paymentMethod int
description string
clientAddress string
clientCity string
clientName string
clientPostcode string
batchId int ID paczki, w której transakcja została przekazana na rachunek bankowy Sprzedawcy. Jeżeli transakcja nie została jeszcze przypisana do paczki pojawi się wartość 0
fee int
statement string Informacja o tytule przelewu przedstawionym klientowi w procesie płatności
GeneralError
Obiekt z informacją o błędach.
dostępne pola typ opis
errorCode int unikalny kod błędu
errorMessage string

GetRefundInfo - Szczegółowe informacje dotyczące poszczególnego zwrotu.

<?php
$soap = new SoapClient("https://secure.przelewy24.pl/external/9999.wsdl");
$res = $soap->GetRefundInfo('9999', 'anuniquekeyretrievedfromp24', 38919018);
if ($res->error->errorCode > 0) { 
// something went wrong
 echo 'An error occurred: ' . $res->error->errorMessage;
} else {
 foreach ($res->result as $refund) {
 echo 'Status: ' . $refund->statusTxt;
 }
}
?>

Encoding: https://secure.przelewy24.pl/external/{SHOPID}.wsdl

Literal: https://secure.przelewy24.pl/external/{SHOPID}s.wsdl

Parametry wejściowe
nazwa typ opis
login string ID Sprzedawcy
pass string Klucz do WS uzyskany z Przelewy24
orderId int Numer transakcji nadany przez Przelewy24
Parametry wyjściowe
nazwa typ
result array of RefundInfo
error GeneralError


Powiązane typy danych
RefundInfo
Obiekt z informacją o pojedynczym zwrocie.
dostępne pola typ opis
orderId int
sessionId string
batchId int
requestId int
date string format YYMMDDHHIISS
status int
statusTxt string
amount int
GeneralError
Obiekt z informacją o błędach.
dostępne pola typ opis
errorCode int unikalny kod błędu
errorMessage string

GetRefundsByDate - Lista zwrotów z danego dnia.

<?php
$soap = new SoapClient("https://secure.przelewy24.pl/external/9999.wsdl");
$params = [
    "login" => 9999,
    "pass" => "anuniquekeyretrievedfromprzelewy24",
    "spid" => "20161228"
];
$res = $soap->__soapCall("GetRefundsByDate", $params);

if(!$res->error->errorCode) {
    foreach ($res->result as $refund) {
        echo 'Zwrot z transakcji ' . $refund->orderId . ' na kwotę (w gr) ' . $refund->amount . "\n";
    }
}

Encoding: https://secure.przelewy24.pl/external/{SHOPID}.wsdl

Literal: https://secure.przelewy24.pl/external/{SHOPID}s.wsdl

Parametry wejściowe
nazwa typ opis
login string ID Sprzedawcy
pass string Klucz do WS uzyskany z Przelewy24
date string Data w formacie YYYYMMDD
Parametry wyjściowe
nazwa typ
result array of RefundInfo
error GeneralError

Typy danych:

RefundInfo
Obiekt z informacją o pojedynczym zwrocie.
dostępne pola typ opis
orderId int
sessionId string
batchId int
requestId int
date string format YYMMDDHHIISS
status int
statusTxt string
amount int
GeneralError
Obiekt z informacją o błędach.
dostępne pola typ opis
errorCode int unikalny kod błędu
errorMessage string