Wstęp

Uprzejmie informujemy, że aktualna dokumentacja bramki Espago została przeniesiona pod adres https://start.espago.com

Niniejsza strona ma charakter archiwalny, i jej zawartość nie jest aktualizowana od 2019 roku.

Niniejsza dokumentacja zawiera wszystkie informacje potrzebne do integracji serwisu internetowego z bramką płatności Espago przy użyciu najnowszej, rozwijanej wersji API 3.0.

Istnieją trzy główne możliwości integracji z bramką płatnosci Espago:

Testowy sklep prezentujący przykładową integrację płatnosci: https://warzywko.espago.com/

Dostęp do środowiska testowego https://sandbox.espago.com można uzyskać mailowo w Dziale Wsparcia Technicznego Espago, support @ espago.com.

• Ogólny opis działania bramki

  1. Wszystkie operacje związane z zarządzeniem płatnościami (sprawdzenie statusu, zwroty itp) realizuje się przy pomocy zapytań API (Application Programming Interface). Niniejsza dokumentacja w większości jest poświęcona opisowi tego API.
  2. Architektura aplikacji jest zgodna ze wzorcem REST.
  3. Odpowiedzi na zapytania API (głownie GET i POST) zwracane są w formacie JSON.
  4. Wymaganym kodowaniem do przesłania danych jest UTF-8.
     • Należy sprawdzić poprawność integracji podając jako imie/nazwisko posiadacza karty np.:
       • zażółć gęślą jaźń - dla języka polskiego,
       • sébasti, takác, grün, žižk - dla zagranicznych liter ze znakami diakrytycznymi.
  5. We wszystkich sposobach integracji wrażliwe dane kart płatniczych są przesyłąne bezpośrednio od klienta do bramki Espago, z pominięciem serwisu Sprzedawcy. Zrzuca to ze Sprzedacy odpowiedzialność za przechowywanie lub przetwarzanie danych kart, a certyfikacja PCI-DSS ogranicza się do wypełnienia ankiety po podpisaniu umowy z Elavon.
  6. W większości przypadków (strona płatności z formularzem do podania danych karty jest wewnątrz strony sprzedawcy) użycie skryptu JavaScript https://js.espago.com/espago-1.2.js lub Espago iFrame jest obowiązkowe. Dzięki wykorzystaniu skryptów 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.
  7. W celu zapewnienia odpowiedniego poziomu bezpieczeństwa zalecane jest na stronie sklepu zastosowanie certyfikatów SSL (HTTPS).
  8. 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.
  9. Dla zapytań API sugerowany timeout (maksymalny czas oczekiwania na odpowiedź z Espago) to 30 sekund, przy czym zdecydowana większość płatności jest przetwarzana w czasie poniżej 2 sekund.
  10. Zaleca się, aby unikać wywoływania cyklicznych zadań w godzinach 3:30-5:30 CEST (01:30- 03:30 UTC) w dni robocze, w tych terminach mogą być przeprowadzane planowane prace serwisowe w bramce Espago.

  • Przykładowa płatność jednorazowa

    Przykładowa płatność jednorazowa z formularzem płatności osadzonym w sklepie:
    1. Wypełnienie formularza danymi karty przez klienta
    2. Wstępna walidacja parametrów raz utworzenie tokenu z danymi karty płatniczej (realizowane przez skrypt JS, token w postaci "cc_xxxxxxxxxx") i przesłanie id_tokenu do webaplikacji Sprzedawcy razem z formularzem.
    3. Wysłanie z serwisu Sprzedawcy żądania płatności do bramki Espago (zapytanie na /api/charges) przy powołaniu się na odebrany od klienta token i odczytanie potwierdzenia/powodu odrzucenia transakcji.
    4. Jeżeli usługa 3D Secure jest włączona, dla potwierdzenia transakcji wymagane jest przekierowanie użytkownika na redirect_url uzyskany w odpowiedzi na zapytanie /api/charges. Gdy klient zakończy weryfikację 3D Secure z bramki Espago przesyłane jest do serwisu sprzedawcy żadanie zwrotne (back request) z potwierdzeniem transakcji a klient jest przekierowany do strony sprzedawcy.
    Przykładowa płatność jednorazowa z przekierowaniem klienta na stronę Espago:
    1. Przesłanie formularza (poprzez kliknięcie klienta) ze strony sprzedawcy do bramki Espago. Formularz zawiera potrzebne dane dotyczące płatności (m.in. kwotę, opis)
    2. Klient przechodzi przez proces płatności na stronie Espago.
    3. Przekierowanie klienta z powrotem do strony Sprzedawcy wraz z informacją o statusie płatności. Równoległe wysłanie informacji zwrotnej o statusie płatności z bramki Espago na adres URL w serwisie Sprzedawcy.

  • Informacje widoczne dla klienta

    Informacje dotyczące płatności widoczne dla klienta:
    1. Jeżeli w profilu klienta został podany adres e'mail to przy każdej próbie (udanej i nieudanej) obciążenia karty klienta dostaje on powiadomienie mailowe. Wiadomość zawiera informacje takie jak: nazwa sklepu, kwota, opis i status płatności, a w przypadku niepowodzenia płatności również informację o przyczynie odrzucenia przez bank. 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 SP Z O O 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. Warto wyświetlić klientowi informację o tym, że nie przechowują Państwo kompletu danych kart.

• 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. Lista wymogów technicznych i merytorycznych Elavon dostępna jest w dokumentacji w dziale "Do pobrania".
  4. 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
  5. W ramach integracji należy przetestować/zaimplementować działanie funkcji takich jak:
     • tworzenie tokenów,
     • obciążenie kart,
     • wyświetlanie klientowi informacji o przyczynie odrzucenia nieudanej płatności,
     • uzyskiwanie informacji na temat dokonanych płatności,
     • realizację zwrotów i anulowanie transakcji (nie ma konieczności implementowania tych funkcji od razu, ale w praktyce są potrzebne i należy przynajmniej sprawdzić możliwość wykonania ich 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, tzn. uruchomienie płatności cyklicznych, wywoływanych przez bramkę Espago),
     • odbieranie informacji zwrotnej (o ile jest uzasadnienie biznesowe).
  6. Po zintegrowaniu się ze środowiskiem produkcyjnym środowisko testowe pozostaje w dalszym ciągu do dyspozycji Klienta.
  7. 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łaczyć zabezpieczenie 3D-Secure (domyślnie włączone) oraz funkcję DCC (domyślnie wyłaczona)
     • Włączyć/wyłączyć możliwość tworzenia i korzystania z planów i subskrypcji (domyślnie wyłączone).
     • Utworzyć nowego użytkownika z dostępem do panelu.
     • Udzielać odpowiedzi i pomagać rozwiązywać problemy związane z integracją.
  8. W zakładce download dostępne są przykładowe pliki przyspieszające integrację.

• 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 w komunikacji z bramką Espago istnieją pewne wymagania, które ograniczają kompatybilność względem starych technologii:

  • Wymaganie połączeń szyfrowanych protokołami TLSv1.2 lub TLSv1.1

    Od 13 lutego 2018 bramka produkcyjna Espago akceptuje tylko połączenia szyfrowane przy pomocy protokołów TLSv1.2 oraz TLSv1.1 (do tego czasu akceptowała również TLSv1). W bramce testowej https://sandbox.espago.com takie ustawienie działa od listopada 2015, więc jeżeli Państwa aplikacja łączy się ze środowiskiem testowym to znaczy, że spełnia najnowsze wymagania i będzie z powodzeniem łączyć się z bramką produkcyjną.

    • Niektóre starsze systemy, biblioteki lub przeglądarki nie wspierają takich połączeń; powinny one zostać zaktualizowane lub zastąpione nowszymi rozwiązaniami.
    • Ten wymóg dotyczy wszystkich połączeń do API, przekierowania 3D-Secure klientów oraz dostępu do panelu WWW.
    • Zmiany opisane są w historii zmian: zmiany-w-wymaganiach-ssl-https-bramki

     

    Lista oprogramowania obsługującego połączenia TLSv1.2 oraz TLSv1.1

    System/ aplikacja/ biblioteka	Minimalna kompatybilna wersja	Uwagi
    Windows	7 i nowsze	Uwaga: W starszych systemach należy użyć alternatywnych, aktualnych przeglądarek (np. Chrome, Firefox, Opera)
    Windows Server	2008 R2 i nowsze	Windows 2008 R2 wymaga włączenia obsługi TLSv1.2 w rejestrach systemu oraz włączenia obsługi dodatkowych szyfrów
    Android	4.4.4	Android API level 20. Częściowe wsparcie dla TLSv1.2 dostępne również w wersi 4.2
    OpenSSL	1.0.1 i nowsze	Uwaga: OpenSSL w wersji 0.9.8 nie obsługuje TLSv1.2
    Apache	2,2,23 i nowsze
    Java	8	Uwaga: Java 6 oraz Java 7 nie obsługuję TLSv1.2
    .NET Framework	4.5.1 i nowsze	może wymagać włączenia w ustawieniach, oraz wymaga systemu Windows wspierającego TLSv1.2

    Lista protokołów i szyfrów umożliwiających bezpieczne połączenie do bramki Espago

    Protokół	Dostępne zestawy szyfrów	Uwagi
    TLSv1.2 TLSv1.1	ECDHE-ECDSA-AES128-GCM-SHA256 ECDHE-ECDSA-AES256-GCM-SHA384 ECDHE-RSA-AES256-GCM-SHA384 ECDHE-RSA-AES128-GCM-SHA256 kEDH+AESGCM ECDHE-ECDSA-AES256-SHA384 ECDHE-ECDSA-AES256-SHA ECDHE-ECDSA-AES128-SHA256 ECDHE-ECDSA-AES128-SHA ECDHE-RSA-AES256-SHA384 ECDHE-RSA-AES256-SHA ECDHE-RSA-AES128-SHA256 ECDHE-RSA-AES128-SHA DHE-RSA-AES256-SHA256 DHE-DSS-AES256-SHA DHE-RSA-AES256-SHA DHE-RSA-AES128-SHA256 DHE-RSA-AES128-SHA DHE-DSS-AES128-SHA256 DHE-RSA-AES128-GCM-SHA256 DHE-DSS-AES128-GCM-SHA256 AES256-GCM-SHA384 AES256-SHA

    Zaleca się konfigurację aplikacji aby umożliwiała łączenie się przy użyciu najbezpieczniejszych protokołów i szyfrów, a także aby miała możliwość połączenia przy użyciu kilku zestawów szyfrów (tzn. nie wymuszanie jednego, konkretnego szyfru).

    • Testowanie łączności z protokołami TLSv1.2 i TLSv1.1

      Jeżeli Państwa aplikacja łączy się z API https://sandbox.espago.com ten rozdział nie jest potrzebny.

      Jeżeli Państwa aplikacje nie może nawiązać połączenia SSL/TLS z bramką Espago, to w celu potwierdzenia/wykluczenia problemów z protokołami SSL/TLS została utworzona dodatkowa domena https://oldssl-sandbox.espago.com dająca dostęp do tego samego serwera Sandbox):

      • https://oldssl-sandbox.espago.com spełnia starsze wymagania (akceptuje również TLSv1.0), umożliwia testowanie płatności pomimo nie spełniania nowych wymogów dotyczących SSL.
        • Ten adres powinien służyć tylko do sprawdzenia łączności, w przypadku zupełnej niemożliwości połączenia się aplikacji przez API do sandbox.espago.com (tzn. podejrzenia że problem dotyczy zestawienia połączenia SSL/TLS)
        • Jeżeli Państwa aplikacji łączy się z oldssl-sandbox, a nie łączy się z sandbox, oznacza to prawdopodobnie że Państwa oprogramowanie nie obsługuje protokołu TLSv1.2 i wymaga aktualizacji/wymiany.
      • https://sandbox.espago.com spełnia aktualne wymagania SSL/TLS, identyczne lub nawet bardziej restrykcyjne niż bramka produkcyjna.
        • Jeśli Państwa aplikacja łączy się z bramką https://sandbox.espago.com to znaczy że spełnia najnowsze wymagania i będzie z powodzeniem łączyć się z bramką produkcyjną po wprowadzeniu wszystkich zmian.
      • W razie wątpliwości skontaktuj się z Działem Wsparcia Espago (Support), jesteśmy w stanie określić jakich protokołów aktualnie używa Państwa aplikacja w komunikacji z Espago. W tym celu podaej źródłowy adres IP oraz ID aplikacji (ms_xxxxxxxx).

  • Formularz płatności nie działa w przeglądarce IE9 i starszych

    Do poprawnego działania formularza przyjmującego dane kart potrzebna jest przeglądarka Internet Explorer 10 lub nowsza, lub dowolna inna przeglądarka internetowa (Google Chrome, Mozilla Firefox, Opera, Safari, itp). Formularz płatości nie działa poprawnie w przeglądarkach Internet Explorer w wersji IE9 i starszych, w niektórych konfiguracjach występują również problemy z tworzeniem tokenów w przeglądarkach Microsoft Edge (z uwagi na ograniczenia tej przeglądardki dla zapytań CORS). 

    • 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.
    • Wyjaśnienie: Skrypt JS https://js.espago.com/espago-1.2.js 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.

