• Założenia wstępne

    Niniejsza dokumentacja zawiera informacje potrzebne do integracji serwisu internetowego z bramką płatności Espago, przy użyciu starszej (ale w dalszym ciągu wspieranej) wersji APIv2.0.

    Ta część dokumentacji nie bedzie jest już aktualizowana. W celu uzyskania najnowszej i uaktualnianej dokumentacji proszę przejsć do zakładki "Dokumentacja API v 3.0".

    • Integracja

      1. 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).
      2. 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).
      3. 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
      4. 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).
      5. Po zintegrowaniu się ze środowiskiem produkcyjnym środowisko testowe pozostaje w dalszym ciągu do dyspozycji Klienta.
      6. 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ą.
      7. W zakładce download dostępne są przykładowe pliki przyspieszające integrację.
    • Ogólny opis działania bramki

      1. 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.
      2. Adres aplikacji dla środowiska testowego to https://sandbox.espago.com/api
      3. Architektura aplikacji jest zgodna ze wzorcem REST.
      4. Dane początkowe przesyłane są z wykorzystaniem HTTP PARAMS, a wynikowe zwracane w formacie JSON.
      5. 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).
      6. W celu zapewnienia odpowiedniego poziomu bezpieczeństwa wymagane jest na stronie sklepu zastosowanie certyfikatów SSL i wykorzystanie skryptu JS udostępnianego przez Espago.
      7. Przykładowa płatność jednorazowa:
        1. Wypełnienie formularza przez klienta i wstępna walidacja parametrów (realizowana przez skrypt JS w przeglądarce klienta)
        2. Utworzenie tokenu i zwrócenie id_tokenu do webaplikacji sprzedawcy (realizowane przez skrypt JS, token w postaci "cc_xxxxxxxxxx")
        3. 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. 
      8. Informacje widoczne dla klienta:
        1. 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.
        2. 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.
        3. 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
      9. 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.
    • 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:

      1. 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.
    • 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:

      1. Przejść do zakładki Twoje strony
      2. Przejść do okna edycji serwisu wybierając przycisk Edytuj
      3. 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. Hasło API
      4. Zaakceptować zmiany klikając Edytuj dane serwisu
      5. Należy zwrócić uwagę na uzyskane ID Aplikacji w tabeli głównej zakładki Serwisy. ID Aplikacji
      6. Przejść do szczegółowych informacji o serwisie klikając na jego nazwę. Pole "Klucz publiczny" jest wymagane do generowania tokenów. Klucz publiczny
  • 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:

    1. Zabronione jest używanie rzeczywistych numerów kart. Dozwolone jest korzystanie jedynie z numerów testowych, np.'4242424242424242'
    2. 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
    3. 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_code
      failed 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 POST

      Przykł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:password

      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"
      }
    • 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:password

      Przykł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 GET

      Przykł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 DELETE

      Przykł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 POST

      Przykł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 POST

      Przykł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:

      1. Przejść do zakładki Twoje strony
      2. Przejść do okna edycji serwisu wybierając przycisk Edytuj
      3. 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
         
      4. 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.

      5. 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). Ustawienia płatności cyklicznych

        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.
    • 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:password
        Przykł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 DELETE
        Odpowiedź

        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 PUT
        Odpowiedź

        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:password
        Przykł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:password
        Przykł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 DELETE
        Odpowiedź

        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

        ParametrOpisObligatoryjnośćWartość domyślna
        pageNumer stronyOpcjonalny1 (pierwsza strona)
        perLiczba subskrypcji na każdej stronieOpcjonalny25 (25 subskrypcji)
        Przykład z wykorzystaniem CURL (bez parametrów dodatkowych)
        curl -i https://sandbox.espago.com/api/subscriptions -u app_id:password
        Przykł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

        ParametrOpisObligatoryjnośćWartość domyślna
        pageNumer stronyOpcjonalny1 (pierwsza strona)
        perLiczba subskrypcji na każdej stronieOpcjonalny25 (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:password
        Przykł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:password
        Przykł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 polaZnaczenieDostępne wartości
        DateInformacja o zleconej dacie obciążeniaData w formacie Unix time
        PaidInformacja, czy faktura została opłacona'True' lub 'false'
        AttemptsLiczba wykonanych prób zapłatyWartość liczbowa
        Next payment attemptData wykonania kolejnej próby w przypadku negatywnej ostatniej odpowiedziData 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:password
        Przykł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:password
        Przykł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 POST
        Przykł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
        ParametrOpisWartość polaObligatoryjność
        amountKwota transakcjiLiczba dziesiętna, np. 123,45Wymagany
        currencyWalutaSymbol waluty zgodny z posiadanym MIDWymagany
        dateData obciążeniaData obciążenia w przyszłości w formacie unix timeWymagany
        clientID klientaIdentyfikator umożliwiający przypisanie transakcji do utworzonego klientaWymagany
        descriptionOpis transakcjiPowinien 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:password
        Przykł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 DELETE
        Odpowiedź

        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

      Alt text

       

      1. 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.
      2. Formularz komunikuje się za pośrednictwem biblioteki Espago.js z bramką Espago (wysyłając żądanie na api/tokens).
      3. 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.
      4. Token jest przesyłany do Aplikacji Merchanta w parametrze "card_token"
      5. Aplikacja Merchanta komunikuje się z bramką Espago, np. w celu utworzenia w naszym systemie klienta z podanym tokenem, zamiast danymi karty klienta.
      6. 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

        ParametrObligatoryjnośćWartości domyślneZnaczenie
        public_keyobowiązkowyKlucz publiczny Merchanta
        liveopcjonalnytrueParametr, 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.
        formopcjonalny#espago_formNazwa formularza
        card_numberopcjonalny#espago_card_numberNumer karty klienta
        first_nameopcjonalny#espago_first_nameImię właściciela karty
        last_nameopcjonalny#espago_last_nameNazwisko właściciela karty
        monthopcjonalny#espago_monthMiesiąc ważności karty
        yearopcjonalny#espago_yearRok ważności karty
        cvcopcjonalny#espago_verification_valueNumer weryfikacyjny karty
        customopcjonalnyfalseWartość 'true' pozwala na zdefiniowanie własnych parametrów success i error.
        successopcjonalnyfunction(data) {}Funkcja callback. Akcje w niej zawarte wykonują się w przypadku otrzymania pozytywnej odpowiedzi zwrotnej.
        erroropcjonalnyfunction(data) {}Funkcja callback. Akcje w niej zawarte wykonują się w przypadku wystąpienia błędu podczas komunikacji z serwerem.
        submitopcjonalnytrueZatwierdzenie formularza i wysłanie danych.
      • Niezbędne pola formularza


        ID PolaTyp polaZnaczenie
        espago_card_numbertextNumer karty klienta
        espago_first_nametextImię klienta
        espago_last_nametextNazwisko klienta
        espago_monthtextMiesiąc wygaśnięcia karty
        espago_yeartextRok wygaśnięcia karty
        espago_verification_valuetextKod 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' formularza
        validate_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' formularza
        validate_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' formularza 
        validate_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' formularza
        validate_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 GET

      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
        }
      }
    • 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 negatywnie
      created_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 DELETE
      Odpowiedź

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

      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
      }
    • 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:


      ParametrOpisKomentarzeObligatoryjność
      descriptionKrótki opis klientaPowinno składać się z co najmniej 5 znaków.Pole opcjonalne
      emailE-mail klientaUzupeł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 kartyOpcjonalne. 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 klientaZapisywane w formacie liczbowym YYYY
      card[month]Miesiąc końca ważności karty klientaZapisywane w formacie liczbowym MM; możliwe opcje 01-12
      cardParametr przekazujący ID tokenu do kartyW 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 POST

      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
      }

       

    • 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


      ParametrOpisObligatoryjnośćWartość domyślna
      pageNumer stronyOpcjonalny1 (pierwsza strona)
      perLiczba obciążeń na każdej stronieOpcjonalny25 (25 klientów)

      Przykład z wykorzystaniem CURL (bez parametrów dodatkowych)

      curl -i https://sandbox.espago.com/api/clients -u app_id:password

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