API przekazy masowe - Dokumentacja v 1.1, czerwiec 2014 KIP S.A. ul. Św. Marcin 73/6 61-808 Poznań www.kipsa.pl www.tpay.com
1 Bramka API Dokumentacja opisuje możliwość wykonania przekazów masowych za pomocą API. Adres bramki API transakcji jest zbudowany jest w następujący sposób: https://secure.transferuj.pl/api/gw/klucz/masspayment/metoda gdzie: klucz (api_key) unikalny ciąg dostępu, wygenerowany w Panelu Odbiorcy Płatności w zakładce Ustawienia->API metoda jedna czynności opisanych w rozdziale 2. Parametry operacji przesyłane są metodą POST. W każdym zapytaniu, oprócz ów dla danej metody, należy przesłać także wartość api_password. Jest on dostępny w panelu obok klucza, jednak podczas zakładania nowego dostępu do API należy hasło zapisać w swojej aplikacji. Nie przechowujemy go w formie jawnej więc nie będzie możliwe jego późniejsze wyświetlenie w panelu. Jeżeli utracisz hasło jedyną formą uzyskania dostępu będzie wygenerowanie/przekazanie nowego hasła. Klucz oraz hasło są wartościami tajnymi, wymagana jest szczególna ostrożność przy przechowywaniu i przekazywaniu tych danych. Jeżeli uznasz, że mogły wpaść w niepowołane ręce, możesz zablokować dostęp dla wybranego klucza w Panelu Odbiorcy Płatności lub zmienić hasło. Za wszelkie operacje poprzez dostęp API odpowiada Odbiorca Płatności zarejestrowany i posiadający konto w tpay.com, do którego przypisany jest dostęp API (klucz oraz hasło). Regulamin korzystania z usługi masowych przekazów można znaleźć w poniższym linku: https://secure.transferuj.pl/partner/pliki/regulamin_transferow_masowych.pdf 2
2 Metody create Metoda dodaje do systemu paczkę przelewów. Po poprawnym wykonaniu operacji, należy wywołać metodę authorize w celu potwierdzenia zlecenia wypłaty. Przelewy są realizowane raz dziennie w dni robocze. Parametry konieczne do stworzenie przelewu masowego muszą być przesłane metodą POST. Poniżej wymagane y (oprócz wymaganych opisanych w rozdziale 1): csv sign lista przelewów zakodowana za pomocą base64. Format opisany w rozdziale 4. Suma kontrolna służąca do weryfikacji otrzymywanych od Sprzedawcy ów. Zbudowana jest zgodnie z poniższym schematem wykorzystując funkcję skrótu SHA1: SHA1(seller_id + lista przelewów (przed zakodowaniem base64) + kod potwierdzający Odbiorcy Płatności) Implementacja obliczania sumy w języku PHP wygląda następująco: sha1($seller_id. $csv. $confirmation_code) Kod potwierdzający Odbiorcy Płatności można znaleźć w Panelu, w zakładce Ustawienia->Powiadomienia. Zmienna $seller_id to ID konta Sprzedawcy w systemie tpay.com. W odpowiedzi na żądanie zostanie wydrukowany dokument xml. W przypadku poprawnie przetworzonych przelewów, możliwe podelementy to: count Liczba przelewów zdefiniowanych w pliku csv sum Suma wszystkich przelewów (format d.2) pack_id ID stworzonej paczki przelewów (liczba). Wszystkie przelewy przesłane w jednym ze csv będą miały ten sam pack_id referers Pole widoczne, jeżeli przesłano ID w przelewach (zob. rozdz. 4) Format JSON w schemacie: ID w przelewie : ID przelewów systemie tpay.com. Umożliwia śledzenie pojedynczego przelewu. Przykład pozytywnej odpowiedzi: <?xml version="1.0" encoding="utf-8"?> <response> <>1</> <count>5</count> <sum>200.00</sum> <pack_id>1000</pack_id> <referers>{"afb74":"4507","afb80":"4508"}</referers> </response> 3
W przypadku wystąpienia błędu, zostaną zwrócone następujące podelementy: error Kod błędu w przypadku niepowodzenia, opis kodów w rozdziale 3. desc Opcjonalny opis błędu Przykład negatywnej odpowiedzi: <?xml version="1.0" encoding="utf-8"?> <response> <>0</> <err>err11</err> <desc>linia 2: Nazwa odbiorcy jest za długa - maks. 35 znaków </desc> </response> authorize Metoda autoryzuje wybraną paczkę do realizacji. Parametry wymagane to (oprócz opisanych w rozdziale 1): pack_id ID stworzonej paczki zwrócony w metodzie create. W odpowiedzi na żądanie zostanie wydrukowany dokument xml. W przypadku poprawnego procesowania, możliwe podelementy to: W przypadku wystąpienia błędu, zostaną zwrócone następujące podelementy: error Kod błędu, opis kodów w rozdziale 3. 4
packs Metoda pozwala przeglądać stworzone paczki. Przyjmowane są opcjonalne y pack_id from_date to_date ID stworzonej paczki zwrócony w metodzie create. początkowa data stworzenia paczki (metodą create) (format YYYY-MM-DD) końcowa data stworzenia paczki (metodą create) (format YYYY-MM-DD) Jeżeli żaden powyższy nie zostanie przesłany, zwrócone zostaną wszystkie paczki dla danego konta Odbiorcy Płatności. W odpowiedzi na żądanie zostanie wydrukowany dokument xml. W przypadku poprawnego procesowania, możliwe podelementy to: packs kontener zawierający znalezione paczki Jeżeli istnieją rekordy, w sekcji packs dostępne będą obiekty pack reprezentujące poszczególne paczki z następującymi elementami: pack_id date auth_date status count sum cost ID paczki data stworzenia paczki (format YYYY-MM-DD HH:mm:ss) data autoryzacji paczki (metodą authorize) (format YYYY-MM-DD HH:mm:ss) status paczki. Możliwe statusy to: pending - oczekuje na autoryzację auth - autoryzowana liczba przelewów w paczce suma przelewów w paczce (format d.2) dodatkowy koszt procesowania przelewów w paczce (format d.2) W przypadku wystąpienia błędu, zostaną zwrócone następujące podelementy: error Kod błędu, opis kodów w rozdziale 3. 5
Przykład poprawnej odpowiedzi: <?xml version="1.0" encoding="utf-8"?> <response> <>1</> <packs> <pack> <pack_id>768</pack_id> <date>2014-04-11 13:20:34</date> <auth_date>2014-04-11 13:20:44</auth_date> <status>auth</status> <count>2</count> <sum>268.72</sum> <cost>1.80</cost> </pack> <pack> <pack_id>747</pack_id> <date>2014-04-10 15:10:37</date> <auth_date>2014-04-10 16:01:19</auth_date> <status>auth</status> <count>3</count> <sum>1999.00</sum> <cost>2.70</cost> </pack> </packs> </response> transfers Metoda pozwala przeglądać przelewy należące do danej paczki. Parametry wejściowe to (oprócz opisanych w rozdziale 1) - wymagany jest co najmniej jeden: pack_id ID paczki zwrócony w metodzie create. tr_id ID przelewu w systemie tpay.com (zob. metada create) W odpowiedzi na żądanie zostanie wydrukowany dokument xml. W przypadku poprawnego procesowania, możliwe podelementy to: transfers kontener zawierający przelewy 6
Jeżeli istnieją rekordy, w sekcji transfers dostępne będą obiekty transfer reprezentujące poszczególne przelewy z następującymi elementami: date auth_date acc_date status accnum rcv1 do rcv4 amount title1 do title2 tr_id data stworzenia stworzenia przelewu (format YYYY-MM-DD HH:mm:ss) data autoryzacji przelewu (metodą authorize). Pole może być puste. Format YYYY-MM-DD HH:mm:ss data księgowania przelewu. Pole może być puste. Format YYYY-MM-DD HH:mm status przelewu. Możliwe statusy to: pending - oczekuje na autoryzację auth - autoryzowany, oczekuje na pobranie przez system processed - wysłane do banku done - zaksięgowane numer konta (format IBAN, 26 cyfr) odbiorca kwota przelewu (format d.2) tytuł przelewu ID przelewu w systemie tpay.com W przypadku wystąpienia błędu, zostaną zwrócone następujące podelementy: error Kod błędu, opis kodów w rozdziale 3. Przykład poprawnej odpowiedzi: <?xml version="1.0" encoding="utf-8"?> <response> <>1</> <transfers> <transfer> <date>2014-04-11 19:07:54</date> <auth_date>2014-04-11 19:07:59</auth_date> <acc_date>2014-04-12 11:07:59</acc_date> <status>auth</status> <accnum>12345678901234567890123456</accnum> <rcv1>jan Kowalski</rcv1> <rcv2/><rcv2/> <rcv3/><rcv2/> <rcv4/><rcv2/> <amount>0.02</amount> 7
<title1>przykladowy przelew</title1> <title2/> <tr_id>3432</tr_id> </transfer> </ transfers > </response> 8
3 Kody błędów kod ERR4 ERR6 ERR7 ERR8 ERR9 ERR10 ERR11 ERR12 ERR13 ERR14 ERR15 ERR16 ERR17 ERR18 ERR19 ERR20 ERR21 ERR22 ERR23 ERR24 ERR99 ERR98 ERR97 ERR31 ERR32 Nie został przesłany plik o rozszerzeniu csv Niepoprawna suma kontrolna (sign) Niepoprawny format linii Niepoprawny format numeru rachunku Nazwa odbiorcy nie może być pusta Nazwa odbiorcy 1 jest za długa - maks. 35 znaków Nazwa odbiorcy 2 jest za długa - maks. 35 znaków Nazwa odbiorcy 3 jest za długa - maks. 35 znaków Nazwa odbiorcy 4 jest za długa - maks. 35 znaków Niepoprawny format kwoty Pole tytuł 1 nie może być puste Pole tytuł 1 jest za długie - maks. 35 znaków Pole tytuł 2 jest za długie - maks. 35 znaków Błąd wewnętrzny Nie udało się załadować pliku o rozszerzeniu csv Błąd przetwarzania przelewów Niepoprawny pack_id lub nie znaleziono paczki Błąd przy autoryzacji paczki Za mało środków do autoryzacji paczki Paczka została już autoryzowana Błąd ogólny błąd logowania (błędny klucz lub api_password) brak metody dostęp wyłączony dostęp zabroniony (poprzez reguły w panelu Odbiorcy Płatności) 9
4 Przykładowy plik csv Każda linia zawiera osobny przelew wg formatu przedstawionego poniżej. Kolumny są rozdzielone średnikami. Plik nie posiada nagłówka. nr rachunku (26 cyfr);odbiorca 1 (35 znaków);odbiorca 2 (35 znaków);odbiorca 3 (35 znaków);odbiorca 4 (35 znaków);kwota (z, lub.);tytuł 1 (35 znaków);tytuł 2 (35 znaków);id przelewu w systemie Sprzedawcy W polach odbiorca 1-4 należy umieścić nazwę odbiorcy płatności. Każde pole może mieć maksymalnie 35 znaków długości. Jeżeli nazwa odbiorcy jest długości np. 40 znaków, 35 umieszamy w polu odbiorca 1, a następne 5 znaków w polu odbiorca 2. Ta sama zasada obowiązuje przy wprowadzaniu tytułu przelewu. Pole ID przelewu w systemie Sprzedawcy nie jest obowiązkowe, bez niego format przelewu wygląda następująco: nr rachunku (26 cyfr);odbiorca 1 (35 znaków);odbiorca 2 (35 znaków);odbiorca 3 (35 znaków);odbiorca 4 (35 znaków);kwota (z, lub.);tytuł 1 (35 znaków);tytuł 2 (35 znaków);id przelewu w systemie Sprzedawcy Przykładowy plik o rozszerzeniu csv można pobrać ze strony: https://secure.transferuj.pl/partner/pliki/przyklad.csv 10