• 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	Wymagany	application/vnd.espago.v3+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
  2. Przejść do okna edycji serwisu wybierając przycisk
  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.
  4. Należy ustawić adres url żądania zwrotnego (więcej o żądaniach zwrotnych: #266):
     
     url żądania zwrotnego - definiuje adres, na który wysyłana jest asynchronicznie informacja po uzyskaniu przez bramkę statusu kolejnej płatności. W bramce produkcyjnej dozwolone są tylko adresy HTTP i HTTPS (porty 80 i 443). W bramce testowej sandbox możliwe jest wysyłanie żadań zwrotnych dodatkowo na port 8002 i 8003.

  5. 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.

  6. Zaakceptować zmiany klikając
  7. Należy zwrócić uwagę na uzyskane ID Aplikacji w tabeli głównej zakładki Serwisy.
  8. Przejść do szczegółowych informacji o serwisie klikając "Wyświetl" przy jego nazwie.  Parametr "Klucz publiczny" jest niezbędny do generowania tokenów.

• Migracja z API v. 2.0

  Różnice pomiędzy API v.2.0 a v.3.0:

  • Każde zapytanie na API musi mieć nagłówek definiujący wersję używanego API (więcej). Jeśli serwis ma włączoną obsługą APIv2.0 oraz APIv3.0 domyślnym API przy braku nagłówków jest 2.0.
  • Informacje zwrotne z bramki Espago są wysyłane po wszystkich obciążeniach (w APIv2.0 były wysyłane tylko przy płatnosciach cyklicznych).
  • Nowy format informacji zwrotnych:  'Content-Type' => 'application/json; charset=utf-8' .
    • W trakcje migrowania z wersji 2 na 3, należy określić - w panelu merchanta (więcej) -  w jakim formacie mają przychodzić żądania zwrotne dla płatnosci cyklicznych:
    • Format żądań zwrotnych zwykłych obciążeń jest zależny od wersji API w których transakcje zostały utworzone. Odpowiednio application/x-www-form-urlencoded i application/json dla API v. 2.0 i API v. 3.0.
  • Przy włączonej, dla merchanta, opcji 3D Secure, podczas tworzenia nowego obciążenia (jeżeli klient ma kartę zarejestrowaną w usłudze 3D Secure), odsyłany jest adres - parametr redirect_url - na który należy przekierowąć klienta w celu dokończenia/potwierdzenia danej transakcji. (więcej)
  • Nowa wersja 1.2 skryptu Espago JS, używanego w formularzu do tworzenia tokenu karty (więcej) oraz możliwość użycia dynamicznie tworzonego Espago iFrame w celu przyjmowania danych od klienta kart na stronie sklepu.

• Minimalizacja ilości odrzuceń płatności

  Karty większości klientów nadają się do płatności internetowych oraz cyklicznych. Warunkami koniecznymi do powodzenia jest poprawna integracja Sprzedawcy z bramką Espago oraz odpowiednie ustawienia karty przez Klienta. Zawsze pojawia się jednak jakaś część odrzuconych płatności (w zależności od klientów może to być od kilku do kilkunastu procent).

  Poniżej spisano rozwiązania, na które warto zwrócić uwagę aby maksymalizować liczbę udanych płatności:

   

  Działanie	Opis/Komentarz
  Edukacja klientów i informowanie o przyczynie odrzucenia	Po nieudanej płatności należy wyświetlić klientowi przyczynę odrzcenia, np. kod odrzucenia 51 oznacza brak środków na karcie/koncie. Espago wyświetla taką informacja jeśli klient był przekierowany na stronę płatności Espago, oraz jest przesyłamy informację w powiadomieniu mailowym o płatności (jeśli został podany mail klienta).  Jest to najskuteczniejsza i konieczna metoda zwiększająca ściągalnosć płatności, jeśli klient nie skonfiguruje swojej karty do działania w internecie to nie będzie możliwe jej obciążanie. Przydatne informacje: https://www.espago.com/faq-posiadacza-karty#a338-przygotowanie-karty-do-platnosci-internetowych-i-cyklicznych
  Używanie płatności jednorazowych z kodem CVV	Płatnosći jednorazowe bez kodu CVV (np. wywołanie płatności recurringowej bez parametru recurring=true) są odrzucane przez wiele banków. Część kart w ogóle nie obsługuje płatności cyklicznych (patrz rozdział: "Problem kart nienadających się do płatności cyklicznych") dlatego do płatnosci tzw. "one click payment" warto dosyłać kod CVV i wykonywać je jako zwykłe płatności.
  [Płatności cykliczne] Poprawne odfiltrowanie kart nie działających w płatnościach cyklicznych przed uruchomieniem subskrypcji	Szczegóły w rozdziale "Problem kart nienadających się do płatności cyklicznych"

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.

• Testowanie

  Podczas testowania kart płatniczych należy używać wymienionych niżej testowych numerów kart. Zabronione jest używanie rzeczywistych numerów kart.

  Numer karty	Opis
  4242424242424242	Do zwykłych transakcji jednorazowych i cyklicznych, bez 3D Secure, bez DCC.
  4012001037141112	Visa Credit z zabezpieczeniem 3D Secure (Verified by Visa)
  5432670000041258	MasterCard z zabezpieczeniem 3D Secure (MasterCard SecureCode)
  375987000000005	American Express z zabezpieczeniem 3D Secure (SafeKey)
  4012888888881881	Visa z zabezpieczeniem 3D Secure (Verified by Visa) oraz włączonym DCC. Waluta: USD.
  5555555555554444	MasterCard z  zabezpieczeniem 3D Secure (MasterCard SecureCode) oraz włączonym DCC. Waluta: HKD.
  4242421111112239	Visa z włączonym DCC, bez 3D-Secure. Waluta: HKD.
  4917484589897107	Visa do zwykłych transakcji jednorazowych, bez 3D Secure, bez DCC. Karta wymaga użycia kodu CVV do każdej transakcji (nie obsługuje płatności cyklicznych), transakcje bez CVV są odrzucane.

  Jako datę wygaśnięcia karty należy podać dowolną datę z przyszłości. Od wyboru miesiąca zależy otrzymany rezultat transakcji. Dzięki temu można testować zarówno scenariusze negatywne jak i pozytywne.

  Miesiąc ważności	Skutek
  01-05	transakcja zaakceptowana
  06	wynik losowy, 50% szans powodzenia transakcji. Przydatne przy testach subskrypcji.
  07-12 transakcja odrzucona, dla każdego miesiąca inne przyczyny odrzucenia:
  07	transakcja odrzucona. Kody odrzuceń: 04, 07, 41, 43.
  08	transakcja odrzucona. Kod odrzucenia: 51.
  09	transakcja odrzucona. Kod odrzucenia: 13.
  10	transakcja odrzucona. Kod odrzucenia: 00.
  11	transakcja odrzucona. Kod odrzucenia: 54.
  12	transakcja odrzucona. Kody odrzuceń: 05, 57, 61.

  Kod CVV/CVC w bramce testowej jest ignorowany.

  CVV	Opis działania w bramce testowej
  683	Niepoprawny kod CVV. Transakcja zostanie odrzucona ze względu na niepoprawny kod CVV.
  Pozostałe CVV	Poprawny kod CVV.

• Możliwe stany płatności

  Status "executed" jest potwierdzeniem obciążenia klienta, na jego podstawie w sklepie można uznać zakupy za opłacone.

  Stan	Opis
  new	Nowa płatność jeszcze nie obciążająca klienta
  executed	Płatność została wykonana, konto klienta obciążone. Na podstawie tej wartości/parametru można uznać płatność za wykonaną. 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
  preauthorized	[Status dostępny tylko w przypadku użycia parametru complete=false] Środki są zarezerwowane (blokada) na koncie klienta ale nie są jeszcze pobrane. Czytaj więcej
  tds_redirected	[Status dostępny tylko w przypadku włączonej opcji 3D-Secure]. Klient został przekierowany na stronę 3D-Secure (stronę banku), oczekiwanie na jego powrót.
  dcc_decision	[Status dostępny tylko w przypadku włączonej opcji DCC]. Oczekiwanie na nadesłanie przez Sprzedawcę decyzji dotyczącej wybranej przez Klienta waluty płatności.
  resigned	Klient zrezygnował z autoryzacji płatności lub porzucił płatność [stan dostępny przy włączonym 3D-Secure, DCC lub/i MasterPass]. W przypadku porzucenia (brak działania klienta przez czas 1,5h) transakcje ze statusem "new", "tds_redirected" lub "dcc_decision" zmieniają status na "resigned".
  reversed	Płatność została anulowana/wycofana w dniu jej wykonania (przed rozliczeniem).
  refunded	Platnosc zostala zwrocona w całości lub części.

   

• Możliwe przyczyny odrzuceń płatności

  • Informacje ogólne - parametr "reject_reason"

    Parametr "reject_reason" może służyć jako dodatkowe doprecyzowanie przyczyny odrzucenia i nie jest konieczne jego sprawdzanie (użyteczniejszą informacją jest kod "issuer_response_code"). 

     

    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
    3ds_not_authorized	odrzucenie podczas 3D-Secure	Nieprawidłowe poświadczenie 3D-Secure lub inny błąd związany z 3D-Secure.

  • Szczegółowe informacje - parametr "issuer_response_code"

    Aktualna tabela (MySQL dump) z kodami odrzuceń issuer_response_code znajduje się w dziale "Do pobrania".

    Kod błędu	Znaczenie	Proponowany komunikat
    00	Zaakceptowane obciążenie	Transakcja zaakceptowana. Dziękujemy!
    	Blokada odpowiedzi na poziomie Elavon (sugerowany kontakt z Espago/Elavon)	ODMOWA - wystąpił błąd. Transakcja została odrzucona ze względu na brak odpowiedzi z banku, blokadę konta Sprzedawcy, użycie nieobsługiwanego typu karty lub nieprawidłowe dane kary. Prosimy spróbować ponownie później lub skontaktować się z Działem Wsparcia Technicznego Espago.
    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	Płatności typu MOTO/eCommerce/subskrypcyjne nieaktywne lub niewspierane	ODMOWA – bank odrzucił transakcję ze względu na ustawienia zabezpieczeń (np. karta nie obsługuje płatności cyklicznych/bez kodu CVV) albo blokadę środków lub karta nie obsługuje płatności internetowych/MOTO. Sprawdź ustawienia karty lub użyj innej karty.
    13,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, czy karta jest wciąż aktywna czy przeterminowana 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.
    57	Typ transakcji niedozwolony dla karty	ODMOWA – bank odrzucił transakcję ponieważ użyta karta nie może zostać użyta to tego typu transakcji (internetowe, MOTO lub cykliczne). Sprawdź ustawienia karty lub użyj innej karty.
    59	Podejrzenie oszustwa	ODMOWA - skontaktuj się z Twoim bankiem w celu wyjaśnienia przyczyny problemu
    62	Ograniczenie karty, wykluczenie 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 CVV/CVC/PIN. 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. UWAGA: Nie należy powtarzać obciążeń dla tej karty! Może to zostać uznane za próbę oszustwa!
    91,92,94,98	Spróbuj Ponownie	ODMOWA – Tymczasowy błąd po stronie banku, spróbuj ponownie.
    E3	Niepoprawna weryfikacja 3D-Secure	ODMOWA – Transakcja nie przeprowadzona ze względu na nieprawidłowe poświadczenie klienta podczas sprawdzania 3D-Secure lub błąd związany z 3D-Secure.

• 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

  Rozpoczęcie tworzenia 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
  description	Opis transakcji	Musi składać się z 5 do 99 znaków.
  amount	Kwota transakcji	Liczba dziesiętna, np. 123.45
  currency	Waluta	Trzyliterowy symbol waluty zgodny z posiadanym MID
  client	ID klienta	Do wyboru: ID klienta w przypadku obciążenia istniejącego klienta lub ID tokenu w przypadku płatności jednorazowej.
  card	ID tokenu
  recurring	[opcjonalny]	Dodanie parametru "recurring=true" wymusza zakwalifikowanie przez bank (wystawcę karty) transakcji jako cyklicznej. Skutkuje to m.in. nie sprawdzaniem zabezpieczenia 3D-Secure. Parametr jest potrzebny w płatnościach cyklicznych/recurringowych (w nich CVV/CVC nie jest używany) ponieważ zwiększa szanse na zaakceptowanie przez bank płatności pomimo braku użycia kodu CVV/CVC.
  complete	[opcjonalny]	Dodanie parametru "complete=false" sprawia, że dana transakcja jest tylko blokadą środków, a nie pełnym obciążeniem. Szczegóły w rozdziale "Zarezerwowanie środków przyszłego obciążenia na koncie klienta".
  moto	[opcjonalny]	Dodanie parametru "moto=true" wymusza zakwalifikowanie transakcji jako MOTO (Mail Order/Telephone Order). Skutkuje m.in. nie sprawdzaniem zabezpieczenia 3D-Secure. Przed użyciem zalecamy konsultację z Espago.
  cvv	[opcjonalny]	Przesłanie ID tokenu CVV w postaci "cvv=cv_xxxxxxxxxx" umożliwia dodanie kodu CVV do płatności dokonywanej przy użyciu profilu klienta (gdy oryginalny CVV został już "użyty"). Szczegóły w rozdziale "Dosyłanie CVV".
  positive_url	[opcjonalny]	adres powrotny po pozytywnym zakończeniu transakcji
  negative_url	[opcjonalny]	adres powrotny po negatywnym zakończeniu transakcji
  skip_3ds	[opcjonalny]	Dodanie parametru "skip_3ds=true" Skutkuje nie sprawdzaniem zabezpieczenia 3D-Secure. Przed użyciem zalecamy konsultację z Espago.
  reference_number	[opcjonalny]	Tekst ref. transakcji - widoczny w raportach Elavon.  Długość do 20 znaków, tylko alfanumeryczne oraz -_ (myślnik i belka).
  locale	[opcjonalny]	Kod języka w standardzie ISO 639-1, dwuliterowa wartość typu string. Język wykorzystywany przy wyświetleniu strony płatności i/lub w powiadomieniu mailowym.
  email	[opcjonalny]	Adres email, na który ma zostać wysłane powiadomienie e'mail o wyniku tego obciążenia. Wartość typu string. Jeśli parametr jest użyty z profilem klienta posiadającym adres mailowy, to użyty jest przesłany tu w parametrze adres.
  skip_email	[opcjonalny]	Wyłącza powiadomienie mailowe, nawet jeśli użyto profilu klienta z adresem mailowym. Wartość boolowska (true/false, domyślnie: false).
  cof	[opcjonalny]	Wykorzystanie mechanizmu "Card on file". Możliwe wartości parametru: storing (zapisanie danych kart w postaci profilu klienta, do użycia przy płatności wykonanej z użyciem tokenu), recurring (informacja do banku, że płatność jest częścią subskrypcji, do użycia przy płatnosci wykonanej przy użyciu profilu klienta). Szczegóły dostępne w nowej dokumentacji.

   

  Przykład z wykorzystaniem CURL

  Kod wykorzystujący funkcjonalność obiektów klienta

  curl -H "Accept: application/vnd.espago.v3+json" -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"

  Kod wykorzystujący utworzony wcześniej token

  curl -H "Accept: application/vnd.espago.v3+json" -i https://sandbox.espago.com/api/charges -u app_id:password -d "amount=49.99" -d "currency=pln" -d "card=token_id" -d "description=Opis transakcji"

  • Przykładowa odpowiedź

    Użycie 3D Secure wymaga przekierowania Klienta na adres url przysłany w odpowiedzi na request, w parametrze "redirect_url".

    { "id":"pay_q8v53GIhU4SsaI", "description":"Opis transakcji", "channel":"elavon", "amount":"49.99", "currency":"pln", "state":"new", "client":"cli_UrxPVeAjYh3l3C", "created_at":1381821183, "card":{ "company":"VI", "last4":"4242", "year":2017, "month":1, "first_name":"Jan", "last_name":"Kowalski", "authorized":null, "created_at":1380540122 }, "issuer_response_code":"", "transaction_id":"tn_Wz8iuo426", "redirect_url":"https://sandbox.espago.com/3d-secure/tn_Wz8iuo426" }

     

    Gdy merchant lub klient nie mają włączonej obsługi 3D Secure:

    { "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" }

     

    Odpowiedzi o zmianie statusu transakcji przychodzą asynchronicznie na zdefiniowany przez Państwa adres żądania zwrotnego (więcej o żądaniach zwrotnych #266) i w przypadku braku odpowiedzi "200" ze strony aplikacji akcja jest ponawiana przez 24h z rosnącym interwałem.

    { "id": "pay_q8v53GIhU4SsaI", "description": "Description", "channel": "elavon", "amount": 49.99, "currency": "pln", "state": "executed", "client": "cli_UrxPVeAjYh3l3C", "created_at": 1381821183, "issuer_response_code": "00", "reversable": "true" }

     
    Uwaga!
    Należy zwrócić uwagę na fakt, że parametry w odpowiedzi i opcjonalne przekierowania różnią się w zależności od tego czy karta klienta obsługuje 3D-Secure czy nie, oraz czy obsługuje DCC czy nie. Parametry mogą być przesłane w różnej kolejności, ich lista zawarta jest w rozdziale poniżej.

  • Przykładowa odpowiedź przy błędnym zapytaniu

    Gdy przesłane parametry są niepoprawne lub w zapytaniu do API brakuje części danych może dojść do sytuacji, w której zapytanie zostanie odrzucone z kodem HTTP 422 lub innym. Taka sytuacja powinna mieć miejsce tylko w środowisku testowym.

    Odrzucenie z kodem HTTP 422 jest to odrzucenie niepoprawnego zapytania, a nie płatności (do próby dokonania płatności nawet nie dochodzi).

    Odpowiedź przy niepoprawnym opisie płatności (nagłówek: HTTP/1.1 422 Unprocessable Entity)

    {"errors":[{"code":null,"message":"Description is too short (minimum is 5 characters)","param":"description","type":"invalid_request_error"}]}

    Odpowiedź przy próbie dwukrotnego użycia tokenu karty (nagłówek: HTTP/1.1 422 Unprocessable Entity)

    {"errors":[{"code":null,"message":"Card token not found","param":"card","type":"card_error"}]}

    Odpowiedź przy próbie użycia nieisniejącego/usuniętego profilu klienta, profilu klienta należącego do innego konta lub profilu klienta bez danych karty płatniczej (nagłówek: HTTP/1.1 422 Unprocessable Entity)

    {"errors":[{"code":null,"message":"Card can't be blank","param":"card","type":"card_error"}]}

  • Znaczenie parametru ID transakcji

    Parametr transaction_id (z wartością tn_xxxxxxxxx lub tr_xxxxxxxxx) jest przesyłany przy każdej płatności obok zwykłego ID. Z technicznego punktu widzenia:
    • ID płatności występuje w komunikacji sprzedawca - Espago. Definiuje płatność/zlecenie płatności.
    • ID transakcji występuje w komunikacji Espago - Elavon. Definiuje "operację" płatności w Elavon.

    ID transakcji jest dostępne dla sprzedawcy w panelu udostępnianym przez Elavon np. w panelu https://www.imerchantconnect.com, dzięki czemu sprzedawca może sprawdzić jakie transakcje/płatności są zawarte w poszczególnych przelewach z Elavon na konto bankowe sprzedawcy. ID transakcji nie jest niezbędny, ale do powyższego celu warto go odczytywać i przechowywać.

    W normalnej sytuacji płatność (pay_xxxxxxxxx) ma przypisany 1 transaction ID. ID transakcji ulega zmianie (aktualizacji) w sytuacji gdy:

    • najpierw została wykonana preautoryzacja - rezerwacja środków (pierwszy ID transakcji), a następnie zapytanie potwierdzające obciążenie (drugi ID transakcji)
    • płatność została zwrócona (do płatności zostaje przypisany nowy numer ID transakcji zwracającej płatność)

     

  • Atrybuty płatności

    Płatność kartowa posiada zestaw parametrów. Są one zwracane zaraz po wykonaniu płatności, a także dostępne później przy odpytaniu o konkretną płatnosć lub o listę płatności.

    Parametr	Uwagi	Opis
    id		ID płatności. Umożliwia m.in. późniejsze odszukanie płatności, sprawdzenie statusu, zwrot. Ma postać pay_xxxxxxxxxxxxxxxx i długość 18 lub 20 znaków.
    description		Opis płatności przesłany w zapytaniu na /api/charges.
    channel		Kanał płatności. Domyślną wartością jest "elavon".
    amount		Kwota transakcji.
    currency		Waluta transakcji.
    state		Status transakcji. Szczegółowo opisane w części "Możliwe stany płatności"
    client		ID klienta przy pomocy którego dokonano płatności. W płatności jednorazowej (zapytanie przy użyciu parametru "card" jest to ID klienta "tymczasowego", które można zignorować.
    created_at		Data utworzenia płatności, czas w systemie unix.
    card	tablica	Parametry dotyczące użytej karty.
    issuer_response_code		Kod odpowiedzi z banku. Jeśli jest przekierowanie wynikające z 3D-Secure to ten parametr przyjmuje wartość 00 lub NULL do czasu dokonania płatności.
    transaction_id		ID transakcji. Przydatne do wyszukiwania płatności w panelu udostępnianym przez Elavon, gdyż tylko to ID jest widoczne w raportach Elavon (nie ma tam ID klienta ani ID płatności). Transakcja jest to "operacja". Domyślnie jedna płatność ma jedną transakcję (tj. wykonanie płatności), po zwróceniu części lub całości płatności zostaje przypisane tu ID transakcji zwracającej płatność.
    redirect_url	opcjonalny	Adres URL do przekierowania klienta jeśli obsługa 3D-Secure jest włączona oraz jeśli karta klienta obsługuje 3D-Secure.
    reversable	opcjonalny	Parametr "reversable=true" informuje o możliwości zwrotu płatności przed rozliczeniem. Po rozliczeniu parametr przyjmuje wartość "false" i przestaje być widoczny we właściwościach płatności.
    tds_redirect_form	opcjonalny/ tablica	Parametry umożliwiające przekierowanie klienta bezpośrednio do banku (zamiast do Espago przy użyciu redirect_url). W tym przypadku należy przekierować klienta formularzem na adres "action", metodą POST przekazując parametry PaReq, MD i TermUrl. W większości imlementacji ta opcja nie jest polecana, przed użyciem prosimy o kontakt z Espago.

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

  Preautoryzację można dokończyć dokonując potwierdzenia płatności (zapytanie "complete", skutkujące zmianą statusu płatności na "executed") lub anulowania/wycofania (zapytanie "DELETE", skutkujące zmianą statusu płatności na "reversed").

  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ż 1-2 tygodnie.

  Przykład z wykorzystaniem CURL

  curl -H 'Accept: application/vnd.espago.v3+json' -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 -H 'Accept: application/vnd.espago.v3+json' -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 -H 'Accept: application/vnd.espago.v3+json' -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 -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/charges -u app_id:password

  Przykład z wykorzystaniem CURL i dodatkowych parametrów

  curl -H 'Accept: application/vnd.espago.v3+json' -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 nowej transakcji pojedynczej", "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 cyklicznej", "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_xj8Hfr2-jHdf83HHa", "subscription":"sub_aaNbjskjhakJj", "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 (poniędzy godziną 22:30 a 00:00). Po tym czasie możliwy jest jedynie ich zwrot (refund).
  Uwaga!
  Wycofanie płatności jest również sposobem na anulowanie preautoryzacji, w ten sposób na koncie bankowym klienta szybciej zniknie rezerwacja środków. Wycofanie preautoryzacji może zostać dokonane w ciągu kilku/kilkunastu dni od dnia dokonania preautoryzacji.
  W przypadku gdy płatnosć została już rozliczona w Elavon (w banku) próba wycofania płatności nie powiedzie się.
   

  Przykład z wykorzystaniem CURL

  curl -H 'Accept: application/vnd.espago.v3+json' -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 adres https://sandbox.espago.com/api/charges/(:id)/refund gdzie (:id) jest to identyfikator płatności, która ma zostać wycofana i zwrócona

  Zwrócić można całą kwotę z transakcji lub część. Nie ma możliwości wycofania dokonanego zwrotu.

  Płatność można zwrócić w czasie maksymalnie 12 miesięcy od jej wykonania.

  W przypadku zwrotu części płatności możliwe jest wielokrotne zwracanie płatności do momentu zwrócenia całej kwoty pierwotnej płatności. Kwotę już zwróconą podaje parametr refunded_amount. Aby zwrócić całość płatności już częściowo zwróconej można zwrócić wyliczoną wartość (do zwrócenia= amount - refunded_amount) lub wywołać zapytanie bez parametru "amount".

  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.

  Istotne elementy odpowiedzi

   

  Parametr	Opis	Uwagi
  id	id płatności	Wartość niezmieniona, ID płatności której dotyczy zwrot.
  state	status płatności	Po poprawnie wykonanym zwrocie (częściowym lub całkowitym) przyjmuje wartość "refunded"
  refunded_amount	kwota zwrócona	Przy zwrocie całkowitym refunded_amount=amount. Przy częściowych zwrotach płatności, refunded_amount jest sumą dokonanych zwrotów.
  transaction_id	ID transakcji zwracającej	Jest to ID transakcji (operacji) zwracającej płatność. Różni się od ID transakcji dokonującej płatność.

   

  Przykład z wykorzystaniem CURL - bez parametrów HTTP

  curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/charges/(:id)/refund -u app_id:password -X POST

  Przykład z wykorzystaniem CURL - z parametrami HTTP

  curl -H 'Accept: application/vnd.espago.v3+json' -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", "refunded_amount":"20.00", "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", "refunded_amount":"15.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.
 

• Możliwe scenariusze

  Realizowanie cyklicznych obciążeń kart klientów możliwe jest na kilka sposobów, wśród których należy rozróżnić dwa podstawowe scenariusze.

  Uwaga! Od lipca 2019r należy przyjać za wymóg, aby subskrypcje/płatności cykliczne rozpoczynały się od płatności z 3D-Secure.

  Scenariusz	Zastosowanie	Opis
  Cykliczność realizowana po stronie Sprzedawcy (kolejne płatności na żądanie Sprzedawcy)	Gdy wysokość lub częstotliwość opłat jest zmienna. Gdy poza opłatami cyklicznymi przez klientów realizowane są również płatności jednorazowe. Gdy Sprzedawca posiada już mechanizmy zarządzające terminami płatności. Gdy Sprzedawca chce oferować szybkie zakupy dla stałych klientów (one-click payment).	Sprzedawca tworzy w bramce Espago profil klienta (z danymi karty) np. wykorzystując płatność z parametrem "cof=storing", następnie w wybranych przez siebie momentach wywołuje żądanie płatności (zapytanie na /api/charges z podaniem m.in. ID klienta) dodając informację, że jest to płatność cykliczna (parametr "recurring=true" oraz "cof=recurring"). Parametr "recurring=true" jest potrzebny w płatnościach cyklicznych/recurringowych (w nich CVV/CVC nie jest używany) ponieważ zwiększa szanse na zaakceptowanie przez bank płatności pomimo braku użycia kodu CVV/CVC. Parametr "cof=recurring" został wprowadzony przez Visę i MasterCard w 2019r, i jest uszczegółowieniem konkretnych płatności w ramach recurringu. Gdy ten scenariusz jest wykorzystywany jako oneclick payment/wielokrotne płatności na żądanie, to w żądaniach płatności (/api/charges) nie powinno być parametru "recurring=true" (dzięki temu możliwe będzie przekierowanie w ramach 3D-Secure). Warto tu również użyć Dosyłanie CVV gdyż zwiększa to bezpieczeństwo i szanse na powodzenie obciążenia w niektórych bankach. W przypadku realizacji tego scenariusza nie ma potrzeby zapoznawania się z następnymi rozdziałami dotyczącymi płatności cyklicznych (Konfiguracja, Plany, Scenariusze, Faktury, Pozycje faktury) gdyż dotyczą one drugiego scenariusza, w którym Espago zarządza cyklicznością.
  Cykliczność realizowana po stronie Espago	Gdy wysokość i częstotliwość opłat są stałe.	Sprzedawca początkowo definiuje w systemie Espago plan (lub wiele planów), czyli schemat płatności cyklicznych określający okres oraz wysokość opłaty. Następnie dla każdego swojego klienta Sprzedawca tworzy profil klienta z danymi karty (np. przez płatność z użyciem tokenu i parametrem "cof=storing") i uruchamia dla niego subskrypcję. W momencie utworzenia subskrypcj następuje pierwsza próba obciążenia, jeśli ona się powiedzie subskrypcja zostaje uruchomiona, a następne obciążenie będzie miało miejsce po zdefiniowanym w planie okresie. Każda próba obciążenia generuje wysłanie do serwisu Sprzedawcy informacji zwrotnej (back-request) ze statusem płatności. Ten scenariusz jest opisany w następnych rozdziałach (Konfiguracja, Plany, Subskrypcje itd)

  • Problem kart nienadających się do płatności cyklicznych

    Większość kart płatniczych nadaje się do jednorazowych płatności Internetowych oraz cyklicznych (o ile ich właściciele włączą w swoim banku obsługę tych płatności i ustawią odpowiednie limity kwotowe). Istnieje jednak część kart, którymi można dokonać jednorazowych płatności internetowych, ale które nienadają się do płatności cyklicznych. Przykładami takich kart są karty Maestro oraz część kart wydana przez banki PKO S.A. oraz Bank PEKAO.

    W normalnym scenariuszu (utworzenie klienta, utworzenie subskrypcji wraz z pierwszym obciążeniem) mogła by więc nastąpić sytuacja, gdzie w momencie utworzenia zamówienia/subskrypcji udaje się obciążyć klienta, a później (w ramach płatności cyklicznych) już nie. Jest to zjawisko niewygodne zarówno dla Sprzedawcy jak i Klienta.

    Aby uniknąć tego problemu warto rozważyć scenariusz opisany poniżej.

    Bardzo istotne jest również, aby wszystkie transakcje cykliczne i wielokrotne (w których nie jest już używany kod CVV/CVC) były oznaczone parametrem "recurring=true". Część banków ma politykę odrzucania transakcji internetowych bez CVV, przy jednoczesnym akceptowaniu transakcji oznaczonych jako "recurring" bez CVV.

    Obsługa Espago może również ustawić aby wszystkie płatności Sprzedawcy były widziane przez bank jako cykliczne, wtedy nie ma potrzeby dodawania tego parametru każdorazowo. Takie ustawienie uniemożliwia jednak w danym serwisie wykonywanie jednorazowych płatnosci z wykorzystaniem np. 3D-Secure lub DCC.

    Krok	Działanie	Opis
    1	Utworzenie klienta	Sprzedawca tworzy w bramce Espago profil klienta (z danymi karty).
    2	Autoryzacja klienta	Autoryzacja na żądanie lub automatyczna autoryzacja podczas tworzenia klienta (można ją włączyć w panelu WWW). POWODZENIE:: karta obsługuje płatności internetowe, można przejść do kroku 3. NIEPOWODZENIE: karta nie obsługuje płatności internetowych, więc na pewno nie uda się kolejna próba obciążenia [1]* [3]*.
    3	Utworzenie subskrypcji / Obciążenie klienta w ramach pierwszej opłaty / Druga autoryzacja	Utworzenie subskrypcji (z automatyczną pierwszą płatnością) lub pierwsze żądanie obciążenia klienta (w przypadku cykliczności realizowanej po stronie Sprzedawcy) lub drugie przeprowadzenie autoryzacji (w przypadku gdy Sprzedawca chce tylko sprawdzić działanie karty, bez jej obciążania). POWODZENIE: karta obsługuje płatności internetowe i cykliczne. Kolejne obciążenia najprawdopodobniej się powiodą [2]*. NIEPOWODZENIE: karta nie obsługuje płatności cyklicznych, więc na pewno nie powiodą się kolejna próby obciążenia [1]*.

    [1]* Jeżeli powodem odrzucenia jest nieobsługiwanie płatności internetowych/MOTO przez kartę lub zbyt niskie limity, to po włączeniu tych płatności/ustawieniu wyższych limitów przez właściciela karty kolejne płatności mogą być dokonane z powodzeniem.

    [2]* W przypadku gdy klient nie będzie posiadał środków pieniężnych na koncie/karcie lub ważność karty wygaśnie wykonanie płatności przestanie być możliwe.

    [3]* W przypadku gdy przyczyną odrzucenia autoryzacji będzie niepoprawny kod CVV/CVC (kod odrzucenia: 75, 82, N7) nie należy dokonywać więcej obciążeń tej karty! Takie odrzucenie może wynikać z użycia kradzionej karty (fraud). Następne obciążenia mogą zostać zaakceptowane przez bank ze względu na brak (niepoprawnego) CVV, ale odbywa się to na odpowiedzialność Sprzedawcy.

  • Zasady i dobre praktyki płatności cyklicznych

     

    Działanie	Opis/Komentarz
    Przed rozpoczęciem subskrypcji (lub jako pierwsza płatnosć subskrypcji) klient powinien dokonać płatności/preaturyzacji z 3D-Secure.	Płatność z 3D-Secure znacząco zwiększa pewność, że klient jest właścicielem karty. Od września 2019r. część banków może odrzucać płatności cykliczne, jeśli przed nimi nie było płatności 3D-Secure.
    Należy ograniczać do minimum powtarzanie nieudanych płatności, szczególnie gdy klient ma kilka zaległych płatności.	Visa zaleca (w przyszłości może to być wymóg), aby unikać sytuacji, gdy kilka zaległych płatności klienta skutkuje w wielokrotnym powtarzaniu wielu płatności. Nie powinno następować więcej niż 1 próba pobrania zaległej płatności na dzien. W praktyce jeśli klient zalega z wieloma płatnosciami, to jeśli próba jednej (np. z najniższą kwotą) się nie powiedzie to inne też zostają odrzucone.
    Używać preautoryzacji jeśli spodziewamy się, że kwota będzie zwrócona, lub docelowe obciążenie będzie tylko na część kwoty preautoryzacji. Unikać preautoryzacji jeśli nie jest ona konieczna.	Preautoryzacja umożliwia blokadę środków, bez jej pobrania. W zależnosci od umowy z Elavon Visa/MasterCard mogą pobierać stałą, drobną opłatę za każdą preautoryzację (poza prowizją od wykonanej płatności).

     

     

• Konfiguracja

  Po uzyskaniu dostępu do panelu merchanta należy wykonać następujące czynności:

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

     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 definiują schemat płatności cyklicznych, zawierają informacje o wysokości i częstotliwości obciążeń. Na podstawie zdefiniowanych Planów następnie będzie można uruchamiać dla klientów subskrypcje.

  Tworząc plan ustala się takie dane jak: typ okresu obciążenia (np. day, month), wartość okresu obciążenia (w przypadku typu okresu period=7 oraz period_unit=day uzyskujemy cykliczność obciążania co 7 dni) oraz kwota pojedyńczego obciążenia. 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, 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 -H 'Accept: application/vnd.espago.v3+json' -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":1550871586 }

  • 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 -H 'Accept: application/vnd.espago.v3+json' -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) -H 'Accept: application/vnd.espago.v3+json' -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! W związku z tym, dla utrzymania porządku sugerujemy nie korzystać z aktualizacji planu, a tworzyć nowe plany.

    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 -H 'Accept: application/vnd.espago.v3+json' -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

  Subskrypcja (abonament) jest to przypisanie planu do klienta.

  Domyślnie subskrypcja działa od momentu jej uruchomienia (generowana jest wtedy pierwsza płatność), i jej kolene płatności są wywoływane z okresem zdefiniowanym w użytym Planie. Godzina wywołania kolejnych płatnosci jest zbliżona do godziny utworzenia subskrypcji (płatność może zostać wywołana max 4h późńiej).

  Subskrypcja jest zatrzymywana gdy:

  • pierwsza płatnosć się nie powiedzie (czyli subskrypcja tak na prawdę nie jest w ogóle uruchamiana)
  • Sprzedawca wyśle żądanie zatrzymania subskrypcji,
  • nastąpi trzykrotna nieudana próba obciążenia w ramach jednego cyklu (jeżeli zatrzymanie subskrypcji w takiej sytuacji zostało skonfigurowane w panelu www).

  Istnieje również uruchomienie subskrypcji z opóźnionym startem (tzn. ze zdefinowaną datą pierwszego obciążenia). W takiej sytuacji nie ma automatycznego mechanizmu dezaktywującego subskrypcję w przypadku odrzucenia pierwszej płatności.

  • 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	Uwagi
    client	ID klienta	Parametr wymagany
    plan	ID planu	Parametr wymagany
    start_time	Moment uruchomienia subskrypcji	Parametr opcjonalny. Domyślnie (bez parametru start_time) subskrypcja jest uruchamiana w momencie wywołania żądania. Parametr wymaga wartości czasu w formacie unix pomiędzy: 12h po zapytaniu oraz przed czasem zdefioniowanym jako kolejne wywołanie (period). Szczegóły w następnym rozdziale.

    Przykład z wykorzystaniem CURL

    curl -H 'Accept: application/vnd.espago.v3+json' -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 Żądania zwrotne) 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.

  • Tworzenie nowej subskrypcji z opóźnionym startem

    Isnieje możliwość utworzenia subskrypcji, której start (pierwsze obciążenie) nastąpi w zadeklarowanym przez Sprzedawcę momencie. Aby uruchomić subskrypcję z opóźnionym startem należy w zapytaniu tworzącym subskrypcję przesłać parametr start_time z odpowiednią wartością (opis wyżej).

    • Jest to opcja przydatna np. w celu realizacji początkowego darmowego okresu.
    • Po uruchomieniu subskrypcji z opóźnionym startem działa ona tak jak zwykła subskrypcja.
    • Możliwe jest zatrzymanie subskrypcji zanim nastąpi pierwsze wywołanie.

    Subskrypcja z opóźnionym startem posiada pewne ograniczenia:

    • W momencie tworzenia subskrypcji nie ma pierwszej próby płatności, a co za tym idzie nie ma mechanizmu dezaktywującego subskrypcję w przypadku odrzucenia pierwszej płatności. Możliwe jest więc uruchomienie subskrypcji dla karty, której nie da się obciążyć, gdyż np. nie obsługuje płatności internetowych i/lub cyklicznych.
    • Aby uniknąć powyższego problemu, Sprzedawca powinien upewnić się wcześniej czy karta obsługuje płatności cykliczne.
    • Data i godzina uruchomienia subskrypcji zdefiniowana w parametrze start_time musi być później niż 12 godzin po wywołaniu zapytania, oraz wcześniej niż po czasie zdefiniowanym jako okres subskrypcji (planu).

  • 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 -H 'Accept: application/vnd.espago.v3+json' -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) -H 'Accept: application/vnd.espago.v3+json' -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

     

    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 -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/subscriptions -u app_id:password

    Przykład z wykorzystaniem CURL i parametrów dodatkowych

    curl -H 'Accept: application/vnd.espago.v3+json' -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 -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/clients/(:client_id)/subscriptions -u app_id:password

    Przykład z wykorzystaniem CURL i parametrów dodatkowych

    curl -H 'Accept: application/vnd.espago.v3+json'  -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 -H 'Accept: application/vnd.espago.v3+json' -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 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 -H 'Accept: application/vnd.espago.v3+json' -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 -H 'Accept: application/vnd.espago.v3+json' -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 -H 'Accept: application/vnd.espago.v3+json' -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

    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 -H 'Accept: application/vnd.espago.v3+json' -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 -H 'Accept: application/vnd.espago.v3+json' -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 -H 'Accept: application/vnd.espago.v3+json' -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 umożliwiają bezpieczne przesłanie danych karty bezpośrednio z urządzenia klienta (przeglądarka internetowa, urządzenie mobilne) do bramki Espago, z pominięciem systemu Sprzedawcy. Tokeny zawierają tylko dane karty, mogą następnie być użyte przez Sprzedawcę do dokonania płatnosci lub utworzenia profilu klienta.

