-
Założenia wstępne
Niniejsza dokumentacja zawiera informacje potrzebne do integracji serwisu internetowego z bramką płatności Espago, przy użyciu starszej wersji APIv2.0.
Ta część dokumentacji nie jest już aktualizowana. W celu uzyskania najnowszej i uaktualnianej dokumentacji proszę przejsć do dokumentacji APIv3 na stronie https://start.espago.com
-
Integracja
- Proces integracji odbywa się w dwóch etapach:
- integracja ze środowiskiem testowym (opisana w tej dokumentacji)
- zmiana parametrów połączenia na odpowiadające środowisku produkcyjnemu (zmiany wymaga 5 parametrów: adres bramki, ID aplikacji, hasło API, klucz publiczny, wartość parametru live w konstruktorze Espago).
- Przejście do drugiego i zarazem końcowego etapu integracji musi zostać poprzedzone testami webaplikacji klienta w środowisku testowym (dokonywanymi przez integrującego się klienta) oraz ogólną weryfikacją webaplikacji i poprawności implementacji formularza płatności (dokonaną przez Dział Wsparcia Espago).
- Panel z możliwością przeglądania i ustawiania parametrów oraz przeglądania testowych płatności, zapytań i odpowiedzi dostępny jest pod adresem https://sandbox.espago.com
- W ramach integracji należy sprawdzić działanie funkcji takich jak:
- tworzenie tokenów,
- obciążenie kart,
- uzyskiwanie informacji na temat dokonanych płatności,
- realizację zwrotów i anulowanie transakcji (nie ma konieczności implementowania tych funkcji, ale bywają potrzebne i warto sprawdzić możliwość wykonania jej ręcznie zapytaniem curl),
- tworzenie profilów klienta i zarządzanie nimi (o ile jest uzasadnienie biznesowe, np. w sklepach, w których zakupy klienta mają się powtarzać)
- tworzenie planów i subskrypcji (o ile jest uzasadnienie biznesowe, np. konieczność cyklicznych obciążeń, które mają być automatycznie wywoływane przez bramkę Espago).
- Po zintegrowaniu się ze środowiskiem produkcyjnym środowisko testowe pozostaje w dalszym ciągu do dyspozycji Klienta.
- Na prośbę Sprzedawcy Dział Wsparcia Espago może m.in.:
- Dodać nowy serwis w obrębie konta Sprzedawcy (np. do obsługi innej waluty)
- Włączyć/wyłączyć możliwość tworzenia i korzystania z planów i subskrypcji (domyślnie wyłączone).
- Włączyc/wyłaczyć możliwość autoryzacji automatycznej i na żądanie (domyślnie wyłączone).
- Utworzyć nowego użytkownika z dostępem do panelu.
- Udzielać odpowiedzi i pomagać rozwiązywać problemy związane z integracją.
- W zakładce download dostępne są przykładowe pliki przyspieszające integrację.
- Proces integracji odbywa się w dwóch etapach:
-
Ogólny opis działania bramki
- Wszystkie operacje związane z płatnościami realizuje się przy pomocy zapytań API.
- Oznacza to, że nie ma "strony płatności" na którą Państwo muszą przekierować klientów.
- Odpowiednio skonstruowany formularz płatności (wykorzystujący udostępniany przez nas skrypt) może być umieszczony w Państwa serwisie.
- Możliwość przekierowania na "stronę płatności Espago" pojawi się ponownie w nowej wersji API w pierwszym kwartale 2015.
- Adres aplikacji dla środowiska testowego to https://sandbox.espago.com/api
- Architektura aplikacji jest zgodna ze wzorcem REST.
- Dane początkowe przesyłane są z wykorzystaniem HTTP PARAMS, a wynikowe zwracane w formacie JSON.
- Espago udostępnia skrypt w JavaScript https://js.espago.com/v1/ W większości przypadków jego użycie jest obowiązkowe. Dzięki wykorzystaniu skryptu formularz płatności jest osadzony wewnątrz Państwa strony w taki sposób, żeby Państwa Klient nie opuszczał w żadnym momencie Państwa strony a dane kart płatniczych omijały Państwa serwer (zrzuca to z Państwa odpowiedzialność za przechowywanie i przetwarzanie danych kart).
- W celu zapewnienia odpowiedniego poziomu bezpieczeństwa wymagane jest na stronie sklepu zastosowanie certyfikatów SSL i wykorzystanie skryptu JS udostępnianego przez Espago.
- Przykładowa płatność jednorazowa:
- Wypełnienie formularza przez klienta i wstępna walidacja parametrów (realizowana przez skrypt JS w przeglądarce klienta)
- Utworzenie tokenu i zwrócenie id_tokenu do webaplikacji sprzedawcy (realizowane przez skrypt JS, token w postaci "cc_xxxxxxxxxx")
- Wysłanie żądania płatności (zapytanie na /api/charges) przez Państwa serwis (przy powołaniu się na token utworzony w przeglądarce użytkownika i przesłany z formularza do Państwa) i odczytanie potwierdzenia/powodu odrzucenia transakcji.
- Informacje widoczne dla klienta:
- Jeżeli w profilu klienta został podany adres e'mail to przy każdej próbie obciążenia karty klienta dostaje on powiadomienie mailowe. Wiadomość zaweira informacje takie jak: nazwa sklepu, kwota i opis płatności. Jest to jedyna sytuacją, w której serwis Espago przekazuje jakąś informację bezpośrednio do klienta.
- Po dokonaniu płatności klient widzi na swoim koncie bankowym informację o płatności składającą się ze skróconej nazwy firmy lub usługi, miasta i kraju firmy, np. "EXAMPLE.COM WARSZAWA PL" - nie ma więc informacji o ID płatności itp.
- Informacje o karcie w składzie: ostatnie 4 cyfry karty, imię i nazwisko posiadacza karty oraz data ważności karty (czyli dane zwracane w potwierdzeniu utworzenia klienta lub płatności) w rozumieniu standardu PCI-DSS (wydanego przez Visę i MasterCard) nie są danymi wrażliwymi, więc sprzedawca ma możliwość ich przechowywania i wyświetlania również klientom. Ze względów wizerunkowych warto rozważyć wyświetlanie tylko części tych informacji, np. tylko ostatnich 4 cyfr karty, oraz umieścić informację, że nie przechowują Państwo kompletu danych kart
- Sprzedawca (Merchant) posiadający kilka serwisów (dla różnych walut i/lub różnych usług) może wykorzystywać utworzone w jednym serwisie tokeny oraz profile klientów w pozostałych swoich serwisach.
- Wszystkie operacje związane z płatnościami realizuje się przy pomocy zapytań API.
-
Kompatybilność i ograniczenia
Udostępnienie API ma na celu nie ograniczanie w żaden sposób technologii wykorzystywanej przez serwisy, w których płatności mają być zintegrowane, a także urządzeń, z których klienci będą dokonywać płatności. Mimo to istnieje ograniczenie kompatybilności:
- Formularz płatości nie działa poprawnie w przeglądarkach Internet Explorer w wersji IE9 i starszych.
- Skrypt JS https://js.espago.com/v1 który musi zostać zaimplementowany w formularzu płatności wykorzystuje zapytanie XMLHttpRequest kierowane do innej niż sprzedawcy domeny (zapytanie do bramki Espago tworzące token), jest to Cross-Origin Resource Sharing, w skrócie CORS. Starsze wersje IE nie zezwalają na takie zapytania.
- Wskazana niekompatybilność dotyczy przeglądarek IE w każdej wersji w Windows XP, więc użytkownikom Windows XP w celu dokonania płatności zaleca się użcie jakiejkolwiek innej przeglądarki.
- Wskazana niekompatybilnośc ma znaczenie np. w przypadku programu pisanego w .NET na system Windows XP, wykorzystującego wbudowaną w system przeglądarkę IE lub imitującego ją w wersji starszej lub równej IE9.
- Formularz płatości nie działa poprawnie w przeglądarkach Internet Explorer w wersji IE9 i starszych.
-
Niezbędne nagłówki żądań
Do poprawnej komunikacji z aplikacją wykorzystywane są następujące nagłówki HTTP:
Nagłówek Obligatoryjność Zawartość Authorization* Wymagany Basic app_id:password Accept Zalecany application/vnd.espago.v2+json - Authorization* z parametrami APP_ID i hasła uzyskanego w sekcji "Czynności początkowe" dotyczy wszystkich zapytań na API z wyjątkiem zapytania o tworzenie tokenu.
- Zapytanie o tworzenie tokenu jest uwierzytelniane przy pomocy Klucza Publicznego i w przypadku większości serwisów jest wykonywane przez skrypt Espago JS.
- Seria nieudanych prób zalogowania skutkuje czasową blokadą konta.
-
Czynności początkowe
Po uzyskaniu dostępu do panelu merchanta należy wykonać następujące czynności:
- Przejść do zakładki
- Przejść do okna edycji serwisu wybierając przycisk
- Uzupełnić pola "Hasło API" i "Potwierdzenie hasła API" - wpisana wartość odpowiada za prawidłową autoryzację Państwa konta i nie może być ujawniana osobom postronnym.
- Zaakceptować zmiany klikając
- Należy zwrócić uwagę na uzyskane ID Aplikacji w tabeli głównej zakładki Serwisy.
- Przejść do szczegółowych informacji o serwisie klikając na jego nazwę. Pole "Klucz publiczny" jest wymagane do generowania tokenów.
- Przejść do zakładki
-
-
Karty płatnicze
Płatności kartami w systemie Espago obsługuje Elavon. Jest to domyślny kanał płatności w naszym systemie. Chcąc zintegrować kanał płatności kartami, obsługiwany przez Elavon, należy zaimplementować wszystkie poniższe funkcjonalności tego kanału.
Podczas testowania kart płatniczych obowiązują następujące reguły:
- Zabronione jest używanie rzeczywistych numerów kart. Dozwolone jest korzystanie jedynie z numerów testowych, np.'4242424242424242'
- Należy podawać jako datę wygaśnięcia karty dowolną datę z przyszłości. Od wyboru miesąca zależy otrzymany rezultat transakcji. Dzięki temu można testować zarówno scenariusze negatywne jak i pozytywne.
Wybór miesiąca ważności karty skutkuje:
a). 01-05 - transakcja zaakceptowana
b). 06 - wynik losowy, 50% szans powodzenia transakcji
c). 07-12 - transakcja odrzucona, dla każdego miesiąca inna przyczyna odrzucenia - Kod CVV/CVC w bramce testowej jest ignorowany.
-
Możliwe stany płatności
Stan Opis new Nowa płatność jeszcze nie obciążająca klienta executed Płatność wykonana, konto klienta obciążone. Uwaga: Po wykonaniu transakcji wciąż można zwrócić pobraną wcześniej kwotę (lub pewną jej część).rejected Płatność odrzucona. Uwaga: Jeżeli nastąpi ten stan płatności, to w odpowiedzi dostaniemy dodatkowo parametr reject_reason oraz issuer_response_codefailed Płatność zakończona niepowodzeniem ze względu na czynniki zewnętrzne -
Możliwe przyczyny odrzuceń płatności
Informacje ogólne - parametr "reject_reason"
Komunikat Znaczenie Przyczyna Uwagi declined transakcja odrzucona Nieaktywowany rodzaj usługi (MOTO, ecommerce), również brak środków card expired karta utraciła ważność Przekroczony termin ważności karty invalid amount niewłaściwa kwota Ma to związek z limitem kwotowym/liczby płatności invalid card nieprawidłowa karta invalid profile nieprawidłowe konto MID Odrzucenie przez Elavon, np. ze względu na niekatywny MID Komunikat występuje wraz z kodem issuer_response_code=00 referral A / pick up card karta do zatrzymania Karta oznaczona jako zablokowana/zagubiona/skradziona. UWAGA: Nie należy powtarzać obciążeń dla tej karty! Może to zostać uznane za próbę oszustwa! referral B transakcja wymaga potwierdzenia wymaga kontaktu z bankiem dla potwierdzenia transakcji, transakcja jest od traktowana jako odrzucona w systemie Espago serv not allowed nieobsługiwany typ karty Merchant nie obsługuje danego typu karty np. American Express, Diners Club, w przypadku braku rejestracji BRAM także MasterCard Szczegółowe informacje - parametr "issuer_response_code"
Kod błędu Znaczenie Proponowany komunikat 00 Zaakceptowane obciążenie Transakcja zaakceptowana. Dziękujemy! Blokada odpowiedzi na poziomie Elavon (niezbędny kontakt z Espago/Elavon) ODMOWA - wystąpił nieoczekiwany błąd. Prosimy spróbować ponownie później. 01,02 Wymagana autoryzacja głosowa ODMOWA - problem z autoryzacją. Niezbędny kontakt z bankiem. 03 Nieprawidłowe/niepełne dane akceptanta ODMOWA - problem z autoryzacją. Podano nieprawidłowe dane karty. Spróbuj ponownie. 04,07 Karta zastrzeżona (z powodów innych niż kradzież/zgubienie) ODMOWA - karta zastrzeżona. Skontaktuj się z Twoim bankiem w celu wyjaśnienia przyczyny problemu. UWAGA: Nie należy powtarzać obciążeń dla tej karty! Może to zostać uznane za próbę oszustwa! 05,13,57,61 Nieaktywowane płatności typu MOTO/eCommerce lub przekroczenie limitu ODMOWA – Sprawdź, czy dla Twojej karty dostępna jest usługa płatności internetowych lub MOTO, zweryfikuj ustawienia limitów dla takich transakcji lub skontaktuj się z Twoim bankiem (wystawcą karty) w celu wyjaśnienia przyczyny odmowy. 12 Nieprawidłowa transakcja ODMOWA - transakcja niedostępna dla tej karty. Skontaktuj się z Twoim bankiem w celu wyjaśnienia przyczyny problemu 14 Nieprawidłowy numer karty ODMOWA - podano nieprawidłowy numer karty. Sprawdź dane i spróbuj ponownie. 30 Błędny format danych wiadomości autoryzacyjnej ODMOWA - skontaktuj się z Twoim bankiem w celu wyjaśnienia przyczyny problemu 41 Karta oznaczona jako zgubiona ODMOWA - karta oznaczona jako zgubiona – skontaktuj się z Twoim bankiem w celu wyjaśnienia przyczyny problemu. UWAGA: Nie należy powtarzać obciążeń dla tej karty! Może to zostać uznane za próbę oszustwa! 43 Karta oznaczona jako skradziona ODMOWA - karta oznaczona jako skradziona – skontaktuj się z Twoim bankiem w celu wyjaśnienia przyczyny problemu. UWAGA: Nie należy powtarzać obciążeń dla tej karty! Może to zostać uznane za próbę oszustwa! 51 Niewystarczające środki na koncie ODMOWA - niewystarczające środki na koncie. Zweryfikuj stan swojego konta i spróbuj ponownie. 54 Przeterminowana karta ODMOWA - karta utraciła ważność. Skontaktuj się z bankiem celem wyjaśnienia przyczyny lub użyj innej karty. 59 Podejrzenie oszustwa ODMOWA - skontaktuj się z Twoim bankiem w celu wyjaśnienia przyczyny problemu 62 Ograniczenie karty, wykluczenie karty ze względu na kraj wydawcy. ODMOWA – użycie karty zostało ograniczone, np. ze względu na ograniczenie (embargo) nałożone na kraj wydawcy (banku). Skontaktuj się z bankiem w celu wyjaśnienia szczegółowej przyczyny problemu. 65 Przekroczony limit liczby użyć ODMOWA – przekroczony dzienny limit liczby transakcji dla tej karty. Dokonaj zmiany ustawień dziennych limitów lub spróbuj ponownie później. 75 Przekroczony limit błędnych prób podania CVV/CVC/PIN. ODMOWA – przekroczony limit błędnych prób podania kodu PIN/CVC/CVV. Zweryfikuj poprawność kodu zabezpieczającego na swojej karcie. 78 Nowa, nieaktywowana karta ODMOWA – Karta nie została aktywowana. Aktywuj kartę i spróbuj ponownie. 82, N7 Nieprawidłowy kod CVV ODMOWA – Nieprawidłowy kod CVV. Sprawdź poprawność wprowadzonych danych i spróbuj ponownie. -
Sposoby przekazywania danych karty w obciążeniu
Dane karty w zapytaniu tworzącym nowe obciążenie można przekazać na trzy różne sposoby. W poniższej tabelce zostały przedstawione wszystkie trzy możliwości.
Możliwość Parametry Opis parametrów Uwagi obiekt klient client Do parametru client przypisuje się ID klienta utworzonego wcześniej w systemie Espago. Klient taki musi mieć uzupełnione dane karty. Szczegółowe informacje w dziale Klient token card Parametrowi card przypisuje się ID tokenu, który został utworzony z podanych danych karty. Token jest tworzony przez fomularz JS, który jest dokładnie opisany w dziale Tokeny Tak utworzony token może zostać wykorzystany tylko jeden raz. Szczegółowe informacje w dziale Tokeny dane karty ** card[first_name] Imię posiadacza karty W zapytaniu wysyłanym do bramki Espago, zostają podane wszystkie niezbędne dane karty jako osobne parametry. card[last_name] Nazwisko posiadacza karty card[number] Numer karty card[year] Rok ważności karty card[month] Miesiąc ważności karty card[verification_value] Kod CVV karty ** Ze względów bezpieczeństwa przesyłanie kompletu danych kart w zapytaniu na /api/charges nie jest dozwolone za wyjątkiem środowiska testowego oraz indywidualnie rozpatrywanych przypadków w środowisku produkcyjnym. Poprawnym rozwiązaniem jest przesyłanie ID tokenu lub użycie ID klienta posiadającego dane karty przypisane wcześniej za pomocą tokenu.
-
Nowe obciążenie
Utworzenie nowego obciążenia następuje w wyniku wysłania żądania typu POST na adres https://sandbox.espago.com/api/charges Transakcję należy przeprowadzić wykorzystując jeden w powyższych sposobów przekazywania danych karty dołączając stosowne parametry.
Dostępne parametry HTTP
Parametr Opis Uwagi client ID klienta ID klienta w przypadku obciążenia istniejącego klienta
lub ID tokenu w przypadku płatności jednorazowej.
card ID tokenu amount Kwota transakcji Liczba dziesiętna, np. 123.45 currency Waluta Trzyliterowy symbol waluty zgodny z posiadanym MID description Opis transakcji Musi składać się z 5 do 99 znaków. Przykład z wykorzystaniem CURL
Kod wykorzystujący funkcjonalność obiektów klienta
curl -i https://sandbox.espago.com/api/charges -u app_id:password -d "amount=49.99" -d "currency=pln" -d "client=client_id" -d "description=Opis transakcji"Przykładowa odpowiedź
{ "id":"pay_q8v53GIhU4SsaI", "description":"Opis transakcji", "channel":"elavon", "amount":"49.99", "currency":"pln", "state":"executed", "client":"cli_UrxPVeAjYh3l3C", "created_at":1381821183, "card":{ "company":"VI", "last4":"4242", "year":2017, "month":1, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "created_at":1380540122 }, "issuer_response_code":"00", "reversable":true, "transaction_id":"tn_Wz8iuo426" }Uwaga!
Jest możliwa obsługa płatności MO/TO przez naszą bramkę. Wystarczy dodać do wysyłanego żądania nowego obciążenia parametr moto. Parametr ten domyślnie przyjmuje wartość false, wtedy obciążenia są traktowane jako zwykłe. Gdy parametr moto przyjmuje wartość true, aktywowana jest usługa MO/TO na tym obciążeniu. -
Zarezerwowanie środków przyszłego obciążenia na koncie klienta
Możliwe jest zarezerwowanie środków przyszłego obciążenia karty klienta. Preautoryzacja odbywa się za pomocą wysłania żądania typu POST na adres https://sandbox.espago.com/api/charges
Wysyłane w żądaniu parametry obciążenia są takie same jak w przypadku tworzenia nowego obciążenia (opisane powyżej), z jednym dodatkowym parametrem, który określa to żądanie jako zarezerowowanie środków. Jest to parametr complete, domyślnie przyjmuje on wartość true - wtedy żądanie traktowane jest jako zwykłe obciążenie. Gdy parametr complete przyjmuje wartość false, oznacza to zarezerwowanie środków na karcie klienta dla przyszłego obciążenia.
Uwaga!
Maksymalny okres zablokowania konkretnej kwoty na karcie klienta jest zdefiniowany w regulaminie instytucji wydającej kartę. Ten okres zależy więc wydawcy karty. Zwykle jest to czas nie dłuższy niż tydzień.Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/charges -u app_id:password -d "client=client_id" -d "amount=49.99" -d "currency=pln" -d "description=Opis transakcji" -d "complete=false"Przykładowa odpowiedź
{ "id":"pay_A3snPPD7YI9Bb1", "description":"Opis transakcji", "channel":"elavon", "amount":"49.99", "currency":"pln", "state":"preauthorized", "client":"cli_xNKNXh-_kWu6Qi", "created_at":1381821534, "card":{ "company":"VI", "last4":"4242", "year":2017, "month":2, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "created_at":1381755890 }, "issuer_response_code":"00", "completed":false, "reversable":true, "transaction_id":"tn_prd4lSJss" } -
Obciążenie zarezerwowanych środków na karcie klienta
Aby obciążyć zarezerwowane wcześniej środki na karcie klienta należy wysłać żądanie typu POST na adres https://sandbox.espago.com/api/charges/(:id)/complete
(:id) - identyfikator preautoryzowanych środków na karcie, które mają być teraz obciążone
Uwaga!
Żądanie może zawierać kwotę obciążenia. Jeżeli nie zostanie podana kwota obciążenia, zostaje ono wykonane dokładnie na kwotę zarezerwowanych środków. Można obciążyć kartę klienta kwotą większą od 0 do 115 % zarezerwowanych wcześniej środków.Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/charges/(:id)/complete -u app_id:password -d "amount=35" -X POSTPrzykładowa odpowiedź
{ "id":"pay_JETtzgkvPtHmos", "description":"Opis transakcji", "channel":"elavon", "amount":"35.00", "currency":"pln", "state":"executed", "client":"cli_xNKNXh-_kWu6Qi", "created_at":1381822240, "card":{ "company":"VI", "last4":"4242", "year":2017, "month":2, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "created_at":1381755890 }, "issuer_response_code":"00", "reversable":true } -
Pobranie danych istniejącego obciążenia
Pobranie danych utworzonego wcześniej obciążenia następuje w wyniku wysłania żądania typu GET na adres https://sandbox.espago.com/api/charges/(:id)
(:id) - identyfikator obciążenia, którego dane chcą Państwo pobrać
Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/charges/charge_id -u app_id:passwordPrzykładowa odpowiedź
{ "id":"pay_q8v53GIhU4SsaI", "description":"Opis transakcji", "channel":"elavon", "amount":"49.99", "currency":"pln", "state":"executed", "client":"cli_UrxPVeAjYh3l3C", "created_at":1381821183, "card":{ "company":"VI", "last4":"4242", "year":2017, "month":1, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "created_at":1380540122 }, "issuer_response_code":"00", "reversable":true, "transaction_id":"tn_Wz8iuo426" } -
Wyświetlanie grup obciążeń
Wyświetlanie określonej strony z określoną liczną obciążeń na stronę następuje w wyniku wysłania żądania typu GET na adres https://sandbox.espago.com/api/charges?page=1&per=10&client=client_id
Dostępne parametry HTTP
Parametr Opis Obligatoryjność Wartość domyślna page Numer strony Opcjonalny 1 (pierwsza strona) per Liczba obciążeń na każdej stronie Opcjonalny 25 (25 obciążeń) client ID klienta, którego mają dotyczyć transakcje Opcjonalny wszyscy klienci Przykład z wykorzystaniem CURL (bez parametrów dodatkowych)
curl -i https://sandbox.espago.com/api/charges -u app_id:passwordPrzykład z wykorzystaniem CURL i dodatkowych parametrów
curl -i https://sandbox.espago.com/api/charges -u app_id:password -d "page=1" -d "per=5" -d "client=client_id" -X GETPrzykładowa odpowiedź
{ "count":5, "charges":[ { "id":"pay_O_hgcNdZn16OO3", "description":"Opis transakcji", "channel":"elavon", "amount":"49.99", "currency":"pln", "state":"preauthorized", "client":"cli_UrxPVeAjYh3l3C", "created_at":1381821339, "card":{ "company":"VI", "last4":"4242", "year":2017, "month":1, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "issuer_response_code":"00", "created_at":1380540122 }, "issuer_response_code":"00", "completed":false, "reversable":true, "transaction_id":"tn_b8pIy3S1T" },{ "id":"pay_q8v53GIhU4SsaI", "description":"Opis transakcji", "channel":"elavon", "amount":"49.99", "currency":"pln", "state":"executed", "client":"cli_UrxPVeAjYh3l3C", "created_at":1381821183, "card":{ "company":"VI", "last4":"4242", "year":2017, "month":1, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "issuer_response_code":"00", "created_at":1380540122 }, "issuer_response_code":"00", "invoice":"in_askKJSKKn880-j", "subscription":"sub_jqWaPgj1vgRa4k", "transaction_id":"tn_Wz8iuo426" } ] }Uwaga!
Parametr count w odpowiedzi informuje o całkowitej liczbie uzyskanych wyników zapytania. Listy parametrów mogą się różnić w poszczególnych płatnościach: płatności przed rozliczeniem posiadają dodatkowy parametr "reversable", płatności dokonane w ramach subskrypcji posiadają parametry "invoice" oraz "subscription". -
Wycofywanie istniejącej płatności przed rozliczeniem
Usunięcie istniejącej płatności przed jej całkowitym rozliczeniem następuje w wyniku wysłania żądania typu DELETE na adres https://sandbox.espago.com/api/charges/(:id)
(:id) - identyfikator płatności, którą chcą Państwo usunąć
Uwaga!
Wycofanie płatności może odbyć się jedynie przed jej rozliczeniem i każdorazowo dotyczy całej kwoty transakcji. W przypadku środowiska testowego płatności rozliczane są co godzinę, a produkcyjnego co 24 godziny, po czym możliwy jest jedynie ich zwrot (refund).Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/charges/charge_id -u app_id:password -X DELETEPrzykładowa odpowiedź
{ "id":"pay_ydJqgP2w7KZMvM", "description":"Opis transakcji", "channel":"elavon", "amount":"49.99", "currency":"pln", "state":"reversed", "client":"cli_xNKNXh-_kWu6Qi", "created_at":1381823580, "card":{ "company":"VI", "last4":"4242", "year":2017, "month":2, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "created_at":1381755890 }, "issuer_response_code":"00", "transaction_id":"tn_AKZ71ysMF" } -
Zwrot istniejącej płatności po rozliczeniu
Zwrot pieniędzy za transakcję, która została już rozliczona następuje w wyniku wysłania żądania typu POST na podany adres https://sandbox.espago.com/api/charges/(:id)/refund
(:id) - identyfikator płatności, która ma zostać wycofana i zwrócona
Dostępne parametry HTTP
Parametr Opis Obligatoryjność Wartość domyślna amount kwota, która ma zostać zwrócona Opcjonalny Kwota ta musi być mniejsza bądź równa kwocie transakcji. Jeżeli nie zostanie określona w wysyłanym żądaniu, zwrócona zostanie cała kwota transakcji. Przykład z wykorzystaniem CURL - bez parametrów HTTP
curl -i https://sandbox.espago.com/api/charges/(:id)/refund -u app_id:password -X POSTPrzykład z wykorzystaniem CURL - z parametrami HTTP
curl -i https://sandbox.espago.com/api/charges/(:id)/refund -u app_id:password -d "amount=n" -X POSTPrzykładowa odpowiedź
{ "id":"pay_COy6zH9fLj1d7K", "description":"Opis transakcji", "channel":"elavon", "amount":"49.99", "currency":"pln", "state":"refunded", "client":"cli_xNKNXh-_kWu6Qi", "created_at":1381823580, "card":{ "company":"VI", "last4":"4242", "year":2017, "month":2, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "created_at":1381755890 }, "issuer_response_code":"00", "transaction_id":"tn_AKZ71ysMF" }
-
Płatności cykliczne
Płatności cykliczne są sposobem obciążania klienta w sposób automatyczny z określoną częstotliwością obciążeń. W systemie Espago płatności cykliczne składają się z dwóch głównych elementów, są nimi: plany i subskrypcje. Aby wykorzystywać płatności cykliczne trzeba również utworzyć w systemie Espago obiekt klienta z przypisanymi danymi karty kredytowej - to na podstawie numeru ID klienta, przypisuje się go do określonej subskrypcji.
Schemat działania płatności cyklicznych w systemie Espago jest bardzo prosty. Początkowo należy zdefiniować plan, w którym określa się częstotliwość z jaką klient ma być obciążany oraz kwotę obciążenia. Aby uruchomić naliczanie cykliczne należy utworzyć nową subskrypcję, powołując się na ID klienta oraz ID planu.
-
Konfiguracja
Po uzyskaniu dostępu do panelu merchanta należy wykonać następujące czynności:
- Przejść do zakładki
- Przejść do okna edycji serwisu wybierając przycisk
- Należy ustawić adres url żądania zwrotnego (dotyczy to kolejnych obciążeń subskrypcji):
url żądania zwrotnego - definiuje adres, na który wysyłana jest asynchronicznie informacja po uzyskaniu przez bramkę statusu kolejnej płatności
-
Dla bezpieczeństwa warto skonfigurować po stronie Sprzedawcy konieczność autoryzacji informacji zwrotnych z bramki Espago i skonfigurować nagłówki autoryzacyjne żądań zwrotnych poprzez edycję pól:
Login BasicAuth (dla URL żądania zwrotnego) - definiuje nazwę użytkownika umieszczoną w nagłówkach żądań zwrotnych
Hasło BasicAuth (dla URL żądania zwrotnego) - definiuje hasło umieszczone w nagłówkach żądań zwrotnych
Witryna umieszczona pod adresem żądania zwrotnego musi blokować żądania nie autoryzowane przy pomocy danych ustalonych powyżej.
-
Uzupełnić czasy powtarzania próby obciążenia nieudanych transakcji oraz określić status na wypadek wykorzystania limitów ponowień. W środowisku produkcyjnym możliwymi wartościami są: 1,2,3,4 dni, w środowisku testowym dostępne są krótsze czasy (np. liczone w minutach).
Możliwe stany po wyczerpaniu limitów ponownych obciążeń:
Stan Opis Zatrzymaj subskrypcję Wyłącza subskrypcję uniemożliwiając generowanie kolejnych obciążeń według cyklu ustalonego w szczegółach planu. Status subskrypcji zmieni się na "inactive". Nic nie rób Mimo braku pozytywnego wyniku danego obciążenia generowane będą kolejne, zgodnie z planem.
- Przejść do zakładki
-
Plany
Plany są elementem płatności cyklicznych, które definiują wszystkie istotnie informacje o tej płatności.Tworząc plan ustala się takie dane jak: typ okresu obciążenia (np. day, month), wartość okresu obciążenia (w przypadku typu okresu period=day oraz period_unit=7 uzyskujemy cykliczność obciążania co 7 dni) oraz kwota pojedyńczego obciążenia. Wszystkie te parametry warunkują powstanie prawidłowego planu. Wszelkie dotyczące tworzenia planów znajdują się w poniższych podrozdziałach.
-
Tworzenie nowego planu
Utworzenie nowego planu następuje w wyniku wysłania żądania typu POST na adres https://sandbox.espago.com/api/plans umieszczając stosowne parametry.
Dostępne parametry HTTP
Parametr Opis Uwagi period_unit Jednostka okresu Określa jednostkę, w której następuje rozliczenie, np: day, week, month. period Wartość okresu Liczba całkowita. Wspólnie z parametrem period decyduje o częstotliwości obciążeń. amount Kwota transakcji Liczba dziesiętna, np. 123.45 currency Waluta Symbol waluty zgodny z posiadanym MID description Opis planu Powinien składać się z co najmniej 5 znaków. Należy zauważyć, że istotne jest określenie parametrów "period" i "period_unit", gdyż ich sumaryczne wartości odpowiadają za rzeczywistą częstotliwość obciążeń. Oto dopuszczalne wartości dla powyższych konfiguracji:
Wartość parametru "period_unit" Dopuszczalne wartości parametru "period" Uzyskany rezultat day 1-366 Plan obciążający konto klienta co zadaną liczbę dni month 1-12 Plan obciążający konto klienta co zadaną liczbę miesięcy Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/plans -u app_id:password -d "description=opis planu" -d "period_unit=month" -d "period=1" -d "amount=55" -d "currency=pln"Przykładowa odpowiedź
{ "id":"pl_qtIxVOMg6m076CM", "description":"abonament", "period_unit":"month", "period":1, "amount":"55.0", "currency":"pln", "created_at":1366969540 } -
Pobieranie danych planu
Pobranie danych utworzonego wcześniej planu następuje w wyniku wysłania żądania typu GET na adres https://sandbox.espago.com/api/plans/(:id)
(:id) - identyfikator planu, którego dane chcą Państwo pobrać
Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/plans/(:id) -u app_id:passwordPrzykładowa odpowiedź
{ "id":"pl_qtIxVOMg6m076CM", "description":"abonament", "period_unit":"month", "period":1, "amount":"55.0", "currency":"pln", "created_at":1366969540 } -
Usuwanie planów
Celem usunięcia stworzonego wcześniej planu należy wysłać żądanie metodą DELETE na adres https://sandbox.espago.com/api/plans/(:id)
(:id) - identyfikator planu, którego dane chcą Państwo usunąć
Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/plans/(:id) -u app_id:password -X DELETEOdpowiedź
W odpowiedzi wysyłamy status 204 "No content".
-
Aktualizacja parametrów istniejącego planu
By dokonać zmiany ustawień planu należy wysłać żądanie metodą PUT na adres: https://sandbox.espago.com/api/plans/(:id)
(:id) - identyfikator modyfikowanego planu
Uwaga!
Modyfikacje planu nie dotyczą już istniejących subskrypcji - zmiany obejmą jedynie te utworzone po wysłaniu powyższego requestu!Dostępne parametry HTTP
Parametr Opis Uwagi period_unit Jednostka okresu Określa jednostkę, w którym następuje rozliczenie, np: day, week, month. period Wartość okresu Liczba całkowita. Wspólnie z parametrem period decyduje o częstotliwości obciążeń. amount Kwota transakcji Liczba dziesiętna, np. 123.45 currency Waluta Symbol waluty zgodny z posiadanym MID description Opis planu Powinien składać się z co najmniej 5 znaków. Dopuszczalne wartości dla różnych konfiguracji cyklu:
Wartość parametru "period_unit" Dopuszczalne wartości parametru "period" Uzyskany rezultat day 1-366 Plan obciążający konto klienta co zadaną liczbę dni month 1-12 Plan obciążający konto klienta co zadaną liczbę miesięcy Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/plans/(:id) -u app_id:password -d "description=opis planu" -d "period_unit=month" -d "period=1" -d "amount=55" -d "currency=pln" -X PUTOdpowiedź
W odpowiedzi wysyłamy status 204 "No content".
-
Wyświetlanie listy planów
Pobieranie listy dostępnych planów następuje w wyniku wysłania żądania metodą GET na adres: https://sandbox.espago.com/api/plans
Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/plans -u app_id:passwordPrzykładowa odpowiedź
{ "count":2, "plans":[ { "id":"pl_W0pMAR48jjdLzoO", "description":"abonament", "period_unit":"month", "period":1, "amount":"55.0", "currency":"pln", "created_at":1366970077 },{ "id":"pl_SsYnQX-42jzW2GG", "description":"abonament mini", "period_unit":"month", "period":1, "amount":"45.0", "currency":"pln", "created_at":1366970093 }] }
-
-
Subskrypcje
Subskrypcje (abonamenty) są elementami płatności cyklicznych, które przypisują plan płatności cyklicznej do klienta.
Subskrypcja działa od momentu jej uruchomienia (generowana jest wtedy pierwsza płatność) do momentu wyłączenia jej przez Sprzedawcę lub do nieudanego obciążenia (powtarzanego trzykrotnie lub nie powtarzanego i jeżeli zatrzymanie subskrypcji w takiej sytuacji zostało skonfigurowane w panelu www).
-
Tworzenie nowej subskrypcji
Utworzenie nowej subskrypcji następuje w wyniku wysłania żądania typu POST na adres https://sandbox.espago.com/api/subscriptions i wybrania klienta oraz właściwego planu.
Dostępne parametry HTTP
Parametr Opis Obligatoryjność client ID klienta Wymagany plan ID planu Wymagany Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/subscriptions -u app_id:password -d "client=(:client_id)" -d "plan=(:plan_id)"Przykładowa odpowiedź
W odpowiedzi poza informacją dotyczącą subskrypcji wysyłamy także dane 1. obciążenia (last_invoice).
{ "id":"sub_i3CoQEnqX5IKve", "state":"active", "client":"cli_buoBpPrw6rU7iC", "plan":"pl_vGTGxa_Kf521Sdv", "created_at":1373461486, "last_invoice": { "id":"in_MVt4vwsp7VvOTqa", "date":1373461485, "client":"cli_buoBpPrw6rU7iC", "subscription":"sub_i3CoQEnqX5IKve", "amount":"7.00", "currency":"PLN", "paid":true, "issuer_response_code":"00", "attempts":1, "next_payment_attempt":null, "created_at":1373461485 } }Uwaga!
Jeżeli pierwsza płatność wykonywana przy tworzeniu subskrypcji się nie powiedzie to subskrypcja od razu wygasa - jest to zabezpieczenie przeciwko tworzeniu subskrypcji przy użyciu karty, która np. nie obsługuje transakcji internetowych/MOTO. W takim przypadku w odpowiedzi na zapytanie tworzące subskrypcję (/api/subscriptions) obok id subskrypcji będzie informacja że jest nieaktywna: "state":"inactive".Kolejne odpowiedzi
Poza utworzoną subskrypcją nastąpi utworzenie 1. faktury, która jest właściwą informacją o stanie transakcji. Informacje o kolejnych obciążeniach przychodzą w formie asynchronicznych back requestów na adres żądania zwrotnego (więcej informacji w dziale Konfiguracja) i są generowane są w momencie utworzenia nowej lub próby obciążenia już istniejącej. Przykładowy back request (więcej informacji w dziale Faktury):
{ "id":"in_hS-KiS3N6YCzOhG", "date":1371631155, "client":"cli_OU7k00vEMGi53C", "subscription":"sub_QyJzN4KdzNzvmZ", "amount":"7.00", "currency":"PLN", "paid":true, "attempts":1, "next_payment_attempt":null, "created_at":1371500155 }Back requesty są wysyłane do momentu otrzymania z aplikacji kodu 200 'Ok' maksymalnie przez 24h z rosnącym interwałem.
-
Pobieranie danych subskrypcji
Pobranie danych utworzonej wcześniej subskrypcji następuje w wyniku wysłania żądania typu GET na adres https://sandbox.espago.com/api/subscriptions/(:id)
(:id) - identyfikator subskrypcji, której dane chcą Państwo pobrać
Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/subscriptions/(:id) -u app_id:passwordPrzykładowa odpowiedź
{ "id":"sub_i3CoQEnqX5IKve", "state":"active", "client":"cli_buoBpPrw6rU7iC", "plan":"pl_vGTGxa_Kf521Sdv", "created_at":1373461486, "last_invoice": { "id":"in_MVt4vwsp7VvOTqa", "date":1373461485, "client":"cli_buoBpPrw6rU7iC", "subscription":"sub_i3CoQEnqX5IKve", "amount":"7.00", "currency":"PLN", "paid":true, "issuer_response_code":"00", "attempts":1, "next_payment_attempt":null, "created_at":1373461485 } } -
Zatrzymywanie subskrypcji
Zatrzymanie istniejącej subskrypcji następuje w wyniku wysłania żądania typu DELETE na adres https://sandbox.espago.com/api/subscriptions/(:id)
(:id) - identyfikator subskrypcji, której dane chcą Państwo usunąć
Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/subscriptions/(:id) -u app_id:password -X DELETEOdpowiedź
Status uzyskany w odpowiedzi to 204 "No content".
-
Wyświetlanie listy aktywnych subskrypcji
Pobieranie listy aktywnych subskrypcji następuje w wyniku wysłania żądania metodą GET na adres: https://sandbox.espago.com/api/subscriptions
Dostępne parametry HTTP
Parametr Opis Obligatoryjność Wartość domyślna page Numer strony Opcjonalny 1 (pierwsza strona) per Liczba subskrypcji na każdej stronie Opcjonalny 25 (25 subskrypcji) Przykład z wykorzystaniem CURL (bez parametrów dodatkowych)
curl -i https://sandbox.espago.com/api/subscriptions -u app_id:passwordPrzykład z wykorzystaniem CURL i parametrów dodatkowych
curl -i https://sandbox.espago.com/api/subscriptions -u app_id:password -d "page=2" -d "per=5"Przykładowa odpowiedź
{ "count":1, "subscriptions": [{ "id":"sub_i3CoQEnqX5IKve", "state":"active", "client":"cli_buoBpPrw6rU7iC", "plan":"pl_vGTGxa_Kf521Sdv", "created_at":1373461486, "last_invoice": { "id":"in_9d7xIbhzLMkxTFm", "date":1373463196, "client":"cli_buoBpPrw6rU7iC", "subscription":"sub_i3CoQEnqX5IKve", "amount":"7.00", "currency":"PLN", "paid":true, "issuer_response_code":"00", "attempts":1, "next_payment_attempt":null, "created_at":1373463196 } }] } -
Wyświetlanie listy aktywnych subskrypcji klienta
Pobieranie listy aktywnych subskrypcji przypisanych do danego klienta następuje w wyniku wysłania żądania metodą GET na adres: https://sandbox.espago.com/api/clients/(:client_id)/subscriptions
(:client_id) - identyfikator klienta, którego dane subskrypcji chcą Państwo pobrać
Dostępne parametry HTTP
Parametr Opis Obligatoryjność Wartość domyślna page Numer strony Opcjonalny 1 (pierwsza strona) per Liczba subskrypcji na każdej stronie Opcjonalny 25 (25 subskrypcji) Przykład z wykorzystaniem CURL (bez parametrów dodatkowych)
curl -i https://sandbox.espago.com/api/clients/(:client_id)/subscriptions -u app_id:passwordPrzykład z wykorzystaniem CURL i parametrów dodatkowych
curl -i https://sandbox.espago.com/api/clients/(:client_id)/subscriptions -u app_id:password -d "page=2" -d "per=5"Przykładowa odpowiedź
{ "count":2, "subscriptions": [{ "id":"sub_WbAUbaC_7KB79V", "state":"active", "client":"cli_buoBpPrw6rU7iC", "plan":"pl_vGTGxa_Kf521Sdv", "created_at":1373463500, "last_invoice": { "id":"in_I3iEPUZFxUsLUR-", "date":1373463498, "client":"cli_buoBpPrw6rU7iC", "subscription":"sub_WbAUbaC_7KB79V", "amount":"7.00", "currency":"PLN", "paid":true, "issuer_response_code":"00", "attempts":1, "next_payment_attempt":null, "created_at":1373463498 } },{ "id":"sub_FMw5DlPzK0dW9V", "state":"active", "client":"cli_buoBpPrw6rU7iC", "plan":"pl_vGTGxa_Kf521Sdv", "created_at":1373463506, "last_invoice": { "id":"in_WtlQMDFdUDpIdSq", "date":1373463504, "client":"cli_buoBpPrw6rU7iC", "subscription":"sub_FMw5DlPzK0dW9V", "amount":"7.00", "currency":"PLN", "paid":true, "issuer_response_code":"00", "attempts":1, "next_payment_attempt":null, "created_at":1373463504 } }] }
-
-
Faktury
Faktura to obiekt systemowy związany z płatnością cykliczną i odpowiedzialny za przechowywanie stanu transakcji, liczbę dotychczasowych prób obciążeń oraz ewentualną datę kolejnej płatności na wypadek niepowodzenia ostatniej.
-
Wyświetlanie danych pojedynczej faktury
Wyświetlenie danych faktury jest możliwe po wysłaniu żądania typu GET na adres: https://sandbox.espago.com/api/invoices/(:id)
(:id) - identyfikator faktury
Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/invoices/(:id) -u app_id:passwordPrzykładowa odpowiedź
{ "id":"in_hS-KiS3N6YCzOhG", "date":1371631155, "client":"cli_OU7k00vEMGi53C", "subscription":"sub_QyJzN4KdzNzvmZ", "amount":"7.00", "currency":"PLN", "paid":true, "attempts":1, "next_payment_attempt":null, "created_at":1371500155 }Znaczenie dodatkowych pól:
Nazwa pola Znaczenie Dostępne wartości Date Informacja o zleconej dacie obciążenia Data w formacie Unix time Paid Informacja, czy faktura została opłacona 'True' lub 'false' Attempts Liczba wykonanych prób zapłaty Wartość liczbowa Next payment attempt Data wykonania kolejnej próby w przypadku negatywnej ostatniej odpowiedzi Data w formacie Unix time lub 'null' w przypadku braku konieczności ponawiania -
Wyświetlanie listy faktur
Wyświetlenie listy faktur jest możliwe po wysłaniu żądania typu GET na adres: https://sandbox.espago.com/api/invoices/
Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/invoices/ -u app_id:passwordPrzykładowa odpowiedź
{ "count":2, "invoices": [{ "id":"in_884v5aOAcpTafgd", "date":1371474803, "client":"cli_6kYipMfvoT22KO", "subscription":"sub_UiUoPnq8nSDBYb", "amount":"55.00", "currency":"pln", "paid":false, "attempts":1, "next_payment_attempt":null, "created_at":1371474803 },{ "id":"in_95ev7TLiy_pupjd", "date":1371474813, "client":"cli_6kYipMfvoT22KO", "subscription":"sub_3NrkDVtuz1ybui", "amount":"55.00", "currency":"pln", "paid":false, "attempts":1, "next_payment_attempt":null, "created_at":1371474813 }] } -
Wyświetlanie listy faktur klienta
Wyświetlenie danych faktury danego klienta jest możliwe po wysłaniu żądania typu GET na adres: https://sandbox.espago.com/api/clients/(:client_id)/invoices
(:client_id) - identyfikator klienta
Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/clients/(:client_id)/invoices -u app_id:passwordPrzykładowa odpowiedź
{ "count":1, "invoices": [{ "id":"in_SFRveiSmG4aorkU", "date":1372056035, "client":"cli_cl75lXjKt2kQ6u", "subscription":"sub_wYl0egJryOS7Jg", "amount":"7.00", "currency":"PLN", "paid":true, "attempts":1, "next_payment_attempt":null, "created_at":1372056035 }] } -
Ręczne wymuszenie próby opłacenia faktury
Istnieje możliwość wykonania dodatkowych prób pobrania płatności (poza limitem przewidzianym przez konfigurację). W tym celu należy wysłać request typu POST na adres: https://sandbox.espago.com/api/invoices/(:invoice_id)/pay
(:invoice_id) - identyfikator faktury
Uwaga!
Wykonanie tego polecenia będzie skutkować zmniejszeniem liczby dodatkowych prób obciążeń wykonywanych automatycznie przez system!Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/invoices/(:invoice_id)/pay -u app_id:password -X POSTPrzykładowa odpowiedź
Dla nieopłaconej faktury:
{ "id":"in_MUL7PeIUTDwOHx8", "date":1371805245, "client":"cli_N7hldWZqSoBLva", "subscription":"sub_occMPm6-_284b3", "amount":"7.00", "currency":"PLN", "paid":true, "attempts":2, "next_payment_attempt":null, "created_at":1371805245 }Dla opłaconej wcześniej faktury wysyłana jest odpowiedź z kodem błędu 422 "Unprocessable Entity".
-
-
Pozycje faktury
-
Tworzenie nowej pozycji
Tworzenie nowej pozycji następuje w wyniku wysłania żądania typu POST na adres https://sandbox.espago.com/api/invoice_items
Dostępne parametry
Parametr Opis Wartość pola Obligatoryjność amount Kwota transakcji Liczba dziesiętna, np. 123,45 Wymagany currency Waluta Symbol waluty zgodny z posiadanym MID Wymagany date Data obciążenia Data obciążenia w przyszłości w formacie unix time Wymagany client ID klienta Identyfikator umożliwiający przypisanie transakcji do utworzonego klienta Wymagany description Opis transakcji Powinien składać się z co najmniej 5 znaków. Opcjonalny Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/invoice_items -u app_id:password -d "currency=currency" -d "date=unix_time" -d "amount=100" -d "client=client_id" -d "description=Opis transakcji"Przykładowa odpowiedź
{ "id":"ii_1sbC2i-UHMWJXZH", "client":"cli_xNKNXh-_kWu6Qi", "description":"Opis transakcji", "amount":"100.00", "currency":"PLN", "created_at":1381755981 } -
Pobieranie informacji o pozycjach zawartych w fakturze
Pobranie informacji o pozycjach wchodzących w skład faktury jest możliwe po wysłaniu żądania typu GET na adres: https://sandbox.espago.com/api/invoices/(:invoice_id)/line_items
(:invoice_id) - identyfikator faktury
Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/invoices/(:invoice_id)/line_items -u app_id:passwordPrzykładowa odpowiedź
{ "count":1, "invoice_items": [{ "id":"ii_1KZ0VBahlukLI2X", "client":"cli_OU7k00vEMGi53C", "description":"Pozycja 1", "amount":"7.00", "currency":"PLN", "created_at":1371631057 }] } -
Usuwanie istniejącej pozycji
Usunięcie istniejącej pozycji następuje w wyniku wysłania żądania typu DELETE na adres https://sandbox.espago.com/api/invoice_items/(:id)
(:id) - identyfikator pozycji
Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/invoice_items/(:id) -u app_id:password -X DELETEOdpowiedź
Status uzyskany w odpowiedzi to 204 "No content".
-
-
-
Tokeny
Tokeny do kart klientów umożliwiają obciążenie kart klientów, bez przechowywania danych o ich kartach. Na potrzeby automatycznego tworzenia tokenów, udostępniliśmy bibliotekę JS, której wykorzystanie w formularzu, gdzie Klient podaje dane karty, bezpośrednio tworzy token do tej karty. Poniżej został opisany cały schemat działania takiego formularza. W tym rozdziale znajduje się również przykład wykorzystania biblioteki JS w formularzu z danymi karty klienta.
-
Schemat wykorzystania tokenów
- Formularz, umieszczony na stronie Merchanta, powinien wykorzystywać skrypt Espago.js. Strona, na której znajdować się będzie formularz w nagłówku (head) musi zawierać znacznik meta z kluczem publicznym Merchanta. Podane w formularzu dane dotyczące karty Klienta są wykorzystywane do utworzenia Tokenu. Pozostałe dane są przetwarzane według akcji formularza oprogramowanych przez Merchanta. W formularzu muszą zostać zawarte poniższe pola z nazwami (id) dokładnie takimi samymi jak zamieszczone poniżej.
- Formularz komunikuje się za pośrednictwem biblioteki Espago.js z bramką Espago (wysyłając żądanie na api/tokens).
- Dla poprawnych danych zostaje utworzony token i przejście do kroków zawartych w dalszym opisie. W przypadku podania niepoprawnych danych następuje blokada wykonania akcji.
- Token jest przesyłany do Aplikacji Merchanta w parametrze "card_token"
- Aplikacja Merchanta komunikuje się z bramką Espago, np. w celu utworzenia w naszym systemie klienta z podanym tokenem, zamiast danymi karty klienta.
- Bramka Espago odpowiada na zapytania. Istnieje możliwość pobrania danych utworzonych wcześniej klientów. Musi to zostać zaimplementowane samodzielnie przez Merchanta, a konkretna akcja powinna zostać przekazana w nagłówku formularza. Należy pamiętać, że dodatkowe akcje implementowane samodzielnie muszą być autoryzowane przez AppID i hasło konkretnego Serwisu.
-
Przykładowy formularz zbudowany w oparciu o Espago.js wykorzystujący metody walidacji
Oto przykładowy kod, który należy zamieścić na stronie. Przykład wykorzystuje bibliotekę jQuery, której sam skrypt Espago.JS nie wymaga do poprawnego działania. Możliwa jest więc implementacja również w "czystym" JavaScript.
Uwaga!
W rozdziale zalozenia-wstepne/przydatne-pliki w paczce plików do pobrania dostępny jest najnowszy przykładowy formularz wykorzystujący skrypt JS z biblioteką jQuery.<html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> <script src="https://code.jquery.com/jquery-latest.js"></script> <script src="https://ajax.aspnetcdn.com/ajax/jquery.validate/1.10.0/jquery.validate.js"></script> <script src='https://js.espago.com/v1/' type='text/javascript'></script> <script> $(document).ready(function(){ $("#espago_form").submit(function(event){ var espago = new Espago({public_key: 'public_key:', custom: true, live: false}); event.preventDefault(); if (espago.validate_card_number()){ ///obsługa komunikatów wyniku walidacji numeru karty $("#espago_card_number_error").text(""); } else { $("#espago_card_number_error").text("Błędne dane!"); }; if (espago.validate_first_name()){ ///obsługa komunikatów wyniku walidacji imienia $("#espago_first_name_error").text(""); } else { $("#espago_first_name_error").text("Błędne dane!"); }; if (espago.validate_last_name()){ ///obsługa komunikatów wyniku walidacji nazwiska $("#espago_last_name_error").text(""); } else { $("#espago_last_name_error").text("Błędne dane!"); }; if (espago.validate_card_date()){ ///obsługa komunikatów wyniku walidacji daty wygasania karty $("#espago_year_error").text(""); } else { $("#espago_year_error").text("Błędne dane!"); }; if (espago.validate_card_cvc()){ ///obsługa komunikatów wyniku walidacji wartości CVC $("#espago_verification_value_error").text(""); } else { $("#espago_verification_value_error").text("Błędne dane!"); }; espago.create_token(); }); }); </script> </head> <body> <form id='espago_form' method='POST' action=''> <label>Credit Card Number</label> <input id='espago_card_number' type='text'/> <span id='espago_card_number_error'></span> <br /> <label>First Name</label> <input id='espago_first_name' type='text'/> <span id='espago_first_name_error'></span> <br /> <label>Last Name</label> <input id='espago_last_name' type='text'/> <span id='espago_last_name_error'></span> <br /> <label>Month expire</label> <input id='espago_month' type='text'/> <span id='espago_month_error'></span> <br /> <label>Year expire</label> <input id='espago_year' type='text'/> <span id='espago_year_error'></span> <br /> <label>Verification Value</label> <input id='espago_verification_value' type='text'/> <span id='espago_verification_value_error'></span> <input type='submit' value='Go'/> </form> </body> </html> -
Wykorzystanie skryptu Espago.JS
Celem uproszczenia integracji stworzyliśmy dla Państwa skrypt, który generuje utworzony token zwracając jego wartość w parametrze "card_token".
Adres, pod którym można go znaleźć to https://js.espago.com/v1/
Jeżeli formularz płatności ma być osadzony wewnątrz Państwa strony to użycie skryptu https://js.espago.com/v1/ jest obowiązkowe. Skrypt musi być pobierany przez przeglądarkę klienta bezpośrednio z serwera Espago.
Dostępność skryptu js.espago.com (SLA) jest taka sama jak bramki Espago, dlatego nie ma potrzeby kopiowania i używania przez skryptu JS Espago ze swojego serwera.Przy wykorzystaniu skryptu https://js.espago.com/v1/ w formularzu pola zawierające dane kart (numer karty, data ważności, właściciel) nie może mieć parametru "name". Do działania skryptu wystarczy "id". Aby uzyskać te dane można użyć zapytania o dane tokenu lub (najprościej) odczytać je z odpowiedzi bramki Espago przy tworzeniu profilu klienta (zapytanie /api/clients) lub płatności (zapytanie /api/charges).
-
Konstruktor Espago
Formularz zadziała poprawnie tylko w wyniku operacji na utworzonym wcześniej obiekcie espago. Na nim będą wywoływane wszystkie metody odpowiedzialne za komunikację oraz ewentualną walidację wprowadzonych danych. Utworzony obiekt musi zawierać klucz publiczny merchanta. Poniżej został zamieszczony przykładowy kod odpowiedzialny za jego utworzenie:
var espago = new Espago({public_key: 'klucz_publiczny:'});Klucz publiczny:
Jest to narzędzie autoryzacyjne Merchanta, dzięki któremu możliwe jest tworzenie tokenów za pomocą biblioteki Espago.js. Jest on widoczny w sekcji API, w zakładce Twoje Strony. Tam również możliwa jest jego zmiana (zresetowanie).Parametry
Parametr Obligatoryjność Wartości domyślne Znaczenie public_key obowiązkowy Klucz publiczny Merchanta live opcjonalny true Parametr, który wskazuje gdzie będą wysyłane dane do utworzenia tokenu. Parametr 'true' oznacza wysyłanie danych na środowisko produkcyjne, parametr 'false' na środowisko testowe. form opcjonalny #espago_form Nazwa formularza card_number opcjonalny #espago_card_number Numer karty klienta first_name opcjonalny #espago_first_name Imię właściciela karty last_name opcjonalny #espago_last_name Nazwisko właściciela karty month opcjonalny #espago_month Miesiąc ważności karty year opcjonalny #espago_year Rok ważności karty cvc opcjonalny #espago_verification_value Numer weryfikacyjny karty custom opcjonalny false Wartość 'true' pozwala na zdefiniowanie własnych parametrów success i error. success opcjonalny function(data) {} Funkcja callback. Akcje w niej zawarte wykonują się w przypadku otrzymania pozytywnej odpowiedzi zwrotnej. error opcjonalny function(data) {} Funkcja callback. Akcje w niej zawarte wykonują się w przypadku wystąpienia błędu podczas komunikacji z serwerem. submit opcjonalny true Zatwierdzenie formularza i wysłanie danych. -
Niezbędne pola formularza
ID Pola Typ pola Znaczenie espago_card_number text Numer karty klienta espago_first_name text Imię klienta espago_last_name text Nazwisko klienta espago_month text Miesiąc wygaśnięcia karty espago_year text Rok wygaśnięcia karty espago_verification_value text Kod potwierdzenia Uwaga!
Podane ID pola są wymagane przy ustawieniach standardowych i mogą ulegać zmianie w zależności od zastosowanych wartości parametrów konstruktora z poprzedniego rozdziału. -
create_token()
Główna akcja skryptu komunikująca się z bramką. Na podstawie wcześniej określonego klucza publicznego merchant jest identyfikowany, a wszelkie przesłane dane karty wiązane z tokenem.
espago.create_token();Uwaga!
Domyślnie funkcja espago.create_token() wykonuje akcję submit. Możliwe jest jej wyłączenie poprzez zawarcie w niej dodatkowych argumentów funkcji zawartych poniżej (kolejno wyłączenie akcji submit oraz czynności na wypadek powodzenia i błędu):
espago.create_token({ submit: false, success: function(data) { alert("success"); }, error: function(data) { alert("error"); } }); -
Walidacja pól formularza po stronie klienta
Poniżej przedstawione zostały funkcje walidacji pól formularza. W przykładowym kodzie tych funkcji zostały wprowadzone dane podlegające walidacji. W przypadku ich braku, domyślnym parametrem stają się wartości odpowiednich pól formularza.
validate_card_number()
Metoda umożliwiająca walidację numeru karty klienta. Przy wprowadzaniu numeru karty z dodatkowymi znakami nie będącymi cyframi, zostaną one zignorowane.
espago.validate_card_number('4242424242424242') //true espago.validate_card_number('42 42 42 42 42 42 42 42') //true espago.validate_card_number('42 42 42') //false espago.validate_card_number() //domyślnym parametrem wartość pola 'espago_card_number' formularzavalidate_first_name()
Metoda walidująca imię właściciela karty wprowadzane do formularza płatności.
espago.validate_first_name('Jan') //true espago.validate_first_name('') //false espago.validate_first_name() //domyślnym parametrem wartość pola 'espago_first_name' formularzavalidate_last_name()
Metoda walidująca nazwisko właściciela karty wprowadzane do formularza płatności.
espago.validate_last_name('Kowalski') //true espago.validate_last_name('') //false espago.validate_last_name() //domyślnym parametrem wartość pola 'espago_last_name' formularzavalidate_card_date()
Metoda walidująca datę ważności karty wprowadzaną do formularza płatności.
espago.validate_card_date('02', '2017') //true espago.validate_card_date(02, 2017) //true espago.validate_card_date(2, 17) //false espago.validate_card_date() //domyślnymi parametrami wartości pól 'espago_month' i 'espago_year' formularzavalidate_card_cvc()
Metoda walidująca kod CVC karty wprowadzany do formularza płatności.
espago.validate_card_cvc('123') //true espago.validate_card_cvc('12') //false espago.validate_card_cvc('xyx') //false espago.validate_card_cvc() //domyślnym parametrem wartość pola 'espago_verification_value' formularza
-
-
Pobieranie danych o tokenie
Aby pobrać dane o istniejącym tokenie należy wysłać żądanie typu GET na podany adres https://sandbox.espago.com/api/tokens/(:id)
(:id) - identyfikator tokenu, którego dane chcemy pobrać
Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/tokens/(:id) -u app_id:password -X GETPrzykładowa odpowiedź
{ "id":"cc_J_wDRKH6jmIEb_8", "created_at":1550871586, "used":false, "card":{ "company":"VI", "last4":"4242", "year":2017, "month":2, "first_name":"Jan", "last_name":"Kowalski", "authorized":null, "created_at":1550871586 } } -
Tworzenie tokenu do karty
Aby utworzyć token do karty klienta należy wysłać żądanie typu POST na podany adres https://sandbox.espago.com/api/tokens
Uwaga!
Do wysyłania żądania typu POST, tworzącego token do danej karty potrzebny jest klucz publiczny (publickey) serwisu Merchanta.Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/tokens -u publickey: -d "card[first_name]=Jan" -d "card[last_name]=Kowalski" -d "card[number]=4242424242424242" -d "card[verification_value]=123" -d "card[year]=2014" -d "card[month]=02"Przykładowa odpowiedź
{ "id":"cc_J_wDRKH6jmIEb_8", "created_at":1550871586, "used":false, "card":{ "company":"VI", "last4":"4242", "year":2017, "month":2, "first_name":"Jan", "last_name":"Kowalski", "authorized":null, "created_at":1550871586 } }Uwaga!
Parametr used przyjmuje wartości logiczne true lub false. Jeżeli wartość wynosi false, oznacza to, że token nie został jeszcze użyty.
-
-
Klienci
Rozdział ten jest poświęcony tworzeniu klientów w systemie Espago. W obiekcie klienta, można przechowywać jego dane, ze szczególnym uwzględnieniem danych karty. Klienta utworzonego z pełnymi danymi karty, można obciążać wiele razy. W szczególnym przypadku, gdy przy tworzeniu nowego obciążenia nie zostanie podany klient, to w systemie Espago utworzy się pusty obiekt (bez żadnych danych wewnątrz).
-
Nowy klient
Utworzenie nowego klienta następuje w wyniku wysłania żądania typu POST na adres https://sandbox.espago.com/api/clients/
Dostępne parametry HTTP:
Parametr Opis Komentarze Obligatoryjność description Krótki opis klienta Powinno składać się z co najmniej 5 znaków. Pole opcjonalne email E-mail klienta Uzupełnienie adresu klienta umożliwi włączenie automatycznych powiadomień z bramki Espago o zmianie statusu płatności. Pole opcjonalne, po wypełnieniu sprawdzamy format adresu mailowego. card[first_name] Imię właściciela karty Opcjonalne. Możliwe jest utworzenie klienta pozbawionego danych karty, bądź skorzystania z tokenów, jednak w przypadku chęci bezpośredniego zapisania takich informacji warunkiem koniecznym jest uzupełnienie wszystkich parametrów. card[last_name] Nazwisko właściciela karty card[number] Numer karty klienta card[verification_value] Kod CVV card[year] Rok końca ważności karty klienta Zapisywane w formacie liczbowym YYYY card[month] Miesiąc końca ważności karty klienta Zapisywane w formacie liczbowym MM; możliwe opcje 01-12 card Parametr przekazujący ID tokenu do karty W tym parametrze można, zamiast podawania wszystkich danych karty z osobna, podać ID wcześniej utworzonego tokenu do karty. Opcjonalny Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/clients -u app_id:password -d "description=Jan Kowalski" -d "email=jan@kowalski.com" -d "card[first_name]=Jan" -d "card[last_name]=Kowalski" -d "card[number]=4242424242424242" -d "card[verification_value]=123" -d "card[year]=2017" -d "card[month]=02"Przykładowa odpowiedź
{ "email":"jan@kowalski.com", "id":"cli_Yzij0t46pV88oR", "created_at":1381825758, "description":"Jan Kowalski", "card":{ "company":"VI", "last4":"4242", "year":2017, "month":2, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "created_at":1381825758 }, "deleted":false }Opis i możliwe wartości parametrów authorized i company:
Parametr Wartość Opis company VI, MC Informacja o wystawcy karty: VI - Visa, MC - MasterCard, AX - American Express authorized null, true, false Zwraca informację o autoryzacji karty, przyjmuje wartości logiczne.
null - autoryzacja nie była przeprowadzana
true - autoryzacja karty przebiegła pomyślnie
false - autoryzacja karty przebiegła negatywniecreated_at (numer) Czas w formacie uniksowym Uwaga!
Jeżeli karta jest poprawnie zautoryzowana przy jej numerze w Panelu Merchanta, w opisie klienta, pojawi się etykieta "Aktywna karta". W innym przypadku wyświetli się etykieta "Nieaktywna karta". Dodatkowy paramter "issuer_response_code" pozwala rozpoznać przyczynę ewentualnego odrzucenia autoryzacji. -
Usuwanie istniejącego klienta
Usunięcie istniejącego klienta następuje w wyniku wysłania żądania typu DELETE na dany adres https://sandbox.espago.com/api/clients/(:id)
(:id) - identyfikator klienta, którego dane chcą Państwo usunąć
Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/clients/client_id -u app_id:password -X DELETEOdpowiedź
Status uzyskany w odpowiedzi to 204 "No content".
-
Pobranie danych istniejącego klienta
Pobranie danych utworzonego wcześniej klienta następuje w wyniku wysłania żądania typu GET na adres https://sandbox.espago.com/api/clients/(:id)
(:id) - identyfikator klienta, którego dane chcą Państwo pobrać
Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/clients/client_id -u app_id:passwordPrzykładowa odpowiedź
{ "email":"jan@kowalski.com", "id":"cli_Yzij0t46pV88oR", "created_at":1381825758, "description":"Jan Kowalski", "card":{ "company":"VI", "last4":"4242", "year":2017, "month":2, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "created_at":1381825758 }, "deleted":false } -
Aktualizacja danych istniejącego klienta
Aktualizacja danych utworzonego wcześniej klienta następuje w wyniku wysłania żądania typu PUT na adres https://sandbox.espago.com/api/clients/(:id)
(:id) - identyfikator klienta, którego dane chcą Państwo aktualizować
Uwaga!
Przy aktualizacji danych klienta obowiązują następująca zasada:
Jeżeli aktualizacji ulega, którakolwiek z danych dotyczących karty, należy podać wszystkie dane tej karty, nawet jeśli zmianie ulega tylko jedna część.Dostępne parametry HTTP:
Parametr Opis Komentarze Obligatoryjność description Krótki opis klienta Powinno składać się z co najmniej 5 znaków. Pole opcjonalne email E-mail klienta Uzupełnienie adresu klienta umożliwi włączenie automatycznych powiadomień z bramki Espago o zmianie statusu płatności. Pole opcjonalne card[first_name] Imię właściciela karty Opcjonalne. Możliwe jest nadpisanie danych karty wartościami pustymi, bądź skorzystania z tokenów, jednak w przypadku chęci bezpośredniej aktualizacji danych karty klienta warunkiem koniecznym jest uzupełnienie wszystkich jej parametrów. card[last_name] Nazwisko właściciela karty card[number] Numer karty klienta card[verification_value] Kod CVV card[year] Rok końca ważności karty klienta Zapisywane w formacie liczbowym YYYY card[month] Miesiąc końca ważności karty klienta Zapisywane w formacie liczbowym MM; możliwe opcje 01-12 card Parametr przekazujący ID tokenu do karty W tym parametrze można, zamiast podawania wszystkich danych karty z osobna, podać ID wcześniej utworzonego tokenu do karty. Opcjonalny Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/clients/(:id) -u app_id:password -X PUT -d "description=Jan Kowalski" -d "email=client@example.com" -d "card[first_name]=Jan" -d "card[last_name]=Kowalski" -d "card[number]=4242424242424242" -d "card[verification_value]=123" -d "card[year]=2014" -d "card[month]=02"Przykładowa odpowiedź
{ "email":"jan@kowalski.com", "id":"cli_Yzij0t46pV88oR", "created_at":1381825758, "description":"Jan Kowalski", "card":{ "company":"VI", "last4":"4242", "year":2017, "month":2, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "created_at":1381825758 }, "deleted":false } -
Autoryzacja karty klienta na żądanie
Autoryzacja karty klienta na żądanie następuje w wyniku wysłania żądania typu POST na adres https://sandbox.espago.com/api/clients/(:id)/authorize
(:id) - identyfikator klienta, którego dane mają zostać zautoryzowane
Autoryzacja polega to na zarezerwowaniu i zwróceniu 1 PLN (lub 1 EUR, itp) w celu sprawdzenia czy karta obsługuje płatności internetowe.
- Jeśli autoryzacja się powiedzie oznacza to, że karta obsługuje płatności internetowe, że jest ważna i aktualnie posiada środki na koncie.
- Jeśli autoryzacja się nie powiedzie to znaczy, że jest prawie pewne, że kolejne obciążenia się również nie powiodą (wyjątkiem jest tu odrzucenie autoryzacji ze względu na chwilowy brak środków lub wyczerpanie limitu transakcji danego dnia, ale najczęstszym powodem odrzucenia jest nieaktywowanie płatności Internetowych/E-commerce/MOTO lub limity ustawione na 0PLN).
Uwaga!
Jeśli autoryzacja jest pierwszą operacją wykonywaną przy pomocy danej karty/danego klienta to podczas tej autoryzacji będzie użyty kod CVV (może być użyty tylko jeden raz), wszystkie następne transakcje będą już wykonywane bez kodu CVV. Część kart może nie obsługiwać płatności bez kodu CVV (a co za tym idzie nie nadają się do płatności cyklicznych) co może powodować sytuację w której autoryzacja się powiodła, a dalsze próby obciążania już nie. Aby tego uniknąć należy zaraz po udanej autoryzacji dokonać drugiej autoryzacji lub płatności.Przykład z wykorzystaniem CURL
curl -i https://sandbox.espago.com/api/clients/(:id)/authorize -u app_id:password -X POSTPrzykładowa odpowiedź
{ "email":"jan@kowalski.com", "id":"cli_Yzij0t46pV88oR", "created_at":1381825758, "description":"Jan Kowalski", "card":{ "company":"VI", "last4":"4242", "year":2017, "month":2, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "created_at":1381825758 }, "deleted":false } -
Wyświetlanie grup klientów
Wyświetlenie określonej strony z określoną ilością klientów następuje w wyniku wysłania żądania typu GET na adres https://sandbox.espago.com/api/clients?page=1&per=10
Dostępne parametry HTTP
Parametr Opis Obligatoryjność Wartość domyślna page Numer strony Opcjonalny 1 (pierwsza strona) per Liczba obciążeń na każdej stronie Opcjonalny 25 (25 klientów) Przykład z wykorzystaniem CURL (bez parametrów dodatkowych)
curl -i https://sandbox.espago.com/api/clients -u app_id:passwordPrzykład z wykorzystaniem CURL i dodatkowych parametrów
curl -i https://sandbox.espago.com/api/clients -u app_id:password -d "page=2" -d "per=15"Przykładowa odpowiedź
{ "count":33, "clients":[ { "email":"jan@kowalski.com", "id":"cli_Yzij0t46pV88oR", "created_at":1381825758, "description":"Jan Kowalski", "card":{ "company":"VI", "last4":"4242", "year":2017, "month":2, "first_name":"Jan", "last_name":"Kowalski", "authorized":true, "issuer_response_code":"00", "created_at":1381825758 }, "deleted":false },{ "email":null, "id":"cli_KGe_jJ2ne0IfAP", "created_at":1381231843, "description":"Anna Nowak", "card":{ "company":"VI", "last4":"4242", "year":2018, "month":5, "first_name":"Anna", "last_name":"Nowak", "authorized":true, "issuer_response_code":"00", }, "deleted":false } ] }Uwaga!
Parametr count w odpowiedzi wskazuje łączną liczbę utworzonych klientów
-