• Założenia wstępne

    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.

    • Ogólny opis działania bramki

      1. Istnieje kilka możliwości integracji z bramką płatności Espago:
        • Umieszczenie formularza płatności na stronie Sprzedawcy przy wykorzystaniu skryptu Espago iFrame lub Espago JS, oraz realizacja wszystkich operacji związanych z płatnościami poprzez zapytania API.
        • Przekierowanie klienta ze strony Sprzedawcy na stronę płatności Espago wraz z odpowiednimi parametrami dotyczącymi płatności. [szczegóły]
        • Integracja strony Sprzedawcy z systemem Przelewy24 i wybór płatności kartowych Espago/Elavon jako jedynej lub jednej z form płatnosci. [szczegóły]
      2. 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.
      3. Testowy sklep prezentujący przykładową integrację płatnosci: https://warzywko.espago.com/
      4. Dostęp do środowiska testowego https://sandbox.espago.com można uzyskać w Dziale Wsparcia Technicznego Espago.
      5. Architektura aplikacji jest zgodna ze wzorcem REST.
      6. Preferowanym 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.
      7. Dane początkowe przesyłane są z wykorzystaniem HTTP PARAMS, a wynikowe zwracane w formacie JSON.
      8. Espago udostępnia skrypty w JavaScript https://js.espago.com/espago-1.2.js W większości przypadków (strona płatności wewnątrz strony sprzedawcy) użycie jednego z nich jest obowiązkowe. Dzięki wykorzystaniu skryptu formularz płatności jest osadzony wewnątrz Państwa strony w taki sposób, żeby Państwa Klient nie opuszczał w żadnym momencie Państwa strony a dane kart płatniczych omijały Państwa serwer (zrzuca to z Państwa odpowiedzialność za przechowywanie i przetwarzanie danych kart).
      9. W celu zapewnienia odpowiedniego poziomu bezpieczeństwa wymagane jest na stronie sklepu zastosowanie certyfikatów SSL i wykorzystanie skryptu JS udostępnianego przez Espago.
      10. 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.
      • 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 października 2017 bramka produkcyjna Espago będzie akceptowała tylko połączenia szyfrowane przy pomocy protokołów TLSv1.2 lub TLSv1.1 (do tego czasu akceptuje również TLSv1). Docelowa konfiguracja, czyli wymóg użycia tylko tych dwóch protokołów (TLSv1.2 i TLSv1.1) jest już wprowadzona w bramce testowej https://sandbox.espago.com 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ą po wprowadzeniu wszystkich zmian.

        • 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 rozpoczęte  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.2 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

          W celu ułatwienia testów/analizy problemów z połączeniami do bramki Espago zostały utworzone dodatkowe domeny. 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.

          • Zmiany wynikają z nowych wymagań PCI-DSS stawianych przez organizację wystawców kart płatniczych.
          • W środowisku testowym zostały skonfigurowane dwie alternatywne domeny (dające dostęp do tego samego serwera Sandbox) ułatwiające testowanie:
            • https://oldssl-sandbox.espago.com spełnia starsze, wycofywane wymagania, umożliwia testowanie płatności pomimo nie spełniania nowych wymogów dotyczących SSL.
            • https://sandbox.espago.com spełnia najbardziej aktualne lub planowane w przyszłości wymagania SSL/TLS.
            • 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 środowisku produkcyjnym została dodana jedna alternatywna domena (dająca dostęp do tego samego serwera Secure, te same dane logowania):
            • https://newtls-secure.espago.com spełnia wymagania (protokół TLSv1.2, restrykcyjne zestawy szyfrów ssl), których wprowadzenie na na adres secure.espago.com planujemy na nie później niż 1 kwartał 2017.
            • Jeśli po przełączeniu Państwa produkcyjnej aplikacji z secure.espago.com na newtls-secure.espago.com Państwa środowisko produkcyjne będzie łączyć się z bramką Espago bez problemu, oznacza to że Państwa aplikacja/system nie wymagają zmian związanych z SSL.
            • Jeśli po przełączeniu Państwa produkcyjnej aplikacji z secure.espago.com na newtls-secure.espago.com Państwa środowisko produkcyjne  przestanie łączyć się z bramką Espago (tzn. dokonanie płatności będzie niemożliwe), oznacza to że Państwa aplikacja/system wymagają aktualizacji lub innych zmian związanych z SSL.
            • Adres https://newtls-secure.espago.com służy do testów SSL. Po ich zakończeniu prosimy o przestawienie Państwa aplikacji produkcyjnej z powrotem na secure.espago.com.
      • 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 Twoje strony
      2. Przejść do okna edycji serwisu wybierając przycisk Edytuj
      3. Uzupełnić pola "Hasło API" i "Potwierdzenie hasła API" - wpisana wartość odpowiada za prawidłową autoryzację Państwa konta i nie może być ujawniana osobom postronnym. Hasło API
      4. 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
      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 Edytuj dane serwisu
      7. Należy zwrócić uwagę na uzyskane ID Aplikacji w tabeli głównej zakładki Serwisy. ID Aplikacji
      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. Klucz publiczny
    • 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.
  • 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)
      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"

        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"

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

       

      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 (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) 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.
        description   Opis płatności przesłany w zapytaniu na /api/charges.
        channel   Kanał płatności. Aktualnie we wszystkich przypadkach jest to "elavon", więc parametr może zostać zignorowany.
        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, po czym 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.

      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:

      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), 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").

      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.

      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) 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 nie nadają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 nie nadają 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.

    • Konfiguracja

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

      1. Przejść do zakładki Twoje strony
      2. Przejść do okna edycji serwisu wybierając przycisk Edytuj
      3. Należy ustawić adres url żądania zwrotnego (dotyczy to kolejnych obciążeń subskrypcji):

        url żądania zwrotnego - definiuje adres, na który wysyłana jest asynchronicznie informacja po uzyskaniu przez bramkę statusu kolejnej płatności
         
      4. Dla bezpieczeństwa warto skonfigurować po stronie Sprzedawcy konieczność autoryzacji informacji zwrotnych z bramki Espago i skonfigurować nagłówki autoryzacyjne żądań zwrotnych poprzez edycję pól:

        Login BasicAuth (dla URL żądania zwrotnego) - definiuje nazwę użytkownika umieszczoną w nagłówkach żądań zwrotnych

        Hasło BasicAuth (dla URL żądania zwrotnego) - definiuje hasło umieszczone w nagłówkach żądań zwrotnych

        Witryna umieszczona pod adresem żądania zwrotnego musi blokować żądania nie autoryzowane przy pomocy danych ustalonych powyżej.

      5. Uzupełnić czasy powtarzania próby obciążenia nieudanych transakcji oraz określić status na wypadek wykorzystania limitów ponowień. W środowisku produkcyjnym możliwymi wartościami są: 1,2,3,4 dni, w środowisku testowym dostępne są krótsze czasy (np. liczone w minutach). Ustawienia płatności cyklicznych

        Możliwe stany po wyczerpaniu limitów ponownych obciążeń:

        Stan Opis
        Zatrzymaj subskrypcję Wyłącza subskrypcję uniemożliwiając generowanie kolejnych obciążeń według cyklu ustalonego w szczegółach planu. Status subskrypcji zmieni się na "inactive".
        Nic nie rób Mimo braku pozytywnego wyniku danego obciążenia generowane będą kolejne, zgodnie z planem.
    • Plany

      Plany są 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=day oraz period_unit=7 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) -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) -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 do kart klientów umożliwiają obciążenie kart klientów, bez przechowywania ani przesyłania danych o ich kartach przez system Sprzedawcy.

    Przy integracji z API konieczne jest wykorzystanie skryptu Espago.js. Zadaniem skryptu 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. Poniżej został opisany cały schemat działania i przepływ zapytań.

    • Schemat wykorzystania tokenów

      Alt text

       

      1. Klient wchodzi na stronę Sprzedawcy. Przeglądarka klienta automatycznie pobiera na swoje urządzenie skrypt Espago JS z serwera Espago. Skrypt tworzy formularz, który wyodrębnia się na stronie Sprzedawcy a która jest zabezpieczona przez https (TSL). Pobrany przez posiadacza karty skrypt Espago.js posiada klucz publiczny, 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 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 paramet "card_token" i ma wartość w postaci "cc_xxxxxxxxxx".
      5. Aplikacja Sprzedawcy wysyła do Espago żądanie utworzenia profilu klienta (zapytanie na /api/clients) lub żądanie dokonania płatności (zapytanie na /api/charges) przesyłając ID tokenu odebrane od klienta.
      6. Bramka Espago odpowiada na zapytanie, przesyłając dane utworzonego profilu klienta lub płatności. 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.
    • 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

        ParametrObligatoryjnośćWartości domyślneZnaczenie
        public_keyobowiązkowyKlucz publiczny Merchanta
        liveopcjonalnytrueParametr, który wskazuje gdzie będą wysyłane dane do utworzenia tokenu. Parametr 'true' oznacza wysyłanie danych na środowisko produkcyjne, parametr 'false' na środowisko testowe.
        formopcjonalny#espago_formNazwa formularza
        card_numberopcjonalny#espago_card_numberNumer karty klienta
        first_nameopcjonalny#espago_first_nameImię właściciela karty
        last_nameopcjonalny#espago_last_nameNazwisko właściciela karty
        monthopcjonalny#espago_monthMiesiąc ważności karty
        yearopcjonalny#espago_yearRok ważności karty
        cvcopcjonalny#espago_verification_valueNumer weryfikacyjny karty
        customopcjonalnyfalseWartość 'true' pozwala na zdefiniowanie własnych parametrów success i error.
        successopcjonalnyfunction(data) {}Funkcja callback. Akcje w niej zawarte wykonują się w przypadku otrzymania pozytywnej odpowiedzi zwrotnej.
        erroropcjonalnyfunction(data) {}Funkcja callback. Akcje w niej zawarte wykonują się w przypadku wystąpienia błędu podczas komunikacji z serwerem.
        submitopcjonalnytrueZatwierdzenie formularza i wysłanie danych.
      • Niezbędne pola formularza


        ID PolaTyp polaZnaczenie
        espago_card_numbertextNumer karty klienta
        espago_first_nametextImię klienta
        espago_last_nametextNazwisko klienta
        espago_monthtextMiesiąc wygaśnięcia karty
        espago_yeartextRok wygaśnięcia karty
        espago_verification_valuetextKod potwierdzenia
        Uwaga!
        Podane ID pola są wymagane przy ustawieniach standardowych i mogą ulegać zmianie w zależności od zastosowanych wartości parametrów konstruktora z poprzedniego rozdziału.
      • create_token()

        Główna akcja skryptu komunikująca się z bramką. Na podstawie wcześniej określonego klucza publicznego merchant jest identyfikowany, a wszelkie przesłane dane karty wiązane z tokenem.

        espago.create_token();
        Uwaga!
        Domyślnie funkcja espago.create_token() wykonuje akcję submit. Możliwe jest jej wyłączenie poprzez zawarcie w niej dodatkowych argumentów funkcji zawartych poniżej (kolejno wyłączenie akcji submit oraz czynności na wypadek powodzenia i błędu):
        espago.create_token({
          submit: false,
          success: function(data) { alert("success"); },
          error: function(data) { alert("error"); }
        });
      • Walidacja pól formularza po stronie klienta

        Poniżej przedstawione zostały funkcje walidacji pól formularza. W przykładowym kodzie tych funkcji zostały wprowadzone dane podlegające walidacji. W przypadku ich braku, domyślnym parametrem stają się wartości odpowiednich pól formularza.

        validate_card_number()

        Metoda umożliwiająca walidację numeru karty klienta. Przy wprowadzaniu numeru karty z dodatkowymi znakami nie będącymi cyframi, zostaną one zignorowane.

        espago.validate_card_number('4242424242424242') //true
        espago.validate_card_number('42 42 42 42 42 42 42 42') //true
        espago.validate_card_number('42 42 42') //false
        espago.validate_card_number() //domyślnym parametrem wartość pola 'espago_card_number' formularza
        validate_first_name()

        Metoda walidująca imię właściciela karty wprowadzane do formularza płatności.

        espago.validate_first_name('Jan') //true
        espago.validate_first_name('') //false
        espago.validate_first_name() //domyślnym parametrem wartość pola 'espago_first_name' formularza
        validate_last_name()

        Metoda walidująca nazwisko właściciela karty wprowadzane do formularza płatności.

        espago.validate_last_name('Kowalski') //true
        espago.validate_last_name('') //false
        espago.validate_last_name() //domyślnym parametrem wartość pola 'espago_last_name' formularza 
        validate_card_date()

        Metoda walidująca datę ważności karty wprowadzaną do formularza płatności.

        espago.validate_card_date('02', '2017') //true
        espago.validate_card_date(02, 2017) //true
        espago.validate_card_date(2, 17) //false
        espago.validate_card_date() //domyślnymi parametrami wartości pól 'espago_month' i 'espago_year' formularza
        validate_card_cvc()

        Metoda walidująca kod CVC karty wprowadzany do formularza płatności.

        espago.validate_card_cvc('123') //true
        espago.validate_card_cvc('12') //false
        espago.validate_card_cvc('xyx') //false
        espago.validate_card_cvc() //domyślnym parametrem wartość pola 'espago_verification_value' formularza
      • Demo online

        https://github.com/espago/espago-1.2.js-demo
    • Pobieranie danych o tokenie

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

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

      Przykład z wykorzystaniem CURL

      curl -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.
    • Espago iFrame

      W tej metodzie, skrypt Espago utworzy 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.

       

      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.
      • 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: pl, en.
        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.
  • 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".

    • 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).
      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ć zautoryzowane

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

      • kraju wystawcy karty
      • nazwy banku
      • rodzaju karty

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

      Parametr Opis Uwagi
      card_type Informacja o rodzaju karty C - karta kredytowa
      D - karta debetowa
      - brak informacji
      country Kraj wystawcy karty 3 literowy skrót, ISO_3166-1_alfa-3
      - brak informacji
      bank Nazwa banku Nazwa banku
      - 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}}

    • Strona aktualizacji karty klienta

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

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

      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.

    • Informacja zwrotna przy płatnościach cyklicznych

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

       

      {"id":"sub_WQO0vEpk0-SrqM","state":"processing","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":true,"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).

      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.

      Skrócony opis usługi eDCC znajduje się również na stronie tellmemore.elavon.com

    • Objaśnienie parametrów DCC

      Parametr Opis Uwagi
      multicurrency_indicator Informacja o walucie transakcji. Pole obecne tylko gdy waluta płatnośći 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 Zgodie 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 a 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"}}

      • 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, 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 skryptu Espago JS utworzyć token 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 nie nadają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".

    • 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" 
    • 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.
    • 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 transackji Tak  
          amount kwota transakcji  Tak  
          currency walta 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).

    Płatność przy wykorzystaniu Strony Płatności Espago przebiega następująco:
    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  
      amount kwota transakcji  Tak dwa miejsca po przecinku, rozdzielone kropką np. 10.00, 1.23, 1.20
      currency waluta Tak  
      title opis transakcji Tak  
      description opis klienta Nie  
      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
      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>
  • 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:

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