Przy integracji z API konieczne jest wykorzystanie skryptu EspagoFrame (preferowane) lub Espago.js. Zadaniem skryptów jest przechwycenie i przesłanie danych kart bezpośrednio z przeglądarki/urządzenia klienta i przesłanie ich do Bramki Espago, oraz otrzymanie ID tokenu.

Gdy dane karty mają być podawane z aplikacji mobilnej sugerowanym rozwiązaniem jest uzycie WebView, ale możliwe jest również osadzenie formularza w aplikacji zgodnie z poniższymi wymaganiami. W przypadku implementacji w aplikacji mobilnej prosimy o kontakt z działem wsprarcia technicznego Espago.

• Schemat wykorzystania tokenów

  

   

  1. Klient wchodzi na stronę Sprzedawcy. Przeglądarka klienta automatycznie pobiera na swoje urządzenie skrypt EspagoFrame lub Espago.js z serwera Espago. Skrypt tworzy formularz, który wyodrębnia się na stronie Sprzedawcy a który jest zabezpieczony przez https (TLS). Pobrany przez posiadacza karty skrypt wywołany jest z użyciem klucza publicznego, który identyfikuje Sprzedawcę w bramce Espago. Dane karty muszą zostać zawarte w polach z parametrami "id". Formularz może zawierać pola zdefiniowane i używane przez Sprzedawcę. Skrypt Espago.js usuwa dane karty z formularza w przeglądarce klienta po wysłaniu danych bezpośrednio na serwer Espago.
  2. Gdy Klient klika "Wyślij", skrypt EspagoFrame lub Espago.js przesyła dane karty do bramki Espago, wysyłając żądanie na adres /api/tokens. Jeśli klient poda niepoprawne dane skrypt Espago nie pozwala na wysłanie danych i wyświetla informacje o tym które pole jest niepoprawnie uzupełnione.
  3. Bramka Espago odbiera dane karty, tworzy token i odsyła jego ID w odpowiedzi do przeglądarki klienta.
  4. Formularz jest przesyłany do serwisu Sprzedawcy według akcji formularza zdefiniowanej przez Sprzedawcę. Token karty jest przesyłany jako parametr "card_token" i ma wartość w postaci "cc_xxxxxxxxxx".
  5. Aplikacja Sprzedawcy wysyła do Espago żądanie żądanie dokonania płatności (zapytanie na /api/charges) lub utworzenia profilu klienta (zapytanie na /api/clients) przesyłając ID tokenu odebrane od klienta.
  6. Bramka Espago odpowiada na zapytanie, przesyłając dane utworzonej płatności lub/i profilu klienta. W przypadku utworzenia profilu klienta należy w swojej bazie zapisać przynajmniej ID klienta, w celu późniejszego obciążania. ID tokenu nie będzie już więcej potrzebne.

• EspagoFrame

  Skrypt EspagoFrame pozwoli wyświetlić na stronie okienko iframe, w którym klient będzie mógł podać dane karty. Następnie te dane zostaną przesłane do Espago, a skrypt zwórci do strony ID tokenu, który można użyć do płatności lub utworzenia profilu klienta.

  Działanie

  Po wywołaniu formularza i podaniu danych karty przez płatnika, skrypt wysyła je bezpośrednio do serwera Espago. W przypadku utworzenia tokenu, skrypt domyślnie szuka na stronie z której został wywołany formularza o identyfikatorze "espago_form"  <form id="espago_form">  i dodaje w nim pole input typu hidden o identyfikatorze "card_token" i wartości tokenu:

  <input type="hidden" id="card_token" name="card_token" value="cc_xxxxxxxxxxxxx">

  Działanie to można zmienić, wskazując parametr data-target lub data-success w wywołaniu iframe, o czym wspomniano w tabeli poniżej.

  Obsługa błędów

  Jeżeli skrypt wywoła wyświetlenie iframe, ale nastąpi problem w komunikacji z serwerem Espago, np. ze względu na brak obsługi TLS w wersji wyższej niż TLS 1.0 przez urządzenie klienta, zostanie klientowi wyświetlony ogólny komunikat błędu.

  W celach debugowania należy jednak skorzystać z opcji przekazania jako parametr data-error (opisany w tabeli poniżej) własnej funkcji, do której zostanie zwrócony komunikat błędu, np. 401 błąd autoryzacji - w przypadku podania błędnego klucza publicznego.

   

  Jeżeli formularz płatności ma być osadzony wewnątrz Państwa strony to użycie rozwiązania Espago iFrame lub Espago JS jest obowiązkowe. Odpowiedni skrypt musi być pobierany przez przeglądarkę klienta bezpośrednio z serwera Espago (nie należy go umieszczać i hostować na własnym serwerze).

  • Demo działania Espago iFrame

    Kliknij "Dodaj kartę" to aby uzysktać nowy token
    
    Dodaj kartę

     

    Demo dostępne także testowym sklepie Espago: https://warzywko.espago.com/?locale=pl

  • Opis parametrów

    Ważne:

    Parametry: `async`, `data-id` oraz `src` muszą pozostać niezmienione.

     

    Parametr	Obligatoryjność	Wartości domyślne	Znaczenie
    data-key	obowiązkowy		String, Klucz publiczny Merchanta
    data-live	opcjonalny	true	String, Wskazuje czy formularz ma być wysyłany do środowiska produkcyjnego. Wartość 'true' oznacza wysyłanie danych na środowisko produkcyjne, wartość 'false' na środowisko testowe.
    data-lang	opcjonalny	pl	String, Język w jakim będzie wyświetlony formularz w standardzie ISO 639-1. Dostępne: da, de, en, et, fr, it, lt, lv, pl, ru, sv.
    data-success	opcjonalny	function(data) {}	Funkcja callback wywoływana w przypadku, gdy token zostanie wygenerowany. Uwaga, podanie funkcji callback wyłącza domyślne działanie skryptu - pole 'card_token' nie zostanie dołączone do formularza. data - string; wygenerowany token z bramki Espago.
    data-error	opcjonalny	function(data) {}	Funkcja callback wywoływana w przypadku, gdy token nie zostanie wygenerowany.  data - string; kod błędu otrzymany z bramki Espago wraz z opisem.
    data-onclose	opcjonalny	function() {}	Funkcja wywoływana w przypadku, gdy użytkownik zamknie okno dialogowe (klikając "x" lub klawisz "Esc").
    data-target	opcjonalny	espago_form	Nazwa formularza do którego zostanie dodane ukryte pole 'card_token' o wartości tokenu. Uwaga - w przypadku gdy zostanie podany parametr 'success_callback' akcja ta nie wykona się. Token zostanie przekazany do tej funkcji.
    data-title	opcjonalny	Dodaj swoją kartę (pl)	Nagłówek wyświetlany na górze formularza. Uwaga - domyślna wartość jest zależna od parametru języka 'data-lang'
    data-subtitle	opcjonalny		Tekst wyświetlany poniżej nagłówka i nazwy sklepu (pobranej automatycznie z API Espago)
    data-button	opcjonalny	Zapisz (pl)	Etykieta tekstowa wyświetlona na przycisku zatwierdzania formularza. Uwaga - domyślna wartość jest zależna od parametru języka 'data-lang'

  • iFrame przykładowy kod

    Przykładowy kod (konfiguracja minimalna)

    <script async=""
      data-id="EspagoFrameScript"
      data-key="ooaY3nNkCnf7qtSRp7wD"
      src="https://js.espago.com/iframe-1.0.js">
    </script>

     

    Przykładowy kod (konfiguracja pełna)

    <script async=""
      data-id="EspagoFrameScript"
      data-key="ooaY3nNkCnf7qtSRp7wD"
      data-live="false"
      data-lang="en"
      data-success="my_success_callback"
      data-error="my_error_callback"
      data-onclose="my_onclose_callback"
      data-target="my_form"
      data-title="Add Your Card"
      data-subtitle="It's safe!"
      data-button="Save Card"
      src="https://js.espago.com/iframe-1.0.js">
    </script>

      

     

    Aby wyświetlić zawartość Espago iframe należy wywołać poniższą funkcję.

    showEspagoFrame();

     

    Przykładowy skrypt wywołujący akcję wyświetlenia zawartości Espago iframe po kliknięciu elementu strony o id 'addCard' (np. przycisku formularza).

    <script>
      document.getElementById('addCard').addEventListener('click', (function(event) {
        showEspagoFrame();
      }), true);
    </script>

     

    Przykładowe funkcje wywołania zwrotnego (callback), do których przekazywany będzie token (w przypadku pomyślnego wygenerowania tokenu), komunikat błędu (w przeciwnym wypadku) lub bezpośrednio w przypadku gdy użytkownik zamknie okno dialogowe.

    <script>
      my_success_callback = function(token) {
        return console.log('Great! My token is: ' + token);
      };
    
      my_error_callback = function(error_message) {
        return console.log('Something went wrong: ' + error_message);
      };
    
      my_onclose_callback = function() {
        return console.log('User closed modal.');
      };
    
    </script>

  • Migracja z Espago.JS do Espago iframe.JS

    Aby dokonać migracji z integracji przy wykorzystaniu skryptu espago.js należy:

    1. usunąć wszystkie pola formularza odpowiadające za podawanie danych karty kredytowej stosowane dotychczas;
    2. usunąć skrypt wywołujący konstruktor Espago i korzystający z metody create_token();
    3. następnie należy zastosować minimalne lub rozwinięte wywołanie ramki Espago iframe zaprezentowane powyżej https://developers.espago.com/pl/v3#366-iframe-przykladowy-kod.

• Przykładowy formularz zbudowany w oparciu o Espago JS wykorzystujący metody walidacji

  Na stronie do pobrania dostępny jest najnowszy przykładowy formularz wykorzystujący skrypt JS z biblioteką jQuery.

  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.

• 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/espago-1.2.js

  Jeżeli formularz płatności ma być osadzony wewnątrz Państwa strony to użycie skryptu https://js.espago.com/espago-1.2.js 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/espago-1.2.js 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' 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

  • Demo online

    https://github.com/espago/espago-1.2.js-demo

• Pobieranie danych o tokenie

  [Zdecydowana większość integracji/Sprzedawców nigdy nie będzie potrzebowała tego zapytania, gdyż dane karty (z tokenu) zostaną zwrócone w zapytaniu o płatność lub utworzenie klienta.]

  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 -H 'Accept: application/vnd.espago.v3+json' -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":"John", "last_name":"Kowalsky", "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 -H 'Accept: application/vnd.espago.v3+json' -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]=2018" -d "card[month]=02" 

  Przykładowa odpowiedź

  { "id":"cc_J_wDRKH6jmIEb_8", "created_at":1550871516, "used":false, "card":{ "company":"VI", "last4":"4242", "year":2018, "month":2, "first_name":"John", "last_name":"Kowalsky", "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.

• Komunikat: 'unsuccessful authetication please check your public key' podczas rejestrowania karty

  Podany błąd może wystąpić w dwóch przypadkach:
  1. Przy faktycznie błędnie podanym kluczu publicznym skryptu Espago.js, wykorzystywanego do rejestracji karty w systemie.
  2. Przy braku poprawnego połączenia z serwerem espago.com.
     • Spowodowanego brakiem połączenia internetowego (np. chwilowego), co uniemożliwia poprawne wysłanie zapytania i uwierzytelnienia.
     • Spowodowane błędnym blokowaniem przez program antywirusowy połączeń wysyłanych w tle. Aby to przetestować należy wyłączyć na chwilę program antywirusowy i spróbować przeprowadzić podawanie danych karty. Jeśli problem zniknie włączyć ponownie ochronę antywirusową oraz dostosować poprawnie ustawienia bezpiecznego przeglądania sieci.

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.

Możliwe jest utworzenie profilu klienta bez danych karty (tylko z opisem, e'mailem) w celu późniejszego uzupełnienia danych karty, ale rzadko ma to zastosowanie.

W panelu WWW jest możliwość włączenia i wyłączenia automatycznej autoryzacji klienta podczas jego utworzenia. Po włączeniu tej opcji, podczas tworzenia profilu klienta nastąpi autoryzacja karty (obciążenie oraz zwolnienie kwoty 1PLN w celu sprawdzenia czy karta obsługuje płatności internetowe), i w odpowiedzi na na utworzenie klienta zostanie zwrócony odpowiedni status parametru "authorized" (szczegóły poniżej w częśći "Opis i możliwe wartości parametrów authorized i company".

Uwaga! Od lipca 2019r sugerowanym sposobem tworzenia profilu klienta jest zapytanie o płatnosć (/api/charges) z 3D-Secure oraz parametrem "cof=storing". Pozostałe operacje (modyfikacja, aktualizacja, testowanie karty) funkcjonują bez zmian.

• 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	Parametr przekazujący ID tokenu do karty	W tym parametrze należy podać ID wcześniej utworzonego tokenu do karty.	Opcjonalny/obowiązkowy*. Jeżeli klientowi mają być przypisane dane karty to muszą one być przekazane przy użyciu tokenu.
  card[first_name]	Imię właściciela karty		Opcjonalne/testowe*. Możliwe jest utworzenie klienta przesyłając w zapytaniu dane karty. W tym przypadku konieczne jest uzupełnienie wszystkich parametrów. Możliwe jest utworzenie klienta pozbawionego danych karty, ale na ogół nie ma uzasadnienia by tak robić.
  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

  Uwaga:
  Ze względów bezpieczeństwa przekazywanie danych karty przy użyciu Tokenów jest preferowanym rozwiązaniem. Przesyłanie kompletu danych w zapytaniu może być wykorzystane tylko do testów oraz w specyficznych zastosowaniach w środowisku produkcyjnym (prosimy o kontakt z Espago).

   

  Przykład z wykorzystaniem CURL

  curl -H "Accept: application/vnd.espago.v3+json" -i https://sandbox.espago.com/api/clients -u app_id:password -d "description=Jan Kowalski" -d "email=jan.k@example.com" -d "card=token_id"
  

  curl -H "Accept: application/vnd.espago.v3+json" -i https://sandbox.espago.com/api/clients -u app_id:password -d "description=Description" -d "email=client@example.com" -d "card[first_name]=John" -d "card[last_name]=Kowalski" -d "card[number]=4242424242424242" -d "card[year]=2019" -d "card[month]=02" -d "card[verification_value]=123"
  

  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 }

   

  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.

• Atrybuty profilu klienta i karty

  Profil klienta jest obiektem posiadającym zestaw parametrów. Są one zwracane zaraz po utworzeniu klienta, a także dostępne później przy odpytaniu o klienta lub jego płatnosci.

  Opis i możliwe wartości parametrów karty w profilu klienta:

  Parametr	Wartość	Opis
  company	VI, MC, MD	Informacja o wystawcy karty: VI - Visa, MC - MasterCard, MD - Maestro, AX - American Express, DC - Diners Club, JC - JCB, SW - Switch, SO - Solo, LA - Laser. UWAGA: najczęściej umowa z Elavon obejmuje tylko karty Visa i MasterCard, dlatego w większości przypadków wystarczające jest rozróżnianie wartości: VI, MC, MD.
  authorized	null, true, false	Zwraca informację o ostatniej 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
  authorized_cvv_cvc	null, true, false	Parametr dostępny przy wykorzystaniu funkcji podwójnej autoryzacji. Zwraca informację o pierwszej autoryzacji karty, gdy kod CVV/CVC był użyty. Przyjmuje wartości logiczne takie jak parametr "authorized".
  issuer_response_code	(dwa znaki)	Jeśli authorized=false, to ten parametr będzie zawierał kod odrzucenia przez bank (issuer_response_code)
  created_at	(numer)	Czas w formacie uniksowym

• 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 -H 'Accept: application/vnd.espago.v3+json' -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ć.

  W zapytaniu należy przesłać parametry podobnie jak ma to miejsce przy tworzeniu klienta.

  Uwaga!
  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ęść. Podobnie jak przy tworzeniu klienta preferowanym rozwiązaniem jest użycie ID Tokenu (utworzonego przed wysłaniem żądania aktualizacji klienta).
  Uwaga!
  Po aktualizacji danych karty nie ma możliwości przywrócenia starej karty. Jeśli chcesz umożliwić podanie nowej karty tylko w przypadku gdy będzie działać, i dopiero wtedy usuwać starą kartę to zamiast aktualizacji karty rozważ utworzenie nowego profilu klienta i następnie usunięcie starego.
  Uwaga!
  Jeśli w ustawieniach serwisu jest włączona opcja "automatycznej autoryzacji karty klienta przy jego tworzeniu" to przy aktualizacji karty zostanie również przeprowadzona próba autoryzacji, jej rezultatem będzie zaktualizowany parametr "authorized" oraz "issuer_response_code" w profilu klienta. Jeśli opcja automatycznej autoryzacji nie jest włączona, to po aktualizacji danych karty parametr authorized przyjmie wartość "null".

  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	Parametr przekazujący ID tokenu do karty	W tym parametrze należy podać ID wcześniej utworzonego tokenu do karty.	Opcjonalny/obowiązkowy*. Jeżeli klientowi mają być przypisane dane karty to muszą one być przekazane przy użyciu tokenu.
  card[first_name]	Imię właściciela karty		Opcjonalne/testowe*. Możliwe jest utworzenie klienta przesyłając w zapytaniu dane karty. W tym przypadku konieczne jest uzupełnienie wszystkich parametrów. Możliwe jest utworzenie klienta pozbawionego danych karty, ale na ogół nie ma uzasadnienia by tak robić.
  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

   

  Przykład z wykorzystaniem CURL

  curl -H 'Accept: application/vnd.espago.v3+json' -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]=2018" -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":2018, "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).

  W panelu WWW istnieje możliwość włączenia automatycznej autoryzacji przy tworzeniu profilu klienta. W takiej sytuacji, informacja o przeprowadzonej autoryzacji jest widoczna już w odpowiedzi na żądanie utworzenia (i aktualizacji) profilu klienta.

  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 -H 'Accept: application/vnd.espago.v3+json' -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

   

  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 -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/clients -u app_id:password

  Przykład z wykorzystaniem CURL i dodatkowych parametrów

  curl -H 'Accept: application/vnd.espago.v3+json' -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

• Sprawdzenie informacji o karcie: kraj, bank, rodzaj.

  Sprawdzenie informacji dot. karty klienta na żądanie następuje w wyniku wysłania żądania typu POST na adres https://sandbox.espago.com/api/clients/(:id)/check_type

  (:id) - identyfikator klienta, którego dane mają zostać sprawdzone.

  Sprawdzenie informacji pozwala na sprawdzeniu i przypisaniu do danej karty informacji dotyczących:

  • kraju wystawcy karty
  • nazwy banku
  • rodzaju karty

  Sprawdzenie informacji o karcie może trwać do kilku sekund, co może wiązać się wolniejszą odpowiedzią API. Ten sam problem może wystąpić przy tworzeniu profilu klienta, gdy jest włączone automatyczne sprawdzenie informacji na temat jego karty.

  Opis i możliwe wartości parametrów:

  Parametr	Opis	Uwagi
  card_type	Informacja o rodzaju karty	C - karta kredytowa D - karta debetowa U - brak informacji
  country	Kraj wystawcy karty	3 literowy skrót, ISO_3166-1_alfa-3 U - brak informacji
  bank	Nazwa banku	Nazwa banku U - brak informacji

   

  Przykład z wykorzystaniem CURL

  curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/clients/(:id)/check_type -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, "card_type": "C", "country": "POL", "bank": "POWSZECHNA KASA OSZCZEDNOSCI BANK POLSKI S.A. (PKO BANK", "created_at":1381825758 }, "deleted":false }

• Aktualizacja danych klienta tylko gdy karta jest zautoryzowana

  Aby zaktualizować istniejącego klineta należy wysłać zapytanie PUT na adres: https://sandbox.espago.com/api/clients/(:id)/update_if_authorized

  (:id) - ID wybranego Klienta

  Zapytanie powinno zawierać parametry podobne do tych podczas tworzenia klienta. Dane klienta zostaną zaktualizowane tylko wtedy, gdy jego nowa karta nadaje się do płatności internetowych oraz cyklicznych

  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	Parametr przekazujący ID tokenu do karty	W tym parametrze należy podać ID wcześniej utworzonego tokenu do karty.	Obowiązkowy. Jeżeli klientowi mają być przypisane dane karty to muszą one być przekazane przy użyciu tokenu.

   

  Przykład z wykorzystaniem CURL

  curl -i https://sandbox.espago.com/api/clients/(:ID)/update_if_authorized -X PUT -H "Accept: application/vnd.espago.v3+json" -u app_id:password -d "card=token_id"

  Przykładowa odpowiedź gdy karta nadaje się do płatności internetowych

  {"updated":true, "client": { "email":"jan@kowalski.com", "id":"cli_Yzij0t46pV88oR", "created_at":1381825758, "description":"Jan Testowy", "card":{ "company":"VI", "last4":"4242", "year":2017, "month":2, "first_name":"Jan", "last_name":"NewCard", "authorized":true, "authorized_cvv_cvc":true, "created_at":1473846327 }, "deleted":false }}

  Przykładowa odpowiedź gdy karta nie nadaje się do płatności internetowych

  Parametr "updated=false" informuje o tym, że karta w profilu klienta nie zostaje zaktualizowana, a parametr "issuer_response_code" podaje przyczynę odrzucenia nowej (nie umieszczonej w profilu klienta) karty. W celu uzyskania szczegółów dotyczących odrzucenia można odpytac bramkę o użyty do aktualizacji token.

  W odpowiedzi zawarty jest również obiekt profilu klienta, z starą (tzn. nie zmienioną) kartą.

  {"updated":false,"used_token":{"id":"cc_u82KaO3rToQx9hl","created_at":1476101947,"used":true,"card":{"company":"VI","last4":"4242","year":2018,"month":2,"first_name":"Jan","last_name":"NewCard","authorized":null,"authorized_cvv_cvc":false,"issuer_response_code":"13","created_at":1476101947}},"client":{"email":"","id":"cli_MNXfMFpu8_j3ax","created_at":1457384233,"description":"Description","card":{"company":"MC","last4":"1258","year":2019,"month":1,"first_name":"Jan","last_name":"OldCard","authorized":true,"authorized_cvv_cvc":true,"issuer_response_code":"00","created_at":1476099483},"deleted":false}}

• Bezpieczna strona do tworzenia i aktualizacji karty klienta

  Istnieje możliwość przekierowania Klienta na stronę Espago w celu utworzenia profilu klienta lub aktualizacji danych jego karty w tym profilu. Są to przydane opcje w sytuacji gdy z jakiegoś powodu Sprzedawca nie chce aby Klient podawał dane karty pozostając na stronie sprzedawcy (czyli przy wykorzystaniu Espago JS lub iFrame).

  Dodatkowo przy użyciu parametrów "check" i "store" można zadeklarować sytuacje w jakich aktualizacja ma mieć miejsce, aby wykluczyć sytuację w której Klient nadpisuje działającą kartę nową, nie obsługującą płatnosci cyklicznych lub bez środków.

  Aby stworzyć "client_card_page"  - bezpieczną stronę, gdzie Klient może zostać przekierowany aby bezpiecznie przekazać dane karty - należy wysłać zapytanie POST na następujący adres API:

   https://sandbox.espago.com/api/clients/card_page 

  a następnie przekierować klienta na adres podany w odpowiedzi.

  Parametry HTTP

  Parametr	Opis	Komentarz	Wymagane?
  client	Id klienta	jeśli jest podany, ten parametr powinien zawierać ID klienta utworzonego wcześniej
  client[description]	Opis/nazwa klienta	Musi zawierać przynamniej 5 znaków	Wymagane dla utworzenia nowego klienta podczas tworzenia linku do strony aktualizacji karty
  card[email]	Adres e-mail klienta	Nie jest wymagany, ale konieczny jeżeli Espago ma powiadamiać klienta o statusie jego płatności
  store	Informacja kiedy karta ma być zapisana: all || ecommerce || recurring	Możliwe wartości:  - all - zapisuje każdą kartę podaną  - ecommerce - zapisuje tylko gdy karta nadaje się do płatności internetowych  - recurring - zapisuje gdy karta nadaje się do płatności cyklicznych	Nie jest wymagane, domyślnie all (zapisuje wszystkie karty)
  check	Informacja jak testować kartę klienta: nothing || ecommerce || recurring	Możliwe wartości: - nothing - nic - ecommerce - sprawdź czy karta nadaje się do płatności internetowych - recurring - sprawdź czy karta nadaje sie do płatności cyklicznych	Nie jest wymagane. Jeżeli serwis ma włączoną opcję"automatycznej autoryzacji klienta podczas jego utworzenia" (więcej informacji #259) to "check" jest domyślnie ustawiony jako "recurring". W przeciwnym wypadku jako "nothing".
  positive_url	Adres URL, na który klient ma być przekierowany po zapisaniu danych karty.		Nie jest wymagane
  negative_url	Adres URL, na który klient ma być przekierowany gdy zrezygnuje lub gdy wystąpi błąd.		Nie jest wymagane
  title	Krótki opis, w jakim celu ta karta jest podawana - wyświetlony zostanie na stronie.	Przynajmniej 5 znaków	Nie jest wymagane

  • Przykład z wykorzystaniem CURL

    Przykład z tworzeniem nowego klienta z kartą przygotowaną do obciążeń cyklicznych:

    curl -i https://sandbox.espago.com/api/clients/card_page -H 'Accept: application/vnd.espago.v3+json' -u app12345:Api12345 -d "client[description]=Jan Kowalski id:321" -d "client[email]=test@example.com" -d "check=recurring" -d "store=recurring" -d "title="Card for future subscription for the radio 'ABC'"

    Przykład z istniejącym klientem:

    curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/clients/card_page -u app12345:Api12345 -d "client=cli_tCwkq1uEXkEOrH"

    Przykładowa odpowiedź:

    {"id":"cpl_uUoBWsrDqtQWvD","url":"https://sandbox.espago.com/client_card_page/cpl_uUoBfsrDqtQWvD","client":"cli_KjGn9-EXahOO4i","store":"recurring","check":"recurring","valid_to":1489110032,"created_at":1489023632,"used":false,"positive_url":null,"negative_url":null}

    Teraz można także używać profil klienta - cli_tCwkq1uEXkEOrH -  tak jak normalnie - czytaj więcej.

    Parametr URL zawiera url strony client_card_page dla tego klienta - https://sandbox.espago.com/client_card_page/cpl_uUoBfsrDqtQWvD

    Taki link jest ważny 1 godzinę i wygasa po zapisaniu karty. Po zapisaniu karty,  na ostatnim ekrenie podany jest parametr finish-true, może śledzić ten adres URL w WebView w aplikacji mobilnej i zamknąć okno po utworzeniu karty.

     

Żądania zwrotne (back requests)

Odpowiedzi o zmianie statusu transakcji przychodzą asynchronicznie na zdefioniowany przez Państwa adres żądania zwrotnego (opis konfiguracji żądań zwrotnych: #207) i w przypadku braku odpowiedzi "200" ze strony aplikacji akcja jest ponawiana przez 24h z rosnącym interwałem.

Zapytania zwrotne powinny wykorzystywać protokół HTTPS (port 443), możliwa też jest komunikacja na port HTTP (port 80). W środowisku testowym Sandbox dodatkowo serwer ma możliwość wysyłania informacji zwrotnych na porty 8002 i 8003.

• Informacja zwrotna przy płatnościach cyklicznych

  Przykład żądania zwrotnego z informacją o udanym obciążeniu (paid=true).

  { "id":"in_hS-KiS3N6YCzOhG", "date":1371631155, "client":"cli_OU7k00vEMGi53C", "subscription":"sub_QyJzN4KdzNzvmZ", "amount":"7.00", "currency":"PLN", "paid":true, "issuer_response_code":"00","attempts":1, "next_payment_attempt":null, "created_at":1371500155, "last_payment":"pay_iq1yCYmgieM_ct" }

   

  A w przypadku, gdy status subskrypcji się zmieni - jeżeli zatrzymanie subskrypcji po nie udanych próbach zostało włączone w panelu www - nastąpi żądanie zwrotne informujące o tym fakcie.

  {"id":"sub_WQO0vEpk0-SrqM","state":"inactive","client":"cli_MNXfMFpu8_j3ax","plan":"pl_dxT6xBEo__fbb7y","created_at":1457559667,"last_invoice":{"id":"in_CjUBitNf9UpWdoQ","date":1460461811,"client":"cli_MNXfMFpu8_j3ax","subscription":"sub_WQO0vEpk0-SrqM","amount":"55.00","currency":"pln","paid":false,"issuer_response_code":"00","attempts":1,"next_payment_attempt":null,"created_at":1460461811,"last_payment":"pay_iq1yCYmgieM_ct"}}

• Informacja zwrotna przy zwykłej płatności

  Jeśli Sprzedawca używa APIv3.0, każda wywołana płatnosć generuje równoległe wysłanie informacji zwrotnej z bramki Espago do serwisu sprzedawcy.

  Jeśli zabezpieczenie 3D-Secure nie jest używane, odbiór tych informacji nie jest konieczny, gdyż są to te same informacje, które są zwracane jako odpowiedź na żądanie płatności. Jeśli 3D-Secure jest włączone, te informacje zwrotne są przesyłane dopiero po uwierzytelnieniu klienta i dokonaniu płatności, i są one głównym źródłem informacji dla Sprzedawcy o statusie płatności. Jeśli klient porzuci płatnosć na etapie weryfikacji 3DS, po 1,5h status płatności jest ustawiany na "resigned" i jest wysyłana informacja zwrotna.

   

  Przykładowa informacja zwrotna (back request):

  { "id": "pay_q8v53GIhU4SsaI" ,"description": "Opis transakcji", "channel": "elavon", "amount": 49.99, "currency": "pln", "state": "executed", "client": "cli_UrxPVeAjYh3l3C" ,"created_at": 1381821183, "issuer_response_code": "00", "reversable": "true" }

• Informacja zwrotna przy tworzeniu tokenów

  Istnieje możliwość włączenia wysyłania informacji zwrotnych z danymi tokenu z bramki Espago w momencie tworzenia tego tokenu. W ten sposób serwer sprzedawcy mógłby z Espago dowiedzieć się o utworzeniu tokenu, a nie z przeglądarki klienta/urządzenia mobilnego.

  W celu włączenia tej funkcji konieczny jest kontakt z Działem Wsparcia Technicznego (kontakt mailowy). Aby informacja zwrotna została wysłana, konieczne jest zawarcie parametru "card[description]" (5-60 znaków).

  Przebieg tworzenia tokenu z włączonymi informacjami zwrotnymi:

  1. Z przeglądarki klienta (przy użyciu Espago JS) lub z aplikacji mobilnej wysyłane jest zapytanie utworzenia tokenu. To żądanie zawiera m.in. dane karty oraz pole "description".
  2. Klient otrzymuje odpowiedź z bramki Espago potwierdzającą utworzenie tokenu. Odpowiedź zawiera m.in. ID tokenu, które w normalnym układzie klient przesyła do serwera Sprzedawcy.
  3. Bramka Espago wysyła asynchronicznie informację zwrotną do serwera Sprzedawcy, zawierającą m.in. ID tokenu oraz pole "description" umożliwiające sprzedawcy powiązanie tokenu z klientem.
  4. Przy użyciu tokenu odebranego z Espago (lub oderanego od Klienta) serwis Sprzedawcy może dokonać płatności.

eDCC

• Czym jest DCC?

  Usługa DCC (Dynamic Currency Conversion - Dynamiczne Przeliczanie Walut) firmy Elavon umożliwia Ci oferowanie posiadaczom zagranicznych kart VISA® i MasterCard® dokonywania płatności w ich rodzimej walucie.

  Przeliczenie kwoty transakcji z waluty w Twoim sklepie na walutę karty klienta następuje w bramce Espago jeszcze przed dokonaniem transakcji, dzięki czemu Twoi klienci mają możliwość poznania ostatecznej kwoty transakcji jeszcze przed dokonaniem płatności, a nie dopiero po otrzymaniu wyciągu z karty. Elavon oferuje usługę DCC dla najpopularniejszych 45 walut z całego świata.

  Usługa eDCC nie będzie wywołana w przypadku płatności cyklicznych (recurring=true). W płatności cyklicznej nie bierze udziału posiadacz karty, więc nie może podjąć decyzji DCC. W takim przypadku - przypadku użycia karty w innej walucie niż waluta serwisu do płatności cyklicznych, przewalutowanie nastąpi po stronie banku - wystawcy karty - i według jego zasad.

  Skrócony opis usługi eDCC znajduje się również na stronie https://www.elavon.pl/strefa-klienta/rozwijajswojafirme/dynamiczneprzeliczaniewalut.html​

• Objaśnienie parametrów DCC

  Parametr	Opis	Uwagi
  multicurrency_indicator	Informacja o walucie transakcji. Pole obecne tylko gdy waluta płatności jest inna niż waluta serwisu.	N - Karta bez DCC Y - DCC odrzucone przez posiadacza karty Z -DCC możliwe i zaakceptowane przez posiadacza karty
  dcc_decision_information[cardholder_currency_name]	Nazwa waluty posiadacza karty	Zgodnie ze standardem ISO 4217
  dcc_decision_information[cardholder_amount]	kwota transakcji w rodzimej walucie posiadacza karty
  dcc_decision_information[conversion_rate]	kurs wymiany waluty

• Rozpoczęcie transakcji DCC

  Transakcja rozpoczyna sie tak jak zawsze - #213-nowe-obciazenie. Jeśli merchant ma właczoną usługę eDCC to bramka Espago automatycznie rozpoznaje czy dana karta kwalifikuje się do usługi przeliczenia waluty.

  Kod wykorzystujący utworzony wcześniej token

  curl -H "Accept: application/vnd.espago.v3+json" -i https://sandbox.espago.com/api/charges -u app_id:password -d "amount=49.99" -d "currency=pln" -d "card=token_id" -d "description=Opis transakcji"

  • Jeżeli dana karta podlega transakcji DCC bramka odeśle odpowiedź i będzie oczekiwać na decyzję czy klient chce dokonać transakcji w swojej rodzimej walucie. Odpowiedź przy transakcji DCC zawsze pokaże kwotę transakcji w walucie merchanta, kurs wymiany waluty oraz kwotę transakcji w rodzimej walucie posiadacza karty. Płatność oczekująca na decyzję przyjmuje status=dcc_decision

    {"id":"pay_A3HYfiWQT_ZoHO","description":"Opis transakcji","channel":"elavon","amount":"49.99","currency":"pln","state":"dcc_decision","client":"cli_cAJf7ZF3Fz4FLz","created_at":1431526723,"card":{"company":"MC","last4":"6666","year":2016,"month":1,"first_name":"Jan","last_name":"Kowalski","authorized":null,"created_at":1431526723},"issuer_response_code":"","transaction_id":"tn_0_cIL3NsS","dcc_decision_information":{"cardholder_currency_name":"USD","cardholder_amount":"13.670","conversion_rate":"0.2734", "redirect_url": "https://sandbox.espago.com/secure_web_page/tn_0_cIL3NsS"}}

  • Jeżeli dana karta nie podlega transakcji DCC, płatność przebiega dalej normalnie, odpowiedź jest zgodnie z opisem #286-przykladowa-odpowiedz

• Dokończenie transakcji - przesłanie decyzji DCC klienta

  Aby wykonać zarezerwowane wcześniej środki na karcie klienta należy wysłać żądanie typu POST na adres https://sandbox.espago.com/api/charges/(:id)/dcc_decision

  (:id) - identyfikator płatności oczekującej na decyzję zwiazaną z DCC 

  Dostępne parametry HTTP

  Parametr	Opis	Uwagi
  decision	Podjęta decyzja czy karta ma być rozliczana w walucie posiadacza karty	wartość Y lub N

   

  Przykład z wykorzystaniem CURL

  curl -H "Accept: application/vnd.espago.v3+json" -i https://sandbox.espago.com/api/charges/(:id)/dcc_decision -u app_id:password -d "decision=Y"

  Przykładowa odpowiedź

  Odpowiedzi są takie same jak przy zwykłej transakcji bez eDCC - #286-przykladowa-odpowiedz - poszerzone o informacje nt. waluty i kwoty posiadacza karty.

  • Odpowiedź z 3D-Secure

    {"id":"pay_rU_ZCn4Zedo7Nq","description":"Test Sale 1","channel":"elavon","amount":"123.45","currency":"PLN","state":"tds_prtcpt","client":"cli_4GRTE0F9Xi_rFf","created_at":1432125833,"issuer_response_code":"","transaction_id":"tn_DeLTsLlJB","redirect_url":"https://sandbox.espago.com/3d-secure/tn_DeLTsLlJB","tds_redirect_form":{"action":"https://3dtest.espago.com/PIT/ACS","method":"POST","PaReq":"4e68edef9aec6367b0da4ff2eccb923cdb4be8b846daa696182dd67a2ce27 f5f6f489785dab889e27ce799ae9b976ce021462fdf3654f2f5e3f38cb33f99d43d0197 f87f128847a2df330e2be14 bd9aded0b06625b02997be6ebecbdfeae6476eed1fd069e089b3663c7ae6da4bf666c9db c8acc1b87554f99c203be46 5c9b7aa456ac8d97c878a2b73bc5688afd4925de3aac8a2ae0a53c05ca26cce4cf360053 22c19cc0a8efbc99e7797c7 b4396cfc3fd4e0fb522b1c07eedb2df28496f7168fd03247b3837051ef045da7ae5aec3d 5f4671a2aca18d6990c2138 f8c0a6aea56575645e40df5c12253d77927aa89bf3c4337d93da43ff96e2c654226dd800 23cb7a8c34d96c417a9ddb8 d50632c89634b7c6ca510ea46a27c76212beff4c5d46b90ed5020d57543502013a2369f8 b5a566c7b790ec46cc89156 037f1e7835a9f2fae29e3a2dea3c22514b2f9b0dc8577c8fae5f68471e84900e7b973325 7b2fde44a1c65bf1c6c231f 5699d073096f677421d67e4a8b910c9c6027ccd60dd425a927d4687be69dd8f6a40ce201 9c3d4e7e9ad8db82e9d6729 806b07770229e8c8a6aef7026c1aaefd014f968bd0b4e788399eb9d085d2d2ad5d2a4090 3cbb3ac913e9c35919fea96 2aaa96072135d17ac48e10521d2883374e60e03cdf36b154e168e9cccf73015e1b24d137 988f4a22b5af1","MD":"854","TermUrl":"https://3dtest.espago.com/visa3dmpi/servlet/ParesListener"},"multicurrency_indicator":"Z","dcc_decision_information":{"cardholder_currency_name":"HKD","cardholder_amount":"261.55","conversion_rate":"2.1187"}}

  • Odpowiedź bez 3D-Secure

    { "id": "pay_FMj2Q9N7e6Yv2z", "description": "Test Sale 1", "channel": "elavon", "amount": "123.45", "currency": "PLN", "state": "executed", "client": "cli__aNPjOXggmnfSZ", "created_at": 1432124395, "issuer_response_code": "00", "reversable": true, "transaction_id": "tn_PMN_nN0Am", "multicurrency_indicator": "Z", "dcc_decision_information": { "cardholder_currency_name": "HKD", "cardholder_amount": "261.55", "conversion_rate": "2.1187" } }

• Pobieranie kursu walut

  Kursy walut są aktualizowane raz dziennie o godzinie 18:30.

  Aby pobrać kursy walut dla waluty serwisu należy wysłać żądanie typu GET na adres https://sandbox.espago.com/api/dcc/rates

  Przykład z wykorzystaniem CURL

  curl -H "Accept: application/vnd.espago.v3+json" -i https://sandbox.espago.com/api/dcc/rates -u app_id:password

  Przykładowa odpowiedź

  {"timestamp":"2015-05-11T00:00:00+02:00","currency_name":"PLN","currency_code":"985","rates":{"AUD":"0.3531","CAD":"0.3343","CHF":"0.2618","DKK":"1.905","EUR":"0.2554","GBP":"0.1835","HKD":"2.1187","JPY":"32.6429","NOK":"2.1513","NZD":"0.3551","SEK":"2.3709","SGD":"0.3691","USD":"0.2734","ZAR":"3.3076","INR":"17.1971","KRW":"295.599","RUB":"14.6586","BMD":"0.2734","ISK":"37.3917","MYR":"0.9939","SAR":"1.025","CZK":"6.9958","QAR":"0.9951","TTD":"1.7222","AED":"1.0042","HUF":"75.8934","BHD":"0.103","KWD":"0.0826","THB":"8.8497","ILS":"1.0784","TWD":"8.5047","BBD":"0.5458","OMR":"0.1052","BSD":"0.2734","KES":"25.6168","ARS":"2.4242","CNY":"1.6952","COP":"679.651","MAD":"2.7304","MXN":"4.2133","PAB":"0.2734","RON":"1.1335","TRY":"0.7339","UAH":"6.1786","BRL":"0.8282"}}

Dosyłanie CVV

Kod CVV może być użyty tylko jeden raz i po pierwszej autoryzacji lub płatności jest usuwany z bramki Espago. Aby przy użyciu profilu klienta wykonać kolejną płatnosć z użyciem kodu CVV, należy pobrać od klienta kod CVV (przy uzyciu EspagoFrame lub skryptu Espago JS i utworzyć token dla CVV) i przesłać go jako jeden z parametrów płatności (obok ID klienta, kwoty itp).

Funkcja dosyłania CVV jest szczególnie pomocna jako dodatkowe uwierzytelnienie przy płatnościach wielokrotnych inicjowanych przez klienta (np. zakupy w sklepie, płatności w aplikacji mobilnej). Dosyłanie CVV dodatkowo zwiększa skuteczność płatności, gdyż umożliwia obciążanie kart, które nie działają bez kodu CVV (patrz: Problem kart nienadających się do płatności cyklicznych)

Przesłany kod CVV w formie tokenu może zostać użyty w ciągu 24h od jego utworzenia, ponieważ ta funkcja służy tylko realizacji na bieżąco kolejnych płatności, nie ma możliwości zapisania tokenów "na zapas".

• Nowy token CVV

  Aby utworzyć token dla CVV karty klienta należy wysłać żądanie typu POST na podany adres https://sandbox.espago.com/api/cvv

  Utworzenie Tokenu CVV poprzez bezpośrdnie zapytanie (a nie przez skrypt espago-cvv.js) jest dopuszczone tylko dla aplikacji mobilnych. W innych przypadkach prosimy o kontakt z Działem Wsparcia Techcznego Espago.

  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 -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/cvv -u publickey: -X POST -d "verification_value=123"

  Przykładowa odpowiedź

  {"id":"cv_BhJER4yDz2k3TKE","valid_to":1441792964,"created_at":1441706564,"used":false}

  Uwaga!
  Parametr used przyjmuje wartości logiczne true lub false. Jeżeli wartość wynosi false, oznacza to, że token nie został jeszcze użyty i że może zostać wykorzystany do dokonania płatności.
  Token CVV jest ważny tylko 24h.

• Wykorzystanie EspagoFrame do tworzenia tokenów CVV

  Do utworzenia tokenu CVV można wykorzystać EspagoFrame, opisany szerzej w dziale EspagoFrame, w którym klient będzie mógł podać dane karty, a w tym przypadku - wyłącznie CVV. Następnie te dane zostaną przesłane do Espago, a skrypt zwórci do strony ID tokenu, który można użyć do płatności w trybie dosyłania CVV.

  Działanie

  Po wywołaniu formularza i podaniu danych karty przez płatnika, skrypt wysyła je bezpośrednio do serwera Espago. W przypadku utworzenia tokenu, skrypt domyślnie szuka na stronie z której został wywołany formularza o identyfikatorze "espago_form"  <form id="espago_form">  i dodaje w nim pole input typu hidden o identyfikatorze "cvv_token" i wartości tokenu:

  <input type="hidden" id="cvv_token" name="cvv_token" value="cv_xxxxxxxxxxxxx">

  Działanie to można zmienić, wskazując parametr data-target lub data-success w wywołaniu iframe, o czym wspomniano w tabeli poniżej.

  • Opis parametrów

    Ważne:

    Parametry: `async`, `data-id` oraz `src` muszą pozostać niezmienione.

     

    Parametr	Obligatoryjność	Wartości domyślne	Znaczenie
    data-key	obowiązkowy		String, Klucz publiczny Merchanta
    data-cvv-only	obowiązkowy		String, jeśli ma wartość 'true', EspagoFrame działa w trybie tokenu CVV - tylko pole CVV jest wyświetlane.
    data-company	opcjonalny		String, wskazuje markę zapisanej karty, logo danej marki będzie wyświetlone obok pola CVV w sekcji informacji o zapisanej karcie. Dostępne: AX, DC, DI, JC, MC, MD, UP, VI.
    data-last4	opcjonalny		String, wskazuje ostatnie 4 cyfry z numeru zapisanej karty, będą one wyświetlone obok pola CVV w sekcji informacji o zapisanej karcie.
    data-valid-to	opcjonalny		String, format: 'MMRRRR', wskazuje datę ważności zapisanej karty, będzie ona wyświetlone obok pola CVV w sekcji informacji o zapisanej karcie.
    data-live	opcjonalny	true	String, Wskazuje czy formularz ma być wysyłany do środowiska produkcyjnego. Wartość 'true' oznacza wysyłanie danych na środowisko produkcyjne, wartość 'false' na środowisko testowe.
    data-lang	opcjonalny	pl	String, Język w jakim będzie wyświetlony formularz w standardzie ISO 639-1. Dostępne: da, de, en, et, fr, it, lt, lv, pl, ru, sv.
    data-success	opcjonalny	function(data) {}	Funkcja callback wywoływana w przypadku, gdy token zostanie wygenerowany. Uwaga, podanie funkcji callback wyłącza domyślne działanie skryptu - pole 'card_token' nie zostanie dołączone do formularza. data - string; wygenerowany token z bramki Espago.
    data-error	opcjonalny	function(data) {}	Funkcja callback wywoływana w przypadku, gdy token nie zostanie wygenerowany.  data - string; kod błędu otrzymany z bramki Espago wraz z opisem.
    data-onclose	opcjonalny	function() {}	Funkcja wywoływana w przypadku, gdy użytkownik zamknie okno dialogowe (klikając "x" lub klawisz "Esc").
    data-target	opcjonalny	espago_form	Nazwa formularza do którego zostanie dodane ukryte pole 'card_token' o wartości tokenu. Uwaga - w przypadku gdy zostanie podany parametr 'success_callback' akcja ta nie wykona się. Token zostanie przekazany do tej funkcji.
    data-title	opcjonalny	Dodaj swoją kartę (pl)	Nagłówek wyświetlany na górze formularza. Uwaga - domyślna wartość jest zależna od parametru języka 'data-lang'
    data-subtitle	opcjonalny		Tekst wyświetlany poniżej nagłówka i nazwy sklepu (pobranej automatycznie z API Espago)
    data-button	opcjonalny	Zapisz (pl)	Etykieta tekstowa wyświetlona na przycisku zatwierdzania formularza. Uwaga - domyślna wartość jest zależna od parametru języka 'data-lang'

• Wykorzystanie Espago.js do tworzenia tokenu CVV

  W celu przyjęcia kodu CVV i utworzenia tokenu CVV należy użyć formularz wykorzystujący skrypt JS espago-1.2. Skrypt ten przesyła kod CVV bezpośrednio z formularza (przeglądarka klienta) do bramki Espago, uzyskuje token CVV i przesyła jego ID ( jako parametr "cvv_token" z wartością w postaci "cv_xxxxxxxx") wraz z formularzem do strony sprzedawcy na adres zdefinowany w polu action.

  Adres, pod którym dostępna jest aktualna wersja skryptu: https://js.espago.com/espago-1.2.js 

  Demo: https://github.com/espago/espago-1.2.js-demo

  W skrypcie należy użyć klucza publicznego (Public Key) używanego także przy generowaniu tokenów z danymi kart.

• Płatność przy użyciu tokena CVV

  Dostępne parametry HTTP

  Dodatkowym parametrem w zapytaniu na /api/charges jest parametr cvv

  Parametr	Opis	Uwagi
  cvv	ID tokena CVV, opcionalny	W celu użycia utworzonego wcześniej CVV należy podać "cvv=cvv_token_id"

   

  Przykład z wykorzystaniem CURL

  Kod wykorzystujący funkcjonalność obiektów klienta (najczęstszy przypadek)

  curl -H "Accept: application/vnd.espago.v3+json" -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" -d "cvv=cvv_token_id"

  Kod wykorzystujący utworzony wcześniej token karty

  curl -H "Accept: application/vnd.espago.v3+json" -i https://sandbox.espago.com/api/charges -u app_id:password -d "amount=49.99" -d "currency=pln" -d "card=token_id" -d "description=Opis transakcji" -d "cvv=cvv_token_id" 

• Pobieranie danych o tokenie CVV

  Aby pobrać dane o istniejącym tokenie należy wysłać żądanie typu GET na podany adres https://sandbox.espago.com/api/cvv/(:id)

  (:id) - identyfikator tokenu CVV, którego dane chcemy pobrać

  Przykład z wykorzystaniem CURL

  curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/cvv/(:id) -u app_id:password -X GET

  Przykładowa odpowiedź

  {"id":"cv_BhJER4yDz2k3TKE","valid_to":1441792964,"created_at":1441706564,"used":false}

Masterpass

MasterPass będzie dostępny w Espago od marca 2015

• Jak działa MasterPass?

  MasterPass to nowoczesna forma płatności od MasterCard, która zapewnia nową jakość zakupów online. Wszystkie niezbędne informacje do przeprowadzenia transakcji – dane kart płatniczych i inne – wprowadzane są tylko raz, podczas rejestracj. Dalej wystarczy jedno kliknięcie, by dokonać zakupu. Ponadto, płatność MasterPass jest równie wygodna na komputerze, tablecie lub smartfonie.

• MasterPass API

  Poniżej przedstawiamy komunikację z Espago API dla użycia MasterPass

  Pełna dokumentacja i opis działania MasterPass, dostępna jest na stronie Mastercard: https://developer.mastercard.com/portal/display/api/MasterPass+-+Merchant+Checkout+Services+-+Documentation

  Przykładowa demonstracyjna integracja MasterPass dostępna jest na stronie https://warzywko.espago.com (jest też opisane jak użyć testowy portfel)

  Integracja Lightbox jest niezbędna do uruchomienia MasterPass. Aby uruchomić Lightbox sprzedawca musi załączyć następujące skrypty i podpiąć je pod przycisk Kup z MasterPass

  1. jQuery 
  2. Espago-masterpass script - ta sama bilbioteka w środowisku testowym i produkcyjnym
     <script src="https://developers.espago.com/espago-masterpass.js" type="text/javascript"></script>
  3. MasterPass Script
     w środowisku testowym sandbox:
     <script src="https://sandbox.masterpass.com/lightbox/Switch/integration/MasterPass.client.js" type="text/javascript"></script>
     w środowisku produkcyjnym:
     <script src="https://masterpass.com/lightbox/Switch/integration/MasterPass.client.js" type="text/javascript"></script>

   

  Przy connected checkout przydatna może być biblioteka:

  https://developers.espago.com/jquery.ddslick.min.js (http://designwithpc.com/plugins/ddslick#demo)

  • Rozpoczęcie transakcji bez uprzedniej rejestracji w serwisie merchanta - Standard Checkout

    Przed rozpoczęciem transakcji należy zapisać dane koszyka lokalnie. Szczególnie parametry session_id oraz kwotę transakcji.

    Transakcję rozpoczyna się wywołując funkcję płatnosći MasterPass, korzystając ze skryptu Espago-MasterPass.js, przez klienta. 

    • Jak wygląda przepływ

      Następujące kroki wyjaśnią przepływ przy Standard Checkout MasterPass: 

      1. Klient klika na przycisk Kup z MasterPass.
         Parametry transakcji są przesyłane do Espago przy użyciu jQuery i metody POST, i następnie Lightbox(MasterPass UI) jest uruchamiany. 

      2. Klient loguje sie do swojego portfela.

      3. Klient wybiera metodę płatnośći o adres dostawy.

      4. Klient akceptuje podsumowanie i przesyła zamówienie,

      5. Po tym gdy checkout jest wykonany, MasterPass przkierowuje i zwraca dane do Espago. Espago przekierowuje w zależności od statusu płatności na positive_url lub negative_url (lub wcześniej przekierowuje do banku jeśli usługa 3D-Secure ijest włączona dla sprzedawcy i posaidacza karty).

      6. Po wykonaniu płatności, potwierdzenie płatności (back_request) jest wysłany z bramki Espago do strony sprzedawcy.

      Pełny proces jest dostępny na stronie demo:  https://warzywko.espago.com, oraz na video poniżej:

       

    • przykładowe użycie espago-masterpass.js

      Parametry transakcji przesyłane zą za pomocą metody POST na adres

      sandbox URL: https://sandbox.espago.com/api/masterpass
      production URL: https://secure.espago.com/api/masterpass

      Parametry transakcji:

       

      Parametr	Opis	Obowiązkowy	Uwagi
      masterpass_action	Rodzaj akcji MasterPass	Tak
      app_id	Identyfikator aplikacji	Tak
      session_id	Identyfikator transakcji	Tak
      amount	kwota transakcji	Tak
      currency	waluta	Tak
      description	opis transakcji	Tak
      api_version	wersja api	Tak	3.0
      checksum	suma kontrolna	Tak	Funkcja skrótu MD5 dla ciągu znaków (app_id +|+ session_id +|+ amount +|+ currency +|+ checksum_key), łącznikiem pól jest znak "|". md5 dla: app123|hoQuNQAam|1.23|PLN|ac2bb wynosi: 963c1ab6d74d1340176c581867d951de
      Poszczególne pozycje koszyka zakupów, gdzie INDEX jest numerem od 0-100
      shopping_cart_items[INDEX][description]	Opis pozycji w koszyku	Tak
      shopping_cart_items[INDEX][quantity]	Ilość sztuk danej pozycji	Tak
      shopping_cart_items[INDEX][value]	Wartość	Tak
      shopping_cart_items[INDEX][image_url]	Url obrazu danej pozycji	Nie	musi być HTTPS/SSL

       

      Przykładowy formularz:

      <form accept-charset="UTF-8" id="masterpass_espago_form" method="post">     <input id="masterpass_action" name="masterpass_action" type="hidden" value="checkout" />     <input id="app_id" name="app_id" type="hidden" value="app12345" />     <input id="session_id" name="session_id" type="hidden" value="NF9r5x1at8MprEvqKmPh" />     <input id="amount" name="amount" type="hidden" value="123.00" />     <input id="currency" name="currency" type="hidden" value="PLN" />     <input id="description" name="description" type="hidden" value="payment_id:1" />     <input id="api_version" name="api_version" type="hidden" value="3" />     <input id="checksum" name="checksum" type="hidden" value="9ecbd7782c6152d71cf963448a2b7daf" />     <input id="shopping_cart_items_0_description" name="shopping_cart_items[0][description]" type="hidden" value="Szkolenie 8h" />     <input id="shopping_cart_items_0_quantity" name="shopping_cart_items[0][quantity]" type="hidden" value="1" />     <input id="shopping_cart_items_0_value" name="shopping_cart_items[0][value]" type="hidden" value="123.0" />     <input id="shopping_cart_items_0_image_url" name="shopping_cart_items[0][image_url]" type="hidden" value="https://example.com/image.jpg" />     <button name="button" type="submit">Buy with MasterPass</button> </form><a href="http://www.mastercard.com/mc_us/wallet/learnmore/pl/PL" target="_blank">Learn more</a>

       

      Podpięcie funkcji EspagoMasterPass pod formularz Buy with MasterPass:

      <script> $(document).ready(function(){ var espago_masterpass = new EspagoMasterPass({public_key: 've9SCMKLFabsHzX8HhTe', custom: true, live: false}); $("#masterpass_espago_form").submit(function(event){ event.preventDefault(); espago_masterpass.create_js(); }); }); </script>

      Przykładowa odpowiedź. Skrypt EspagoMasterPass na podstawie wartość atrybutu js uruchamia MasterPass Lightbox:

       

      { "id": "pay_W0PwYzBhVHNfMO", "description": "payment_id:99", "channel": "masterpass", "amount": "123.00", "currency": "PLN", "state": "new", "client": "cli_Q20SVMDFtL-Etr", "created_at": 1426638527, "transaction_id": "tn_7r6QMuWzD", "masterpass_action": "checkout", "js": { "callbackUrl": "https://secure.espago.com/api/masterpass/cartcallback/tn_7r6QMuWzD", "requestToken": "9de311cc5cf2cd9193bd9b83584cd5ce44c87817", "requestBasicCheckout": false, "merchantCheckoutId": "a4a6w4vto9k9gi6o2l21z1i7dec8sxkfz5", "allowedCardTypes": "master,amex,maestro,visa", "cancelCallback": "https://binartrackers.railshost.com/payments/err", "suppressShippingAddressEnable": false, "loyaltyEnabled": "true", "version": "v6" } }

    • Przykładowa odpowiedź back_request

      {"id":"pay_5-gesOlp_ZIbuJ","description":"payment_id:124","channel":"masterpass","amount":"123.00","currency":"PLN","state":"executed","client":"cli_IJRMhA6p1-Tpy8","created_at":1425756633,"issuer_response_code":"00","reversable":true,"masterpass":{"brand_name":"MasterCard", "billing_address":{"city":"toronto","country":"CA","countrySubdivision":"CA-ON","line1":"1212 no address","line2":"","line3":"","postalCode":"m3v2w2"},"shipping_address":{"city":"Poznań","country":"PL","countrySubdivision":"Wielkopolskie","line1":"Nowakowa 12/3","line2":"","line3":"","postalCode":"60-123","recipientName":"Jan Kowalski","recipientPhoneNumber":"PL+48-61123123123"},"contact":{"firstName":"JOE","lastName":"Test","country":"US","emailAddress":"joe.test@email.com","phoneNumber":"1-9876543210"}}}

    • Wyświetlanie obrazu "Kup z MasterPass"

      • PL https://www.mastercard.com/mc_us/wallet/img/pl/PL/mcpp_wllt_btn_chk_147x034px.png
      • EN https://www.mastercard.com/mc_us/wallet/img/en/US/mcpp_wllt_btn_chk_147x034px.png
      • możliwe rozmiary i rozdzielczośći
        • /mcpp_wllt_btn_chk_147x034px.png
        • /mcpp_wllt_btn_chk_160x037px.png
        • /mcpp_wllt_btn_chk_166x038px.png
        • /mcpp_wllt_btn_chk_180x042px.png
        • /mcpp_wllt_btn_chk_290x068px.png 
        • /mcpp_wllt_btn_chk_317x074px.png 
        • /mcpp_wllt_btn_chk_326x076px.png 
        • /mcpp_wllt_btn_chk_360x084px.png

    • Strona “Dowiedz się więcej” MasterPass

      Oprócz obrazu "Kup z MasterPass", MasterPass wymaga także od akceptantów linku do strony informacyjna "Dowiedz się więcej". Strona ta pozwala konsumentowi dowiedzieć się więcej na temat MasterPass.

      Zalecane jest, dodanie odsyłacza do strony dowiedz się więcej najbliżej buttona "Kup z MasterPass"

      

      Strona "Dowiedz się więcej" jest dostępna w wielu językach, do których linki znajdują się poniżej. Cała lista dostępnych języków oraz adresów stron jest dostępna w dokumencie MasterPassDigital Assets – Buttons and Learn More Links document.

      Adresy URL z prowadzące do stron "Dowiedz się więcej" w różnych językach

      • Polski - https://www.mastercard.com/mc_us/wallet/learnmore/pl/PL/
      • Angielski - http://www.mastercard.com/mc_us/wallet/learnmore/en
      • Szwedzki - http://www.mastercard.com/mc_us/wallet/learnmore/se
      • Francuski - http://www.mastercard.com/mc_us/wallet/learnmore/fr
      • Włoski - http://www.mastercard.com/mc_us/wallet/learnmore/it
      • Hiszpański -http://www.mastercard.com/mc_us/wallet/learnmore/es

    • Testowanie

      Następujące konta testowe Masterpass, które dotychczas były używane do testowania nie są już dostępne:

      • joe.test@email.com
      • joe.test3@email.com
      • 3ds.masterpass+securecode@gmail.com
      • 3ds.masterpass+verifiedbyvisa@gmail.com

      W celu przeprowadzenia testów w środowisku testowym, trzeba najpierw założyć własne testowe konto Masterpass.

      Kliknij tutaj, aby uzyskać więcej szczegółów na temat testów w środowisku Sandbox. Kroki są różne dla witryn handlowych w USA i tych globalnych. https://developer.mastercard.com/page/masterpass-testing

       

      Warto pamiętać, że wynik płatności testowych zależy od wyboru miesiąca(patrz rozdział testowanie). Pozwala to testować dwa scenariusze: pozytywny i negatywny. Miesiąc wygaśniecia karty 01-05 transakcja zakceptowana. Dlatego warto wybierać zweryfikowane karty (każdy może dodać błędną kartę do tego publicznego testowego konta masterpass) oraz odpowiedni miesiąc ważności karty.

Strona płatności

Wykorzystanie Strony Płatności Espago polega na przekierowaniu klienta do bramki Espago, na której klient poda dane kart w celu dokonania płatności. Aktualnie przy pomocy Strony Płatności Espago można dokonywać tylko płatności jednorazowych (nie ma możliwości utworzenia profilu klienta w celu późniejszego cyklicznego obciążania go).

1. Klient po wybraniu zakupów i rodzaju płatności na stronie Sprzedawcy przesyła formularz metodą POST na adres bramki ze ścieżką /secure_web_page
2. Klientowi jest wyświetlana strona płatności, na której widzi m.in. dane Sprzedawcy oraz kwotę do zapłaty. Klient podaje te dane i klika "Zapłać".
3. W zależności od włączonych funkcji na koncie sprzedawcy i typu karty klienta klient może mieć do wyboru walutę płatności (DCC) i/lub być przekierowany na stronę banku (3D-Secure).
4. Po dokonanej płatności klient jest przekierowany na stronę positive_url lub negative_url sprzedawcy zdefiniowaną w formualrzu przesłanym z płatnością, a jeśli nie była ona zdefiniowana w formularzu to na adresy URL zdefiniowane w panelu w bramce Espago.
5. Po dokonanej płatności z bramki Espago do strony sprzedawcy (na adres "URL żądania zwrotnego") jest przesyłane potwierdzenie dokonania płatności.

Demo dostępne: https://warzywko.espago.com/

• Przykładowy formularz

  Parametry transakcji przesyłane są za pomocą metody POST na adres

  sandbox URL: https://sandbox.espago.com/secure_web_page
  URL: https://secure.espago.com/secure_web_page

  Parametry transakcji:

  Parametr	Opis	Obowiązkowy	Uwagi
  api_version	wersja api	Tak	3
  app_id	Identyfikator aplikacji	Tak
  kind	rodzaj transakcji	Tak	sale - sprzedaż; preauth - rezerwowanie środków przyszłego obciążenia
  session_id	Identyfikator transakcji	Tak	Losowy, unikalny ciąg znaków wygeneorwany przez serwis Sprzedawcy.
  amount	kwota transakcji	Tak	dwa miejsca po przecinku, rozdzielone kropką np. 10.00, 1.23, 1.20
  currency	waluta	Tak
  title	opis transakcji	Tak	Tytuł płatności wyświetlany klientowi na ekranie płatności kartą, np. "Zamówienie 123/2019". Musi zawierać od 5 do 100 znaków. Parametr, który powinien zawierać identyfikator z systemu Sprzedawcy umożliwiający identyfikację płatności przy odbiorze Zapytania zwrotnego, np. unikalny numer zamówienia. Pole "title" będzie następnie widoczne jako pole "description" we właściwościach płatności (np. w back requście).
  description	opis klienta	Nie	Opis klienta (nie płatności).
  email	email klienta	Nie
  positive_url	adres powrotny po pozytywnym zakończeniu transakcji	Nie
  negative_url	adres powrotny po negatywnym zakończeniu transakcji	Nie
  locale	język transakcji	Nie	pl, en, da, ru, sv
  reference_number	numer rerenecyjny transakcji	Nie	Tekst ref. transakcji - widoczny w raportach Elavon.  Długość do 20 znaków, tylko alfanumeryczne oraz -_ (myślnik i belka).
  ts	znacznik czasowy	Tak
  checksum	suma kontrolna	Tak	Funkcja skrótu MD5 dla ciągu znaków (app_id + kind + session_id + amount + currency + ts + checksum_key), . łącznikiem pól jest znak "|". md5 dla: app123|sale|hoQuNQAam|1.23|PLN|1444044688|ac2bb wynosi: ec4a3d29787495ca3dc36fb548d93c91
  Poszczególne pozycje koszyka zakupów, gdzie INDEX jest numerem od 0-100 - niewymagany
  shopping_cart_items[INDEX][description]	Opis pozycji w koszyku	Tak
  shopping_cart_items[INDEX][quantity]	Ilość sztuk danej pozycji	Tak
  shopping_cart_items[INDEX][value]	Wartość	Tak
  shopping_cart_items[INDEX][image_url]	Url obrazu danej pozycji	Nie	musi być HTTPS/SSL

   

  Przykładowy formularz:

  <form accept-charset="UTF-8" action="https://sandbox.espago.com/secure_web_page" id="espago_secure_web_page" method="post">
  <input id="api_version" name="api_version" type="hidden" value="3" />
  <input id="app_id" name="app_id" type="hidden" value="app12345" />
  <input id="kind" name="kind" type="hidden" value="preauth" />
  <input id="session_id" name="session_id" type="hidden" value="hoQuNQAamMAvSKYXEKzM" />
  <input id="amount" name="amount" type="hidden" value="1.23" />
  <input id="currency" name="currency" type="hidden" value="PLN" />
  <input id="title" name="title" type="hidden" value="payment_id:294" />
  <input id="description" name="description" type="hidden" value="Jan Kowalski" />
  <input id="email" name="email" type="hidden" value="jan.kowalkis@example.com" />
  <input id="positive_url" name="positive_url" type="hidden" value="http://example.com/payments/ok" />
  <input id="negative_url" name="negative_url" type="hidden" />
  <input id="ts" name="ts" type="hidden" value="1444044688" />
  <input id="checksum" name="checksum" type="hidden" value="ac2bb1cdb8b8052895f2246e14aad7d5" />
  <input id="shopping_cart_items_0_description" name="shopping_cart_items[0][description]" type="hidden" value="Pakiet 1" />
  <input id="shopping_cart_items_0_quantity" name="shopping_cart_items[0][quantity]" type="hidden" value="1" />
  <input id="shopping_cart_items_0_value" name="shopping_cart_items[0][value]" type="hidden" value="1.23" />
  <input id="shopping_cart_items_0_image_url" name="shopping_cart_items[0][image_url]" type="hidden" value="https://example.com/products/0.png" />
  <div class='button'>
  <button name="button" style="float:left" type="submit">Kupuję</button>
  </div>
  </form>

• Płatność z Championem

  Aby zajestrować płatność z użyciem Championa należy wysłać żądanie typu POST na podany adres https://sandbox.espago.com/api/secure_web_page_register

  (:service_client_id) - identyfikator klient w serwisie Sprzedawcy, musi być on unikatowy, ponieważ na jego podstawie następuje automatyczne logowanie do portfela MC klienta

  (:redirect_url) - link, na który należy przekierować klienta w celu dokonania płatności (zwracany jest on w odpowiedzi na żądanie)

  Wynik płatności należy odebrać za pomocą Żądania zwrotnego.

   

  Przykład z wykorzystaniem CURL

   

  curl -i https://sandbox.espago.com/api/secure_web_page_register -X POST -H 'Accept: application/vnd.espago.v3+json' -u app_id:password -d 'amount=49.99' -d 'currency=PLN' -d 'description=Opis transakcji' -d 'kind=sale' -d 'positive_url=https://......' -d 'negative_url=https//.....' -d 'service_client_id=xxxxxx'-d 'client_description=xxxxx'

   

  Przykładowa odpowiedź

   

  {"id":"pay_IZTq8l_qaHuOHH","description":"Opis transakcji","amount":"49.99","currency":"PLN","state":"new","created_at":1550224439,"transaction_id":"tn_CLN2HhetI","redirect_url":"https://sandbox.espago.com/secure_web_page/tn_CLN2HhetI"}

   

Integracja przez Przelewy24

Istnieje możliwość podłączenia płatności kartowych Espago / Eavon jako jednej z metod płatności w module Przelewy24 (Dialcom24 Sp. z o.o.). W takim scenariuszu zupełnie nie ma potrzeby integracji z bramką Espago, sprzedawca musi zintegrować sklep jedynie z modułem Przelewy24.

Jest to rozwiązanie szczególnie przydatne w sytuacjach gdy:

• Sprzedawca jest zainteresowany również przyjmowaniem płatności przez zwykłe/szybkie przelewy bankowe
• Sprzedawca korzysta z gotowego systemu sklepowego (PrestaShop, Magento i inne) i zależy mu na prostym podłączeniu zwykłych, jednorazowych płatności kartowych
• Sprzedawca już wykorzystuje płatności Przelewy24

• Ograniczenia

  Integracja płatności kartowych Espago/Elavon za pośrednictwem Przelewy24 wiąże się z następującymi ograniczeniami:

  1. Jedno konto, czyli jeden numer MID przyznany przez Elavon może być wykorzystywane za pośrednictwem modułu Przelewy24 lub przy bezpośredniej integracji z bramką Espago. Aktualnie nie ma możliwości współdzielenia danych dostępowych, utworzonych profili klienta ani wspólnych list transakcji. Aby jednocześnie przyjmować płatności kartowe przez Przelewy24 oraz bezpośrednio z użyciem bramki Espago należy uzyskać dwa osobne numery MID (na ogół wymaga to aneksu do umowy z Elavon).
  2. Przy pomocy Przelewy24 dostępne są jedynie płatności jednorazowe, nie ma płatności cyklicznych (tzn. recurringu) ani nie ma możliwości tworzenia profili klienta.
  3. W środowisku testowym Przeewy24 nie ma płatności kartowych. Ta metoda płatności pojawi się tylko w środowisku produkcyjnym Przelewy24 po podłączeniu jej przez obsługę Espago i P24.

• Użycie modułu P24

  Integracja płatnosci kartowych Espago/Elavon za pośrednictwem Przelewy24 ogranciza się do następujących czynności:

  1. Utworzenie konta w serwisie Przelewy24 oraz zawarcie umowy (online, pozostałe elementy można wykonywać równolegle)
  2. Integracja systemu/sklepu Sprzedawcy z modułem Przelewy24 np. poprzez instalację odpowiedniej wtyczki P24.
  3. Przekazanie do Espago informacji o chęci integracji przy użyciu Przelewy24 wraz z numerem ID serwisu/konta w P24, do którego mają być podłączone płatności kartowe Espago/Elavon.

   

  Dodatkowe informacje dotyczące integracji z Przelewy24:

  • Opis integracji na stronie P24: https://www.przelewy24.pl/dla-firm/instalacja
  • Lista gotowych modułów P24 do pobrania: https://www.przelewy24.pl/pobierz
  • Wykorzystywany do integracji serwer testowy https://sandbox.przelewy24.pl/panel/ nie posiada opcji płatności kartowych Espago/Eavon - ta opcja będzie włączona tylko na produkcyjnym koncie.
  • Istnieje możliwość "wyciągnięcia" na stronę sklepu przycisku do płatności P24, który przekieruje klienta bezpośrednio do płatności kartą (bez wyboru innych form płatności).

Visa Checkout [SZKIC]

Demo działania Visa Checkout jest dostępne w testowym sklepie Espago https://warzywko.espago.com/

Ogólny zarys integracji Visa Chcekout (VCO) u sprzedawcy w połączeniu z Espago jest przedstawiony na poniższym rysunku:

• Sprzedawca tworzy konto swojej firmy (testowe konto można założyć tutaj: https://developer.visa.com/portal/#users/new)
• Sprzedawca wybiera Espago z listy PSP
• Sprzedawca podłącza skrypt VisaCheckout.JS do swojej strony (https://developer.visa.com/products/visa_checkout/guides#adding_visa_checkout)
  • (1) - po załadowaniu strony, guzik VISA checkout się aktywuje
  • (2) - po przyciśnięciu guzika VISA Checkout uruchamiany jest (na podstawie parametrów ustawionych przez sprzedawcę - m.in. klucz publiczny Espago i identyfikator połączenia Sprzedawcy z Espago) VCO lighbox
    •     V.init({
            apikey: "W01VD5R14X2WZBDI0TJ413EGcry4u-ZZYXFptERgcg8KWiFyw",
            paymentRequest:{
              currencyCode: "PLN",
              subtotal: "5.0",
              total: "5.0",
              customData: {
                    "nvPair": [
                         { "name": "customName1", "value": "customValue1" },
                         { "name": "customName2", "value": "customValue2" }
              ]},
              orderId: "order_no_123",
              promoCode: 'Test promo'
            },
      
          });
  • (3) - klient podaje dane karty/wybiera dane/zakłada konto i klika Dalej
  • (4) - dane z VCO są przesyłane do sprzedawcy, może je wyświetlić i wykorzystać
  • (5) - parametr "call ID" z danych odebranych przez VCO jest przesyłany do Espago wraz z całym zapytaniem obciążającym (analogiczne do standardowego zapytania do Espago, z tym, że call ID zamiast danych karty)
• Espago
  • (6-7-8-9-10-11-12-13-14) Espago pobiera dane klienta z VCO i tworzy płatność kartową, zwraca dane i wysyła BackRequest

Szczegółowa dokumentacja techniczna VisaCheckout: https://developer.visa.com/products/visa_checkout/guides#getting_started

• Przykładowe zapytanie

  Utworzenie nowego obciążenia następuje w wyniku wysłania żądania typu POST na adres https://sandbox.espago.com/api/visacheckout.

  Dostępne parametry HTTP

  Parametr	Opis	Uwagi
  call_id	id zapytania VCO	ID zapytania uzyskanego z Visa Checkout, takie zapytanie musi mieć zdefiniowane total - kwotę, która ma być pobrana z karty klienta (atrybut amount transakcji)
  description	Opis transakcji	Musi składać się z 5 do 99 znaków.
  pay	true|false	domyślnie false, informacja, czy to jest płatność ostateczna czy też początkowa - do odbioru danych kontaktowych z VisaCheckout

  • Przykład z wykorzystaniem CURL

    Kod wykorzystujący funkcjonalność płatności od razu (pay=true)

    curl -i https://sandbox.espago.com/api/visacheckout -u app_id:password -d "call_id=3931755271838381802" -d "description=Opis transakcji" -d "pay=true" 

    Odpowiedź

    {"id":"pay_bJuV0IYLSzRFSA","description":"Opis transakcji","channel":"visacheckout","amount":"49.99","currency":"pln","state":"executed","client":"cli__lebHEMtR-HGIF","created_at":1486118378,"card":{"company":"VI","last4":"4242","year":2022,"month":4,"first_name":"Adam","last_name":"Kowalski","authorized":null,"created_at":1486118379},"issuer_response_code":"00","reversable":true,"transaction_id":"tn_RmNqMSO69","visacheckout":{"params": {"promo_code": "Test promo","total": "130.0","order_id": "1917","custom_data": {"nvPair": [{"name": "customName1","value": "customValue1"},{"name": "customName2","value": "customValue2"}]}},"billing_address":{"personName":"Adam Kowalski","firstName":"Adam","lastName":"Kowalski","line1":"Uliczna 16/1","streetNumber":"16/1","streetName":"Uliczna","city":"Pozna\u0144","postalCode":"60-412","countryCode":"PL","phone":"123456789","default":false},"shipping_address":{"verificationStatus":"NOT_VERIFIED","personName":"Adam Kowalski","firstName":"Adam","lastName":"Kowalski","line1":"Uliczna 16/1","streetNumber":"16/1","streetName":"Uliczna","city":"Pozna\u0144","postalCode":"60-412","countryCode":"PL","phone":"123456789","default":false},"risk_data":{"advice":"UNAVAILABLE","score":0,"avsResponseCode":"0","cvvResponseCode":"0","ageOfAccount":126}}}

    Kod wykorzystujący funkcjonalność płatności po odebraniu informacji o kliencie

    curl -i https://sandbox.espago.com/api/visacheckout -u app_id:password -d "call_id=3931755271838381802" -d "description=Transakcja - 1917" 

    Odpowiedź

    {"id": "pay_OZWBpgQv8v9bWj","description": "Transakcja - 1917","channel": "visacheckout","amount": "130.00","currency": "PLN","state": "vco_data","client": "cli_nmGGAKnVe9QtUk","created_at": 1487340384,"card": {"company": "VI","last4": "4242","year": 2022,"month": 4,"first_name": "Adam","last_name": "Kowalski","authorized": null,"created_at": 1487340384},"issuer_response_code": "","transaction_id": "tn_MxHouQ4K3","visacheckout": {"params": {"promo_code": "Test promo","total": "130.0","order_id": "1917","custom_data": {"nvPair": [{"name": "customName1","value": "customValue1"},{"name": "customName2","value": "customValue2"}]}},"billing_address": {"personName": "Adam Kowalski","firstName": "Adam","lastName": "Kowalski","line1": "Uliczna 16/1","streetNumber": "16/1","streetName": "Uliczna","city": "Poznań","postalCode": "60-412","countryCode": "PL","phone": "123321123","default": false},"shipping_address": {"verificationStatus": "NOT_VERIFIED","personName": "Adam Kowalski","firstName": "Adam","lastName": "Kowalski","line1": "Uliczna 16/1","streetNumber": "16/1","streetName": "Uliczna","city": "Poznań","postalCode": "60-422","countryCode": "PL","phone": "123321123","default": false}}}

     

  • Dokończenie obciażenia

    Dokończenie obciążenia VisaChecout następuje w wyniku wysłania żądania typu POST na adres https://sandbox.espago.com/api/charges/(:id)/vco_pay.

    Dostępne parametry HTTP

    Parametr	Opis	Uwagi
    new_amount	kwota która ma zostać pobrana
    subtotal	zgodnie z dokumentacją VCO
    discount	zgodnie z dokumentacją VCO
    shipping_handling	zgodnie z dokumentacją VCO
    gift_wrap	zgodnie z dokumentacją VCO
    misc	zgodnie z dokumentacją VCO
    tax	zgodnie z dokumentacją VCO

     

    Przykład z wykorzystaniem CURL

     

    curl -H 'Accept: application/vnd.espago.v3+json' -i https://sandbox.espago.com/api/charges/pay_OZWBpgQvgbWj/vco_pay -u app_id:password -d 'subtotal=120' -d 'discount=35' -d 'shipping_handling=5' -d 'amount=90'

    Przykładowa odpowiedź w przypadku płatności jednokrokowej(pay=true)

    {"id": "pay_OZWBpgQv8v9bWj","description": "Transakcja - 1917","channel": "visacheckout","amount": "90.00","currency": "PLN","state": "executed","client": "cli_nmGGAKnVe9QtUk","created_at": 1487340384,"issuer_response_code": "00","reversable": true,"transaction_id": "tn_MxHouQ4K3","visacheckout": {"params": {"promo_code": "Test promo","subtotal": "120.0","discount": "35.0","shipping_handling": "5.0","total": "90.0","order_id": "1917","custom_data": {"nvPair": [{"name": "customName1","value": "customValue1"},{"name": "customName2","value": "customValue2"}]}},"billing_address": {"personName": "Adam Kowalski","firstName": "Adam","lastName": "Kowalski","line1": "Uliczna 16/1","streetNumber": "16/1","streetName": "Uliczna","city": "Poznań","postalCode": "60-412","countryCode": "PL","phone": "123321123","default": false},"shipping_address": {"verificationStatus": "NOT_VERIFIED","personName": "Adam Kowalski","firstName": "Adam","lastName": "Kowalski","line1": "Uliczna 16/1","streetNumber": "16/1","streetName": "Uliczna","city": "Poznań","postalCode": "60-422","countryCode": "PL","phone": "123321123","default": false}}}