home Wstęp

link Wypróbuj

Wypróbuj działanie Espago API. Obciąż pierwszego klienta wykonując poniższe kroki:

W pierwszym kroku zostanie wywołany iFrame, który pozwala zebrać i przesłać dane karty bezpośrednio do bramki Espago w celu uzyskania tokenu, a następnie umieści otrzymany token w formularzu na stronie sklepu.
Należy użyć karty o numerze 4242 4242 4242 4242, dacie wygaśnięcia 02/2025 i kodzie CVV 123.
Wypróbuj
<!-- konfiguracja iFrame -->
<script 
  async=""
  data-id="EspagoFrameScript"
  data-key="VrYVaA1CjmRooKh63YYv"
  data-live="false"
  data-button="Pay"
  src="https://js.espago.com/iframe-1.0.js">
</script>

<!-- formularz z tokenem -->
<form id="espago_form" 
      action="/charge_client" 
      accept-charset="UTF-8" 
      method="post">
</form>
Następnie zostanie wysłane właściwe zapytanie do bramki Espago. Składa się ono kolejno z: nagłówka wskazującego wersję API, danych uwierzytelniających użytkownika, kwoty i waluty. Pole card zwiera token uzyskany w poprzednim kroku, dzięki czemu aplikacja sprzedawcy nie musi przetwarzać danych karty..
curl -i https://sandbox.espago.com/api/charges \
 -H "Accept: application/vnd.espago.v3+json" \
 -u ms_771eUTliRiZ:SeCreT_P@ssw0rD \
 -d "amount=10" \
 -d "currency=pln" \
 -d "card=[card_token]" \
 -d "description=Espago docs"
Spodziewana odpowiedź od bramki Espago w formacie json. Kluczowymi informacjami są tutaj id i state. Więcej na temat back requestów
{
 "id":"pay_7715NocOaPcNTL9O",
 "description":"Espago docs", 
 "channel":"elavon",
 "amount":"10.00",
 "currency":"pln",
 "state":"executed",
 [...]
}

link Opis bramki

Bezpieczeństwo

Dane karty są przechowywane w Espago w sposób bezpieczny, zgodny z najwyższym poziomem standardu PCI DSS - Level 1, co weryfikują i potwierdzają cykliczne, zewnętrzne audyty. Administratorem danych związanych z płatnościami i kart przypisywanych do Profilu Klienta jest Sprzedawca, ale nie ma on dostępu do najbardziej wrażliwych danych jak numer karty. Również nie da się obciążyć Profilu Klienta na rzecz Sprzedawcy innego niż ten, który przesłał dane karty.

W celu zapewnienia odpowiedniego poziomu bezpieczeństwa zalecane jest na stronie sklepu zastosowanie certyfikatów SSL (HTTPS). We wszystkich sposobach integracji wrażliwe dane kart płatniczych (m.in. numer karty) są przesyłane bezpośrednio od klienta do bramki Espago, z pominięciem serwisu Sprzedawcy. Zrzuca to ze Sprzedawcy odpowiedzialność za przechowywanie lub przetwarzanie danych kart, a certyfikacja PCI-DSS ogranicza się do wypełnienia ankiety po podpisaniu umowy z Elavon.

Architektura aplikacji

Architektura aplikacji jest zgodna ze wzorcem REST. 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. Wymaganym kodowaniem do przesłania danych jest UTF-8, a odpowiedzi na zapytania API zwracane są w formacie JSON.

Czas zapytań

Dla zapytań API sugerowany timeout (maksymalny czas oczekiwania na odpowiedź z Espago) to 30 sekund, przy czym zdecydowana większość płatności jest przetwarzana w czasie poniżej 2 sekund. Zaleca się, aby unikać wywoływania cyklicznych zadań w godzinach 3:30-5:30 CEST (01:30- 03:30 UTC) w dni robocze, w tych terminach mogą być przeprowadzane planowane prace serwisowe w bramce Espago.

link Sposoby integracji

Istnieją trzy możliwości integracji z bramką płatności Espago:

Płatność na stronie Sprzedawcy wykorzystująca iframe


Umieszczenie skryptu wywołującego iframe (EspagoFrame) lub formularza obsługiwanego przez skrypt Espago JS, który pozwala zebrać dane karty od klienta, a następnie realizacja wszystkich operacji związanych z autoryzacją poprzez zapytania API (czytaj więcej)

Przekierowanie klienta ze strony Sprzedawcy na stronę płatności Espago


Przekierowanie klienta z odpowiednimi parametrami dotyczącymi płatności na bezpieczną stronę płatności Espago, a następnie odebranie informacji o wyniku płatności z bramki Espago i przyjęcie klienta przekierowanego z powrotem na stronę Sprzedawcy. (czytaj więcej)

Integracja strony Sprzedawcy z systemem Przelewy24

Płatności kartowe Espago/Elavon mogą być jedną z lub jedyną metodą płatności dostępną dla klienta poprzez Przelewy24. W takim scenariuszu nie ma potrzeby bezpośredniej 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

link Zmiany i wymagania wynikające z PSD2

Bramka Espago udostępnia funkcje i mechanizmy potrzebne do realizacji płatności w sposób zgodny z dyrektywą PSD2. Z punktu widzenia Sprzedawców korzystających z płatności kartowych nowe wymagania obejmują przede wszystkim dwa elementy:

1. Każda płatność internetowa inicjowana przez klienta wykorzystuje silne uwierzytelnienie (SCA) jakim jest 3-D Secure;
2. Każda subskrypcja lub zapisanie karty do obciążeń wielokrotnych rozpoczyna się od płatności z SCA, a późniejsze płatności są odpowiednio oznaczone.

Brak wdrożenia SCA będzie skutkował od 1 stycznia 2021 zwiększeniem odrzuceń płatności z użyciem kart wydanych przez europejskie banki. Do Sprzedawców należy weryfikacja i dostosowanie swojej integracji do nowych wymagań.

  1. Jeśli używają Państwo aktualnego APIv3 z włączonym zabezpieczeniem 3D-Secure dla płatności jednorazowych nie muszą Państwo wprowadzać zmian.
  2. Jeśli przed rozpoczęciem płatności cyklicznych dokonują Państwo płatności z flagą cof=storing (funkcja dodana w sierpniu 2019r) to najprawdopodobniej również nie muszą Państwo wprowadzać zmian.
  3. Jeśli Państwa aplikacja używa APIv3 ale bez użycia 3D-Secure, to zabezpieczenie musi zostać włączone i używane dla wszystkich jednorazowych płatności oraz dla płatności inicjujących recurring.
  4. Jeśli używają Państwo starego APIv2 konieczna jest migracja do APIv3.
  5. Jeśli rozpoczynają Państwo płatności cykliczne od utworzenia profilu klienta osobnym zapytaniem i jego podwójnej autoryzacji - należy zmienić proces rejestracji klienta wprowadzając SCA.

Lista kontrolna zmian związanych z PSD2

Aby upewnić się, że spełniają Państwo wymagania związane z PSD2 dotyczące akceptacji kart, należy wykonać poniższe sprawdzenie:

Pytanie Zakres zastosowania Odpowiedź: TAK
Ewentualna lista zmian
Odpowiedź: NIE
Ewentualna lista zmian
1. Czy Państwa integracja opiera się na Espago API v3? Dotyczy wszystkich klientów. Aby upewnić się czy integracja korzysta z API v3 należy sprawdzić czy stosują Państwo odpowiednie nagłówki żądań Tak - należy sprawdzić, czy spełnione są wymagania z dalszych punktów; Nie - należy dokonać integracji z API v3: migracja z API v2 ;
2. Czy wszystkie płatności inicjowane przez posiadacza karty (CIT) wykorzystują silne uwierzytelnienie (SCA)? Dotyczy wszystkich serwisów. Silne uwierzytelnienie to mechanizm 3-D Secure dostarczany przez Espago. Tak - wymaganie spełnione; Nie - należy wprowadzić zmiany:

- jeśli serwis ma wyłączony mechanizm 3-D Secure na prośbę akceptanta, należy skontaktować się z Espago w celu jego włączenia w konkretnej dacie. Od dnia 1.01.2021 r. wszystkie serwisy będą miały włączony mechanizm 3-D Secure obligatoryjnie.

- jeśli w zapytaniach API o obciążenie stosowany jest parametr “skip_3ds”, należy z niego zrezygnować. Jeśli silna weryfikacja nie jest możliwa ze względu na charakter płatności, należy wykorzystać mechanizm moto (parametr “moto” w żądaniu API).
3. Czy płatności cykliczne, wielokrotne i inicjowane przez sprzedawcę (MIT) są poprzedzone silnym uwierzytelnianiem przy ich inicjowaniu? Dotyczy serwisów wykorzystujących mechanizmy:

- Subskrypcji Espago

- płatności cyklicznych, wielokrotnych i innych w oparciu o mechanizm card on file (COF)
Tak - wymaganie spełnione; Nie - należy dostosować proces płatności aby był zgodny z wymaganiami opisanymi w rozdziale Płatności wielokrotne lub subskrypcje Espago - w zależności od wykorzystywanego mechanizmu.
Istotna zmiana - Profil Klienta (który może być użyty do dalszych obciążeń) jest tworzony podczas płatności inicjującej z parametrem cof=storing, wykorzystującej SCA. Nie ma potrzeby tworzenia go osobnym żądaniem tworzenia profilu klienta.
4. Czy profil klienta dotychczas tworzony był na podstawie tokenu karty, jeszcze przed pierwszą płatnością? Dotyczy płatności wykonywanych zapisanym profilem klienta (w tym Subskrypcji Espago). Tak - należy zmienić proces, aby był zgodny z wymaganiami opisanymi w rozdziale Płatności wielokrotne lub subskrypcje Espago.
Co prawda nadal można stworzyć profil klienta bez wywołania płatności z SCA, ale w takim przypadku pierwsza płatność z użyciem tego profilu musi wykorzystywać SCA lub być oznaczona jako MOTO (nie może być np. płatnością cykliczną z parametrem cof=recurring)
Nie - jeśli wykorzystywany jest profil klienta stworzony przy zastosowaniu płatności z cof=storing - wymaganie spełnione;
5. Czy dotychczas, przy tworzeniu profilu klienta bez wykonania płatności z SCA, wykorzystują Państwo mechanizm automatycznej autoryzacji karty (opcja zaznaczona w panelu secure.espago.com)? Dotyczy płatności wykonywanych zapisanym profilem klienta (w tym Subskrypcje Espago). Tak - należy zrezygnować z tej opcji (zostanie ona wyłączona w 2021 r.).

Wprowadziliśmy inny mechanizm, pozwalający określić czy dany profil może być wykorzystany do płatności: jeśli profil klienta został stworzony na podstawie płatności z SCA, jest do niego dodany parametr sca_payment, który świadczy o prawidłowo dokonanej płatności z SCA, co jest podstawą do wykorzystania tego profilu klienta do obciążeń cyklicznych i wielokrotnych. W przypadku braku tego parametru, profil nie nadaje się do obciążeń innych niż z udziałem posiadacza karty (z SCA) lub MOTO.
Nie - wymaganie spełnione;
6. Czy podczas zapisu karty klienta jego początkowa płatność z 3DS lub autoryzacja była natychmiastowo zwracana? Dotyczy głównie Sprzedawców z płatnościami cyklicznymi rozpoczynającymi obciążenia np. od darmowego okresu Tak - należy zmienić integrację, aby początkowa płatność z SCA/3DS nie była wycofywana, gdyż jej wycofywanie będzie przez bank rozumiane jako wycofanie zgody klienta na późniejsze obciążenia. W celu zapisania karty klienta bez jego obciążania docelowo odpowiednia będzie płatność z cof=storing na kwotę 0 PLN, jednak w listopadzie 2020 obserwujemy w niektorych bankach wciąż błędy (odrzucenia) przy takiej autoryzacji, więc sugerujemy kwoty 1 i wyższe oraz weryfikację (np. tu w dokumentacji) sytuacji na przełomie 2020/2021; Nie - nie ma potrzeby wprowadzania zmian;

assignment Integracja

link Proces integracji

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

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). Lista wymogów technicznych i merytorycznych Elavon dostępna jest w dokumentacji w dziale “Do pobrania”.
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

Polega ona na zmianie parametrów połączenia na odpowiadające środowisku produkcyjnemu - zmiany wymaga 5 parametrów:

  1. adres bramki
  2. ID aplikacji
  3. hasło API
  4. klucz publiczny
  5. wartość parametru live w konstruktorze Espago

Po zintegrowaniu się ze środowiskiem produkcyjnym środowisko testowe pozostaje w dalszym ciągu do dyspozycji Klienta. Na prośbę Sprzedawcy Dział Wsparcia Espago może m.in.:

  • Dodać nowy serwis w obrębie konta Sprzedawcy (np. do obsługi innej waluty)
  • Włączyć/wył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ą.

W przypadku problemów z kompatybilnością zaleca się przeczytanie dokładnych wymagań kompatybilności

link Czynności początkowe

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

  1. Przejść do zakładki:
  2. Przejść do okna edycji serwisu klikając przycisk “Edytuj”.
  3. Uzupełnić pole “Hasło API” i “Potwierdzenie hasła API” - wpisana wartość odpowiada za prawidłową autoryzację konta i nie może być ujawniona osobom postronnym wymagane jest również wypełnienie pola “Email BOK”.
  4. Zaakceptować zmiany klikając przycisk “Zatwierdź”.

Naciskając przycisk “Wyświetl” powinny nam się ukazać podobne informacje:

link Niezbędne nagłówki żądań

Do poprawnej komunikacji z aplikacją wykorzystywane są następujące nagłówki HTTP:

Nagłówek Obligatoryjność Zawartość
Authorization1 Wymagany Basic app_id:password
Accept Wymagany application/vnd.espago.v3+json

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.


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

link Dane kart testowych

Podczas testowania płatności należy używać wyłącznie wymienionych niżej testowych numerów kart. Aby uzyskać konkretną odpowiedź z bramki (sukces lub błąd) należy użyć odpowiednich danych w polu daty ważności lub kodu CVV karty widocznych w drugiej i trzeciej tabelce.

Podczas testów zabronione jest używanie rzeczywistych numerów kart.

Numer karty Marka Waluta 3-D Secure DCC Wymagane w testach
4012001037141112 Visa PLN Verified by Visa Nie Tak
5432670000041258 Mastercard PLN Mastercard SecureCode Nie Tak
4242424242424242 Visa PLN Nie Nie Tak
375987000000005 American Express PLN Amex SafeKey Nie Jeśli umowa przewiduje Amex
4012888888881881 Visa USD Verified by Visa Tak Jeśli umowa przewiduje DCC
5555555555554444 Mastercard HKD Mastercard SecureCode Tak Jeśli umowa przewiduje DCC
4242421111112239 Visa HKD Nie Tak Jeśli umowa przewiduje DCC
4917484589897107 Visa PLN Nie Nie Jeśli będą stosowane płatności COF
- ta karta wymaga użycia
kodu CVV do każdej transakcji,
nie nadaje się do subskrypcji i COF=recurring.



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 Kod odpowiedzi
01-05 transakcja zaakceptowana 00
06 wynik losowy, 50% szans powodzenia transakcji.
Przydatne przy testach subskrypcji.
nd.
07 transakcja odrzucona 04, 07, 41, 43
08 transakcja odrzucona 51
09 transakcja odrzucona 13
10 transakcja odrzucona 00
11 transakcja odrzucona 54
12 transakcja odrzucona 05, 57, 61



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

link Połączenie testowe

Aby zweryfikować poprawność swojego połączenia należy wysłać zapytanie na adres https://sandbox.espago.com/api/test. Espago w odpowiedzi wysyła parametr state - wartość passed oznacza, iż połączenie jest poprawnie skonfigurowane. Wartość failed oznacza niepoprawne połączenie - wtedy tablica warnings zawiera informacje na temat przyczyn niepoprawnego połącznia.

Przykładowe zapytanie

curl -i https://sandbox.espago.com/api/test \
-X POST \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/test")
request = Net::HTTP::Get.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/test');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);
{
  "state":"passed",
  "warnings":[]
}
{
  "state":"failed",
  "warnings":[
    {
      "title":"Access denied",
      "message":"Wrong app_id or password."
    },
    {
      "title":"Wrong request headers",
      "message":"Check your 'Accept' header."
    },
        . . .
  ]
}

exit_to_app Strona płatności

link Przykładowy formularz

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. Demo można zobaczyć na warzywko.espago.com

Możesz użyć testowej karty o numerze 4242 4242 4242 4242 i dacie wygaśnięcia 02/2025. Kod CVV może być dowolny (Więcej o kartach testowych)

link Działanie secure web page

1. Przesłanie formularza

Klient naciskając przycisk przesyła ukryte parametry związane z płatnością do bramki Espago metodą POST i zostaje przekierowany na stronę płatności Espago.

<form accept-charset="UTF-8" action="https://sandbox.espago.com/secure_web_page" id="espago_secure_web_page" method="post">
  <input name="api_version" type="hidden" value="3" />
  <input name="app_id" type="hidden" value="ms_771eUTliRiZ" />
  <input name="kind" type="hidden" value="sale" />
  <input name="session_id" type="hidden" value="1559655843622983577" />
  <input name="amount" type="hidden" value="10.00" />
  <input name="currency" type="hidden" value="PLN" />
  <input name="title" type="hidden" value="payment_id:294" />
  <input name="description" type="hidden" value="Platność - Jan Kowalski" />
  <input name="positive_url" type="hidden" value="http://example.com/payments/ok" />
  <input name="negative_url" type="hidden" value="http://example.com/payments/bad" />
  <input name="ts" type="hidden" value="1444044688" />
  <input name="checksum" type="hidden" value="938ee2f7729ac4ba1a7c98f5ead8b167" />
  <button name="button" type="submit" class="btn espago-blue pulse">Kupuję</button>
</form>

2. Wykonanie płatności

Klient podaje swoje dane, a następnie bramka Espago przetwarza te informacje i próbuje obciążyć klienta. W tym momencie rownież zostaje wysłany back request do sklepu z informacją o transakcji.

3. Przekierowanie użytkownika

W zależności od powodzenia operacji klient zostaje przekierowany na adres odpowiadający pozytywnemu lub negatywnemu wynikowi. W tym miejscu warto poinformować klienta o statusie płatności i ewentualnym powodzie niepowodzenia.

link Parametry formularza

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

Parametr Opis Wymagany Uwagi
api_version wersja api done 3
app_id Identyfikator aplikacji done
kind rodzaj transakcji done sale - sprzedaż
preauth - rezerowanie środków przyszłego obciążenia
session_id Identyfikator transakcji done Losowy, unikalny ciąg znaków wygenerowany przez serwis Sprzedawcy
amount kwota transakcji done dwa miejsca po przecinku oddzielone kropką
np: 10.00, 1.23, 1.20
currency waluta done
title opis transakcji done Tytuł płatności wyświetlany klientowi na ekranie płatności kartą, np. “Zamówienie 123/2019”. Musi zawierać od 5 do 100 znaków. Parametr, który powinien zawierać identyfikator z systemu Sprzedawcy umożliwiający identyfikację płatności przy odbiorze Zapytania zwrotnego, np. unikalny numer zamówienia.

Pole “title” będzie następnie widoczne jako pole description we właściwościach płatności (np. w back requście).
description opis klienta Opis klienta (nie płatności).
email email klienta E-mail klienta, na które przyjdzie powiadomienie o transakcji.
positive_url adres powrotny Adres, na który zostanie przekierowany klient po udanej transakcji
negative_url adres powrotny Adres, na który zostanie przekierowany klient po nieudanej transakcji
locale język transakcji pl, en, da, ru, sv
reference_number numer referencyjny transakcji Tekst ref. transakcji - widoczny w raportach Elavon. Długość do 20 znaków, tylko alfanumeryczne oraz -_ (myślnik i belka).
channel kanał płatności Kanał, którym ma być procesowana płatność. Domyślnie “elavon_cc”
ts znacznik czasowy done
checksum suma kontrolna done Funkcja skrótu MD5 dla ciągu znaków (app_id + kind + session_id + amount + currency + ts + checksum_key). Łącznikiem pól jest znak “|”
Poszczególne pozycje koszyka zakupów, gdzie INDEX jest numerem od 0-100 - niewymagany
shopping_cart_items [INDEX][description] Opis pozycji w koszyku done
shopping_cart_items [INDEX][quantity] Ilość sztuk w danej pozycji done
shopping_cart_items [INDEX][value] Cena done
shopping_cart_items [INDEX][image_url] Url obrazu do danej pozycji musi być HTTPS/SSL




Przykładowy sposób wypełnienia formularza:

<form id="espago_secure_web_page" action="https://sandbox.espago.com/secure_web_page" accept-charset="UTF-8" method="post">
  <input type="hidden" name="api_version" value="3" />
  <input type="hidden" name="app_id" value="ms_0CvDQqhnS" />
  <input type="hidden" name="kind" value="sale" />
  <input type="hidden" name="session_id" value="2HWSjEs5G4RcXZjqHqWA" />
  <input type="hidden" name="amount" value="42.94" />
  <input type="hidden" name="currency" value="PLN" />
  <input type="hidden" name="title" value="order_165" />
  <input type="hidden" name="description" value="Transakcja - jan@kowalski.pl 42.94" />
  <input type="hidden" name="email" value="jan@kowalski.pl" />
  <input type="hidden" name="positive_url" value="http://example.com/payments/ok"  />
  <input type="hidden" name="negative_url" value="http://example.com/payments/bad"  />
  <input type="hidden" name="ts" value="1559230283" />
  <input type="hidden" name="checksum"value="532839977fb76ca06ea635c7a936c7db" />
  <input type="hidden" name="shopping_cart_items[0][description]" value="Orange Papaya" />
  <input type="hidden" name="shopping_cart_items[0][quantity]" value="2" />
  <input type="hidden" name="shopping_cart_items[0][value]" value="8.99" />
  <input type="hidden" name="shopping_cart_items[1][description]" value="Cauliflower" />
  <input type="hidden" name="shopping_cart_items[1][quantity]"value="1" />
  <input type="hidden" name="shopping_cart_items[1][value]" value="3.99" />
  <input type="hidden" name="shopping_cart_items[2][description]" value="Purple Bell Peppers" />
  <input type="hidden" name="shopping_cart_items[2][quantity]" value="3" />
  <input type="hidden" name="shopping_cart_items[2][value]" value="6.99" />
  <div class="button">
    <button name="button" type="submit">Kup Teraz!</button>
  </div>
</form>

link Płatność z Championem

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

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

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

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

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

require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/secure_web_page_register")
request = Net::HTTP::Post.new(uri)
request.basic_auth("app_id", "password")
request["Accept"] = "application/vnd.espago.v3+json"
request.body = "amount=49.99&currency=PLN&description=Opis transakcji&kind=sale&service_client_id=xxxxxx&client_description=xxxxx"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/secure_web_page_register');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "amount=49.99&currency=PLN&description=Opis transakcji&kind=sale&service_client_id=xxxxxx&client_description=xxxxx");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, 'app_id' . ':' . 'password');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);
{
  "id": "pay_IZTq8l_qaHuOHH",
  "description": "Opis transakcji",
  "amount": "49.99",
  "currency": "PLN",
  "state": "new",
  "created_at": 1550224439,
  "transaction_id": "tn_CLN2HhetI",
  "redirect_url": "https://sandbox.espago.com/secure_web_page/tn_CLN2HhetI"
}

open_in_browser iFrame

link Działanie iFrame

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

1. Wywołanie iFrame

W pierwszym kroku klient wywołuje iFrame Espago poprzez naciśnięcie przycisku (uruchomienie musi zostać wywołane ręcznie za pomocą funkcji showEspagoFrame()). Następnie podaje dane swojej karty, które po zatwierdzeniu formularza w iFrame zostają przesłane asynchronicznie do bramki Espago w celu wygenerowania tokenu.

 <script src="https://js.espago.com/espago-1.2.js"></script>
 <script 
   async=""
   data-id="EspagoFrameScript"
   data-key="VrYVaA1CjmRooKh63YYv"
   data-live="false"
   data-button="Pay"
   src="https://js.espago.com/iframe-1.0.js">
 </script>

 <a id="pay_btn">Zapłać</a>
$('#pay_btn').click( () => {
  showEspagoFrame()
})

2. Odebranie tokenu

Po odebraniu tokenu skrypt Espago wyszukuje formularz o id espago_form, a następnie tworzy w nim pole <input type="hidden" id="card_token" name="card_token" value="[TOKEN]">. Formularz zostaje wysłany na podany adres.

<form id="espago_form" 
      action="/charge_client" 
      accept-charset="UTF-8" 
      method="post">
</form>

Jeżeli Token nie zostanie użyty, to kod CVV z tokenu zostanie automatycznie usunięty po maksymalnie 2 dobach od utworzenia, a cały token po 2 miesiącach.

3. Obciążenie

Serwer po otrzymaniu tokenu powinien wysłać zapytanie metodą POST na adres https://sandbox.espago.com/api/charges.

curl -i https://sandbox.espago.com/api/charges \
 -H "Accept: application/vnd.espago.v3+json" \
 -u ms_771eUTliRiZ:SeCreT_P@ssw0rD \    # app_id:pass
 -d "amount=10" \
 -d "currency=pln" \
 -d "card=cc_772ahSzjmMnOt4eIk" \    # token
 -d "description=Espago docs"
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/charges")
request = Net::HTTP::Post.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"
request.body = "amount=10&currency=pln&card=cc_772ahSzjmMnOt4eIk&description=Espago docs"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/charges');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "amount=10&currency=pln&card=cc_772ahSzjmMnOt4eIk&description=Espago docs");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close ($ch);

więcej o parametrach obciążenia

4. Odpowiedź z Espago

Po wykonaniu zapytania o obciążenie klienta Espago zwraca informacje w formacje JSON na temat płatności. Kluczowym parametrem jest state. executed oznacza, iż płatność się powiodła .
Przykładowa odpowiedź od bramki Espago:

{
 "id":"pay_772FThyrtalisvgk",
 "description":"Espago docs",
 "channel":"elavon",
 "amount":"10.00",
 "currency":"pln",
 "state":"executed",
 "client":"cli_772coQy1BaW3F0Zn",
 "created_at":1559649971,
 "card":
 {
  "company":"VI",
  "last4":"4242",
  "year":2020,
  "month":2,
  "first_name":"Adam",
  "last_name":"Kowalski",
  "authorized":null,
  "created_at":1559649956
 },
 "issuer_response_code":"00",
 "reversable":true,
 "transaction_id":"tr_7728ogw8v"
}
więcej o informacjach zwrotnych

5. Odpowiedź - informacja dla klienta

Po zakończeniu płatności niezbędne jest wyświetlenie jej statusu klientowi oraz powodu odrzucenia w przypadku niepowodzenia. Kody błedów dostępne są w dziale do pobrania.

link Parametry ramki

Parametr Wymagany Wartości domyślne Informacje
async done “” Nie może mieć wartości innej niż domyślna
data-id done EspagoFrameScript Nie może mieć wartości innej niż domyślna
src done adres skryptu Nie może mieć wartości innej niż domyślna
data-key done String, Klucz publiczny Merchanta
data-live 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 pl String, Język w jakim będzie wyświetlony formularz w standardzie ISO 639-1. Dostępne: en, pl, bg, cs, da, de, el, es, et, fi, fr, ga, hr, hu, it, lt, lv, mt, nl, no, pt, ro, ru, sk, sl, sv.
data-success 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 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 function() {} Funkcja wywoływana w przypadku, gdy użytkownik zamknie okno dialogowe (klikając “x” lub klawisz “Esc”).
data-target 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 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 Tekst wyświetlany poniżej nagłówka i nazwy sklepu (pobranej automatycznie z API Espago)
data-button Zapisz (pl) Etykieta tekstowa wyświetlona na przycisku zatwierdzania formularza.
Uwaga - domyślna wartość jest zależna od parametru języka ‘data-lang’

attach_money Płatność jednorazowa

link Parametry obciążenia

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.

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 ID klienta w przypadku obciążenia istniejącego klienta (bez użycia parametru card)
card ID tokenu ID tokenu w przypadku płatności jednorazowej (bez użycia parametru client).
channel Kanał płatności
[opcjonalny]
Kanał, którym ma być procesowana płatność. Domyślnie elavon_cc, dostępne również m.in. six_cc
recurring [opcjonalny]
[wycofywany]
Parametr wycofywany z API, został zastąpiony wartością parametru cof=recurring. Dodanie parametru “recurring=true” wyłącza 3-D Secure i wymusza zakwalifikowanie przez bank (wystawcę karty) transakcji jako cyklicznej.
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) np. gdy recepcja hotelu otrzymała numer karty do obciążenia za pośrednictwem serwisu do bookingowego. Skutkuje m.in. nie sprawdzaniem zabezpieczenia 3D-Secure. Przed użyciem zalecamy konsultację z Espago, flagowanie transakcji jako MOTO musi zostać uwzględnione przy umowie z Acquirerem.
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]
[wycofywany]
Dodanie parametru “skip_3ds=true” Skutkuje nie sprawdzaniem zabezpieczenia 3D-Secure. Nie powinien już być używany, ewentualne wyłączanie 3D-Secure powinno nastąpić przy użyciu innych mechanizmów (np. flagowanie transakcji jako cyklicznej)
reference_number [opcjonalny] Tekst ref. transakcji - widoczny w raportach Elavon. Długość do 20 znaków, tylko alfanumeryczne oraz - _ (myślnik i belka).
locale [opcjonalny] Kod języka w standardzie ISO 639-1, dwuliterowa wartość typu string. Język wykorzystywany przy wyświetleniu strony płatności i/lub w powiadomieniu mailowym.
email [opcjonalny] Adres email, na który ma zostać wysłane powiadomienie e-mail o wyniku tego obciążenia. Wartość typu string. Jeśli parametr jest użyty z profilem klienta posiadającym adres mailowy, to użyty jest przesłany tu w parametrze adres.
skip_email [opcjonalny] Wyłącza powiadomienie mailowe, nawet jeśli użyto profilu klienta z adresem mailowym. Wartość boolowska (true/false, domyślnie: false).
cof [opcjonalny] Wykorzystanie mechanizmu “Card on file”. Możliwe wartości parametru: storing (zapisanie danych kart w postaci profilu klienta, do użycia przy płatności wykonanej z użyciem tokenu, lub (gdy płatność jest wywołana z profilem klienta) aktualizacja płatności referencyjnej (widocznej w profilu klienta jako sca_payment) w profilu klienta), recurring (informacja do banku, że płatność jest częścią subskrypcji, do użycia przy płatnosci wykonanej przy użyciu profilu klienta), unscheduled (płatność nieregularna, wywołana przez Sprzedawcę). Szczegóły w rozdziale COF.
recurring_expiry [opcjonalny] Parametr będzie wykorzystany gdy parametr cof będzie miał wartość storing.
Data wygaśnięcia płatności cyklicznej (data po której nie będą już następować obciążenia) w formacie YYYYMMDD. Jeśli cof=storing a ten parametr nie został podany, to domyślnie przyjmuje datę ważności karty klienta.
UWAGA: wartość tego parametru może zostać wyświetlona Klientowi na stronie Banku w procesie 3-D Secure.
recurring_freq [opcjonalny] Parametr będzie wykorzystany gdy parametr cof będzie miał wartość storing.
Minimalna liczba dni pomiędzy obciążeniami cyklicznymi. Wartość to liczba całkowita. Jeśli cof=storing, a ten parametr nie został podany, to domyślnie przyjmuje wartość recurring_freq=1.
UWAGA: wartość tego parametru może zostać wyświetlona Klientowi na stronie Banku w procesie 3-D Secure.
authentication_ind [opcjonalny] Typ transakcji, opisany w częsci 3-D Secure.
challenge_ind [opcjonalny] Wymuszenie SCA, opisane w części 3-D Secure.
payment_referenced [opcjonalny] Powołanie się na płatność referencyjną (inicjującą) inną niż ta zapisana w profilu klienta, przyjmuje wartość ID płatności. Parametr może zostać użyty tylko przy cof=recurring lub cof=unscheduled. Domyślnie, przy płatnosciach cyklicznych używana jest płatność zapisana w profilu klienta (widoczna jako sca_payment w profilu klienta) zapisana przy płatności z parametrem cof=storing

link Przykładowe obciążenie

curl -i https://sandbox.espago.com/api/charges \
 -H "Accept: application/vnd.espago.v3+json" \
 -u ms_771eUTliRiZ:SeCreT_P@ssw0rD \
 -d "amount=10" \
 -d "currency=pln" \
 -d "card=cc_772ahSzjmMnOt4eIk" \
 -d "description=Espago docs"
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/charges")
request = Net::HTTP::Post.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"
request.body = "amount=10&currency=pln&card=cc_772ahSzjmMnOt4eIk&description=Espago docs"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/charges');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "amount=10&currency=pln&card=cc_772ahSzjmMnOt4eIk&description=Espago docs");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close ($ch);
{
  "id":"pay_773ob8rbBtid0PYd",
  "description":"Espago docs",
  "channel":"elavon",
  "amount":"10.00",
  "currency":"pln",
  "state":"executed",
  "client":"cli_7733nQkDLdlhHmh-",
  "created_at":1561990343,
  "card":{
    "company":"VI",
    "last4":"4242",
    "year":2020,
    "month":2,
    "first_name":"Adam",
    "last_name":"Adam",
    "authorized":null,
    "created_at":1561990328
  },
  "issuer_response_code":"00",
  "reversable":true,
  "transaction_id":"tr_773OKuy0b"
}

Więcej na temat odpowiedzi z serwera znajdziesz tutaj.

{
  "id": "pay_772LFdT3JG6KaAir",
  "description": "order_481",
  "channel": "elavon",
  "amount": "9.99",
  "currency": "PLN",
  "state": "new",
  "client": "cli_772mtwcEVYBfRCJ2",
  "created_at": 1560935536,
  "card": { ... },
  "issuer_response_code": "",
  "transaction_id": "tr_772atPpUX",
  "redirect_url": "https://sandbox.espago.com/3d-secure/tr_772atPpUX",
  "tds_redirect_form": { ... }
}

link 3D Secure

3D Secure jest metodą autoryzacji transakcji w internecie. Polega ona na przekierowaniu użytkownika na stronę banku (lub wyświetlenia iFrame) w celu dodatkowej autoryzacji poprzez np kod przysłany SMS'em, zalogowanie się na stronę banku lub potwierdzenie płatności na smartfonie.
Użycie 3-D Secure przenosi ze Sprzedawcy na Bank Klienta ewentualną odpowiedzialność za nadużycia (oszustwa, płatność kradzioną kartą, niezamówione usługi itp). 3-D Secure jest pierwszą częścią płatności

Obsługiwanie kart posiadających zabezpieczenie 3D Secure jest niezbędne zarówno do poprawnego obsługiwania płatności jednorazowych, jak i zapisania karty w celu użycia jej w płatnościach wielokrotnych/cyklicznych.


Po wywołaniu obciążenia klienta posiadającego zabezpieczenie 3D Secure obiekt płatności posiada status new oraz jeden dodatkowy atrybut - redirect_url. Jest to adres, na który należy przekierować użytkownika w celu autoryzacji transakcji w banku.
Po przekierowaniu transakcja otrzyma status tds_redirected. Klient po dokonaniu płatności na stronie banku zostanie przekierowany do sklepu (URL pozytywnej odpowiedzi / URL negatywnej odpowiedzi), a na adres żądania zwrotnego przyjdzie informacja dotycząca statusu płatności [executed, rejected, failed].

Do 2019r standardem było 3-D Secure v1.0.2, aktualnie wprowadzane jest EMV 3-D Secure v2.2.0. Z punktu widzenia Klienta różnica jest niewielka, ale dla Sprzedawcy są wartościowe zmiany:
- pojawiło się wiele dostępnych parametrów mogących lepiej dostosować uwierzytelnienie 3DS do danego typu transakcji lub biznesu. Espago ustawia parametry 3DSv2 w sposób optymalny dla większośći mechanizmów recurringowych, Merchant będzie miał możliwość manipulowania tymi opcjami w specyficznych sytuacjach, [przewidziane udostępnienie funkcji: styczeń 2021].
- Dostępna jest autoryzacja na kwotę “0” PLN/EUR/itd, przydatna do zapisania danych karty bez obciążania klienta.
- Przy płatności z flagą cof=storing zawsze wymuszane jest SCA (czyli przekierowanie klienta i jego świadome potwierdzenie transakcji). W płatnosciach jednorazowych Bank może na podstawie danych przeglądarki lub/i urządzenia mobilnego podjąć decyzję o autoryzacji i przekierować Klienta od razu do sklepu bez(tzw. frictionless flow, np. przy kwotach poniżej 50 euro, u sprzedawcy u którego już robił zakupy itp).

Dla standardowych płatności (jednorazowych, cyklicznych) Espago ustawia odpowiednie parametry uwierzytelnienia 3-D Secure v2, w specyficznych sytuacjach Sprzedawca ma możliwość wywołać płatność z dodatkowymi wskazaniami dotyczącymi 3DS (choć pośrednio również płatności).

Parametr przy wywoływaniu płatnosci Opis Uwagi
authentication_ind Typ transakcji, których dotyczy uwierzytelnienie

Domyślnie:
“01” dla płatności jednorazowych
“02” dla płatnosci z cof=storing
Musi składać się z 2 cyfr. Możliwe wartości:
‘01’: ‘Payment transaction’
‘02’: ‘Recurring transaction’
‘03’: ‘Instalment transaction’
‘04’: ‘Add card’ [do użycia przy płatności inicjującej, gdy późniejsze płatności będą nieregularne (np. opłaty po wypożyczaniu roweru z użyciem cof=unscheduled)
‘05’: ‘Maintain card’
‘06’: ‘Cardholder verification as part of EMV token ID&V’
challenge_ind Wymuszenie uwierzytelnienia z SCA

Domyślnie:
“01” dla płatności jednorazowych
“04” wymuszone zawsze dla płatnosci z cof=storing (brak możliwości zmiany challenge_ind przy zapisie karty)
Musi składać się z 2 cyfr. Możliwe wartości:
‘01’: ‘No preference’
‘02’: ‘No challenge requested’
‘03’: ‘Challenge requested (3DS Requestor preference)’
04’: ‘Challenge requested (SCA wymagane np. ze względu na PSD2)’
‘05’: ‘No challenge requested (transactional risk analysis is already performed)’
‘06’: ‘No challenge requested (Data share only)’
‘07’: ‘No challenge requested (strong consumer authentication performed)’
‘08’: ‘No challenge requested (utilise whitelist exemption if no challenge required)’
‘09’: ‘Challenge requested (whitelist prompt requested if challenge required)’

link eDCC

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

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

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

1. Informacja o wyborze waluty

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

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.

Jeżeli dana karta nie podlega transakcji DCC, płatność przebiega dalej normalnie.

curl -i https://sandbox.espago.com/api/charges \
-H "Accept: application/vnd.espago.v3+json" \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD \
-d "amount=49.99" \
-d "currency=pln" \
-d "client=cli_772uWYtgJXnL_F9I" \ # klient z kartą w innej walucie
-d "description=Opis transakcji"
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/charges")
request = Net::HTTP::Post.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"
request.body = "amount=49.99&currency=pln&client=cli_772uWYtgJXnL_F9I&description=Opis transakcji"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/charges');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "amount=49.99&currency=pln&client=cli_772uWYtgJXnL_F9I&description=Opis transakcji");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);
{
  "id": "pay_7724xNjCpNPWYevy",
  "description": "order_502",
  "channel": "elavon",
  "amount": "17.98",
  "currency": "PLN",
  "state": "dcc_decision",
  "client": "cli_772KDwdXQIbqpFp3",
  "created_at": 1560942887,
  "card": { ... },
  "issuer_response_code": "",
  "transaction_id": "tr_772_lDLkv",
  "dcc_decision_information": {
    "cardholder_currency_name": "HKD",
    "cardholder_amount": "39.74",
    "conversion_rate": "2.210174",
    "redirect_url": "https://sandbox.espago.com/secure_web_page/tr_772_lDLkv",
    "mark_up_percentage": "300"
  }
}

Parametr Opis Uwagi
cardholder_currency_name Nazwa waluty posiadacza karty Zgodie ze standardem ISO 4217
cardholder_amount kwota transakcji w rodzimej walucie posiadacza karty
conversion_rate kurs wymiany waluty
redirect_url odłużenie eDCC po stronie Espago Należy przekierować klienta na ten adres jeżeli decyzja eDCC nie jest rozstrzygana po stronie sklepu
mark_up_percentage oprocentowanie od przewalutowania

2. Decyzja eDCC

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

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

curl -i https://sandbox.espago.com/api/charges/(ID_TRANSAKCJI)/dcc_decision \
-H "Accept: application/vnd.espago.v3+json" \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD \
-d "decision=Y"
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/charges/")
request = Net::HTTP::Post.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"
request.set_form_data(
  "decision" => "Y",
)

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/charges/(ID_TRANSAKCJI)/dcc_decision');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "decision=Y");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);
{
  "id": "pay_77219xeZ-8xvxUdE",
  "description": "order_523",
  "channel": "elavon",
  "amount": "39.96",
  "currency": "PLN",
  "state": "executed",
  "client": "cli_772KEkYX7Vq54DJe",
  "created_at": 1560949080,
  "issuer_response_code": "00",
  "reversable": true,
  "transaction_id": "tr_7722-YsY6",
  "multicurrency_indicator": "Z",
  "dcc_decision_information": {
    "cardholder_currency_name": "HKD",
    "cardholder_amount": "88.32",
    "conversion_rate": "2.210174"
  }
}

multicurrency_indicator - Pole obecne tylko gdy waluta płatności jest inna niż waluta serwisu.
N - Karta bez DCC
Y - DCC odrzucone przez posiadacza karty
Z -DCC możliwe i zaakceptowane przez posiadacza karty

Może nastąpić sytuacja, w której klient z zabezpieczeniem 3D Secure będzie chciał zapłacić w innej walucie. Z tego powodu należy obsłużyć scenariusz, w którym klient najpierw podejmuje decyzję DCC, a następnie zostaje przekierowany na adres zabezpieczenia 3D Secure.
Po podaniu informacji na temat przewalutowania bramka Espago wysyła odpowiedź zawierającą dane do przekierowania 3D Secure, a płatność ma stan “tds_prtcpt”

Przykładowa odpowiedź

{
  "id": "pay_7724l5jFs9EP6Xr0",
  "description": "order_526",
  "channel": "elavon",
  "amount": "16.98",
  "currency": "PLN",
  "state": "tds_prtcpt",
  "client": "cli_772TVMYGxKECDKPZ",
  "created_at": 1560953142,
  "issuer_response_code": "",
  "transaction_id": "tr_772C5ke_m",
  "redirect_url": "https://sandbox.espago.com/3d-secure/tr_772C5ke_m",
  "tds_redirect_form": { ... },
  "multicurrency_indicator": "Z",
  "dcc_decision_information": {
    "cardholder_currency_name": "HKD",
    "cardholder_amount": "37.53",
    "conversion_rate": "2.210174"
  }
}

W niektórych sytuacjach, gdy Sprzedawca spodziewa się, że większość klientów będzie korzystać z eDCC, może odpytać bramkę Espago o aktualne kursy walut. Dzięki temu, istnieje możliwość poinformowania klienta o kursie przewalutowania DCC jeszcze przed rozpoczęciem płatności.

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. Wymagane są standardowe nagłówki do autoryzacji zapytania.

curl -i https://sandbox.espago.com/api/dcc/rates \
-H "Accept: application/vnd.espago.v3+json" \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/dcc/rates")
request = Net::HTTP::Get.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/dcc/rates');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);
{
  "timestamp":"2017-12-01T04:48:00.000+01:00",
  "mark_up_percentage":"300",
  "currency_name":"PLN",
  "currency_code":"985",
  "rates":{
    "USD":"0.285413",
    "ARS":"2.546572",
    "RON":"1.136708",
    "CZK":"6.997923",
    "EUR":"0.255955",
    "KWD":"0.085902",
    "MYR":"1.025983",
    "MXN":"4.372453",
    "GBP":"0.183134",
    ...
  }
}

link 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]
tds2_challenge [Status dostępny tylko w przypadku włączonej opcji 3D-Secure v2]. Klient został przekierowany na stronę 3D-Secure v2 (stronę banku lub iFrame), oczekiwanie na jego powrót.
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.

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

Parametr “reject_reason” może służyć jako ogólna informacja o odrzuceniu lub odmowie płatności. Konkretna przyczyna odrzucenia płatności przez bank podana jest w formie kodu w parametrze “issuer_response_code”.

Komunikat Znaczenie Przyczyna Uwagi
declined transakcja odrzucona Nieaktywowany rodzaj usługi (MOTO, ecommerce), również brak środków Możliwość ponowienia zależy od kodu odpowiedzi.
card expired karta utraciła ważność Przekroczony termin ważności karty Nie wolno ponawiać od kodu odpowiedzi.
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 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.

Parametr ten jest odpowiedzią pochodzącą bezpośrednio z banku - wydawcy karty. Szczegółowe informacje o przyczynie jego wystąpienia i sposobie rozwiązania problemu posiadacz karty powinien kierować do swojego banku.


Gdy następuje odmowa autoryzacji, nie należy ponawiać obciążeń z użyciem tej samej karty, chyba że przyczyna odrzucenia została usunięta (wyszczególnione przypadki poniżej, np. issuer_response_code=51). Wielokrotne ponawianie prób obciążeń karty w przypadkach opisanych UWAGA: Nie wolno powtarzać obciążeń dla tej karty. może skutkować blokadą konta sprzedawcy po stronie agenta rozliczeniowego.

Kody issuer_response_code, po których nie należy ponawiać obciążeń karty: 03, 04, 07, 12, 14, 15, 41, 43, 54, 57, 62, 78, 82, N8, 93, R0, R1, R3,B04, B14, B15, B41, B43, B54

Kod błędu Oryginalny komunikat Znaczenie Opis/Proponowany komunikat
00 Approved and completed successfully Gdy stan płatności executed - brak błędu. Transakcja przebiegła prawidłowo.
00 nd. Gdy stan płatności rejected - odrzucenie transakcji na poziomie operatora (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 karty. Prosimy spróbować ponownie później lub skontaktować się z Działem Wsparcia Technicznego Espago.
01,02 Refer to card issuer Kod własny wydawcy karty ODMOWA - problem z autoryzacją. Niezbędny kontakt z bankiem.
03 Invalid merchant Nieprawidłowe/niepełne dane akceptanta lub nieaktywne konto. ODMOWA - problem z autoryzacją.
04 Pick up card (no fraud) 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 wolno powtarzać obciążeń dla tej karty.
05 Do not honor Nie honorować Płatność została odrzucona przez bank bez podania szczególnej przyczyny. Prawdopodobnie płatności typu MOTO/eCommerce/subskrypcyjne nieaktywne lub niewspierane. Potrzebny kontakt klienta z bankiem w celu wyjaśnienia.
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.
07 Pick up card, special condition (fraud account) Karta zastrzeżona ODMOWA - karta zastrzeżona.
12 Invalid transaction Nieprawidłowa transakcja ODMOWA - transakcja niedostępna dla tej karty. Skontaktuj się z Twoim bankiem w celu wyjaśnienia przyczyny problemu
13 Invalid amount or currency conversion field overflow Nieprawidłowa kwota transakcji (przekroczenie limitu) lub błędne przeliczenie walut. 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.
14 Invalid account number (no such number) Nieprawidłowy numer karty lub konta ODMOWA - podano nieprawidłowy numer karty. Należy użyć innej karty. UWAGA: Nie wolno powtarzać obciążeń dla tej karty.
15 No such issuer Nie zidentyfikowano wydawcy karty ODMOWA - podano nieprawidłowy numer karty. Należy użyć innej karty. UWAGA: Nie wolno powtarzać obciążeń dla tej karty.
30 Format error Błędny format danych wiadomości autoryzacyjnej. ODMOWA - skontaktuj się z Twoim bankiem w celu wyjaśnienia przyczyny problemu
41 Lost card, pick up (fraud account) Karta oznaczona jako zgubiona. ODMOWA - karta oznaczona jako zgubiona – skontaktuj się z Twoim bankiem w celu wyjaśnienia przyczyny problemu. UWAGA: Nie wolno powtarzać obciążeń dla tej karty.
43 Stolen card, pick up (fraud account) Karta oznaczona jako skradziona ODMOWA - karta oznaczona jako skradziona – skontaktuj się z Twoim bankiem w celu wyjaśnienia przyczyny problemu. UWAGA: Nie wolno powtarzać obciążeń dla tej karty.
51 Not sufficient funds Niewystarczające środki na koncie lub przekroczenie limitu dla danego typu płatności. ODMOWA - niewystarczające środki na koncie lub przekroczenie limitu. Zweryfikuj stan swojego konta i spróbuj ponownie.
54 Expired card or expiration date is missing Przeterminowana karta. ODMOWA - karta utraciła ważność. Użyj innej karty.UWAGA: Nie wolno powtarzać obciążeń dla tej karty.
57 Transaction not permitted to cardholder 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 Suspected fraud Podejrzenie oszustwa ODMOWA - skontaktuj się z Twoim bankiem w celu wyjaśnienia przyczyny problemu
61 Exceeds approval amount limit Przekroczenie limitu transakcji dla karty ODMOWA - przekroczenie limitu kwoty transakcji. Skontaktuj się z bankiem w celu zmiany limitu lub użyj innej karty.
62 Restricted card (card invalid in this region or country) 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 Exceeds withdrawal frequency limit 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 Allowable number of PIN entry tries exceeded 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 Blocked, first used Nowa, nieaktywowana karta. ODMOWA – Karta nie została aktywowana. Aktywuj kartę i spróbuj ponownie.
82, N7 Negative CAM, dCVV, iCVV, or CVV results Nieprawidłowy kod CVV ODMOWA – Nieprawidłowy kod CVV. Sprawdź poprawność wprowadzonych danych i spróbuj ponownie. UWAGA: Nie wolno powtarzać obciążeń dla tej karty.! Może to zostać uznane za próbę oszustwa!
91,92,94,98 Issuer or switch inoperative Usługa tymczasowo niedostępna, spróbuj Ponownie ODMOWA – Tymczasowy błąd po stronie banku, spróbuj ponownie.
B04, B14, B15, B41, B43, B54 Abort Płatność zablokowana przez Espago, ze względu na próbę płatności nieaktywaną lub zastrzeżoną kartą. Należy zaktualizować profil klienta przy użyciu innej karty. ODMOWA - karta utraciła ważność lub jest zablokowana i można jej obciążyć. Użyj innej karty.
E3 3D-Secure not available Błąd systemu weryfikacji 3D-Secure w banku. ODMOWA – Błąd banku. Spróbuj ponownie, lub skonsultuj się z bankiem lub sprzedawcą.
E4 3D-Secure authentication failed. Podjęta weryfikacja 3D-Secure w banku nie powiodła się. ODMOWA – Bank zwrócił informacje o nieudaniej autoryzacji klienta.
E5 3D-Secure not available Tymczasowy błąd przy weryfikacji 3D-Secure ODMOWA – Tymczasowy błąd przy weryfikacji 3D-Secure, spróbuj ponownie później lub skontaktuj się ze sprzedawcą.

link 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

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

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

Odpowiedź przy próbie użycia nieisniejącego/usuniętego profilu klienta, profilu klienta należącego do innego konta lub profilu klienta bez danych karty płatniczej

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

link 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”).

Maksymalny okres zablokowania konkretnej kwoty na karcie klienta jest zdefiniowany w regulaminie instytucji wydającej kartę. Ten okres zależy więc od wydawcy karty. Zwykle jest to czas nie dłuższy niż 1-2 tygodnie.

curl -i https://sandbox.espago.com/api/charges \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD \
-d "card=cc_7724fuzWy0SYasoLV" \
-d "amount=49.99" \
-d "currency=pln" \
-d "description=Opis transakcji" \
-d "complete=false"
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/charges")
request = Net::HTTP::Post.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"
request.body = "card=cc_7724fuzWy0SYasoLV&amount=49.99&currency=pln&description=Opis transakcji&complete=false"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/charges');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "card=cc_7724fuzWy0SYasoLV&amount=49.99&currency=pln&description=Opis transakcji&complete=false");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);
{
  "id":"pay_772Zm0D5saC0pEA9",
  "description":"Opis transakcji",
  "channel":"elavon",
  "amount":"49.99",
  "currency":"pln",
  "state":"preauthorized",
  "client":"cli_772yY9NvH2Hyt2DM",
  "created_at":1561559076,
  "card":{ ... },
  "issuer_response_code":"00",
  "completed":false,
  "reversable":true,
  "transaction_id":"tr_772_88A0S"
}

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

curl -i https://sandbox.espago.com/api/charges/pay_772Zm0D5saC0pEA9/complete \
-X POST \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD \
-d "amount=35"

require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/charges/pay_772Zm0D5saC0pEA9/complete")
request = Net::HTTP::Post.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"
request.set_form_data(
  "amount" => "35",
)

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/charges/pay_772Zm0D5saC0pEA9/complete');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "amount=35");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);
{
  "id":"pay_772Zm0D5saC0pEA9",
  "description":"Opis transakcji",
  "channel":"elavon",
  "amount":"35.00",
  "currency":"pln",
  "state":"executed",
  "client":"cli_772yY9NvH2Hyt2DM",
  "created_at":1561559076,
  "issuer_response_code":"00",
  "reversable":true,
  "transaction_id":"tr_772JlqSER"
}

link Wycofanie istniejącej płatności przed rozliczeniem

Wycofanie płatności może odbyć się jedynie przed jej rozliczeniem i każdorazowo dotyczy całej kwoty transakcji. W przypadku środowiska testowego płatności rozliczane są co godzinę, a produkcyjnego co 24 godziny (poniędzy godziną 22:30 a 00:00). Po tym czasie możliwy jest jedynie ich zwrot (refund).
Wycofanie płatności jest również sposobem na anulowanie preautoryzacji, w ten sposób na koncie bankowym klienta szybciej zniknie rezerwacja środków. Wycofanie preautoryzacji może zostać dokonane w ciągu kilku/kilkunastu dni od dnia dokonania preautoryzacji.


W przypadku gdy płatnosć została już rozliczona w Elavon (w banku) próba wycofania płatności nie powiedzie się.

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ąć

curl -i https://sandbox.espago.com/api/charges/pay_772Zm0D5saC0pEA9 \
-X DELETE \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/charges/pay_772Zm0D5saC0pEA9")
request = Net::HTTP::Delete.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/charges/pay_772Zm0D5saC0pEA9');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');

curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);
{
  "id":"pay_772Zm0D5saC0pEA9",
  "description":"Opis transakcji",
  "channel":"elavon",
  "amount":"35.00",
  "currency":"pln",
  "state":"reversed",
  "client":"cli_772yY9NvH2Hyt2DM",
  "created_at":1561559076,
  "issuer_response_code":"00",
  "transaction_id":"tr_772JlqSER"
}

link Wyświetlanie obciążeń

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ć

curl -i https://sandbox.espago.com/api/charges/pay_771MKFI-15SIK1Pm \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/charges/pay_771MKFI-15SIK1Pm")
request = Net::HTTP::Get.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/charges/pay_771MKFI-15SIK1Pm');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);

{
  "id":"pay_771MKFI-15SIK1Pm",
  "description":"Espago docs",
  "channel":"elavon",
  "amount":"10.00",
  "currency":"pln",
  "state":"executed",
  "client":"cli_771Xsyr9GkpN8iTp",
  "created_at":1559130872,
  "issuer_response_code":"00",
  "transaction_id":"tr_771EQhf18"
}

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 Wartość domyślna
page Numer strony 1 (pierwsza strona)
per Liczba obciążeń na każdej stronie 25 (25 obciążeń)
client ID klienta, którego mają dotyczyć transakcje wszyscy klienci
curl -i https://sandbox.espago.com/api/charges \
-X GET \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD \
-d "page=1" \
-d "per=5" \
-d "client=cli_772YYE_98HM1DmAD"
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/charges")
request = Net::HTTP::Get.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"
request.set_form_data(
  "client" => "cli_772YYE_98HM1DmAD",
  "page" => "1",
  "per" => "5",
)

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/charges');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "page=1&per=5&client=cli_772YYE_98HM1DmAD");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);
{
  "count":4,
  "charges":[
    {
      "id":"pay_772xZV-3uSUTIxPz",
      "description":"Payment #88",
      "channel":"elavon",
      "amount":"79.00",
      "currency":"pln",
      "state":"executed",
      "client":"cli_772YYE_98HM1DmAD",
      "created_at":1561645210,
      "card":{ ... },
      "issuer_response_code":"00",
      "reversable":true,
      "transaction_id":"tr_772bk-yP2"
    },
    {
      "id":"pay_772X3bE9o9JHdpZt",
      "description":"Payment #23",
      "channel":"elavon",
      "amount":"19.99",
      "currency":"pln",
      "state":"executed",
      "client":"cli_772YYE_98HM1DmAD",
      "created_at":1561645191,
      "card":{ ... },
      "issuer_response_code":"00",
      "reversable":true,
      "transaction_id":"tr_772ZZm3Zt"
    },
    . . .
  ]
}

autorenew Płatności wielokrotne

link Czym są płatności wielokrotne i cykliczne

Mianem płatności wielokrotnych określamy płatności, które odbywają się z użyciem zapisanych w Espago danych karty. Dzielą się one na:

  • płatności inicjowane przez posiadacza karty (Cardholder Initiated Transaction - CIT);

  • płatności inicjowane przez sprzedawcę (Merchant Initiated Transactions - MIT).

Do płatności inicjowanych przez posiadacza karty (CIT), z użyciem zapisanych danych karty, zaliczane są płatności typu one-click, dokonywane za zakup - bez konieczności wprowadzania pełnych danych karty, jednak z wykorzystaniem mechanizmów silnej weryfikacji (SCA).

Płatności inicjowane przez sprzedawcę, to takie, które nie wymagają udziału posiadacza karty, i są realizowane na podstawie umowy sprzedawcy posiadaczem karty, wyrażającym zgodę na jej obciążanie. Są to:

  • płatności cykliczne (recurring payments) - za usługi świadczone w sposób ciągły lub cykliczny, na stałą kwotę, pobierane przez Sprzedawcę w równych odstępach;

  • płatności dokonywane jako wyrównanie salda klienta, za usługi nieregularnie, na różne kwoty;

  • spłata rat kartą;

  • płatności specyficzne dla branży, np. opłata no-show dla rezerwacji hotelowych, rozszerzenie usługi w ramach najmu.

Płatności cykliczne (recurring payments) - subskrypcje

Realizowanie cyklicznych obciążeń kart klientów w ramach bramki Espago możliwe jest na dwa sposoby:

Płatności wielokrotne realizowane po stronie sprzedawcy Płatności cykliczne realizowane po stronie Espago
  • 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).
  • Gdy wysokość i częstotliwość opłat są stałe, np. miesięczny abonament.

Ten rozdział opisuje płatności inicjowane przez mechanizmy po stronie Sprzedawcy. Więcej informacji na temat subskrypcji Espago można znaleźć w rozdziale Subskrypcje Espago.

link Scenariusz płatności wielokrotnych

Aby spełniać wymogi organizacji kartowych oraz regulatora rynku płatności, prawidłowy przebieg płatności z wykorzystaniem zapisanej w Espago karty musi przebiegać następująco:

  1. Należy wywołanie płatność z parametrem cof=storing na kwotę równą przyszłemu obciążeniu cyklicznemu lub 0 jednostek walutowych. Płatność ta spowoduje stworzenie w bramce Espago profilu klienta z zapisanymi danymi karty. W odpowiedzi na request API, Sprzedawca otrzymuje szczegóły płatności, w tym identyfikator płatności, profilu klienta i adres do przekierowania w celu realizacji SCA (3-D Secure).
  2. Opcjonalnie, zaraz po płatności z SCA można wywołać płatność z wykorzystaniem stworzonego profilu klienta z określona wartością parametru cof, w celu sprawdzenia, czy karta obsługuje płatności typu MIT - zobacz: Problem kart nie nadających się do płatności cyklicznych.
  3. Następnie, Sprzedawca inicjuje płatności zgodnie z warunkami umowy zawartej z posiadaczem karty, żądaniem do API zawierającym identyfikator profilu klienta, dodając parametr cof o wartości zgodnej z charakterem płatności. Wartości parametru cof

Parametr cof jest konieczny do poprawnego oznaczenia płatności inicjowanych przez sprzedawcę. W przypadku jego braku, płatność z wykorzystaniem zapisanego profilu klienta będzie traktowana jako płatność inicjowana przez posiadacza karty i wymagała przekierowania w celu silnej autoryzacji.
Wartość recurring parametru cof zastępuje wcześniejsze oznaczenie płatności jako recurring=true w bramce Espago. Parametr recurring bramce Espago jest wycofywany.


Uwaga
Gdy zapisane dane karty są wykorzystywane w płatności inicjowanej przez klienta, należy powinąć parametr cof.

link Zasady i dobre praktyki płatności cyklicznych

Działanie Opis / Komentarz
Płatności inicjowane przez sprzedawcę (recurring, płatności wielokrotne) muszą być poprzedzone silnym uwierzytelnieniem. Przed rozpoczęciem serii płatności inicjowanych przez sprzedawcę (MIT, czyli subskrypcji, recurring i płatności wielokrotnych) należy dokonać płatności z silnym uwierzytelnieniem (SCA), korzystającym z mechanizmów 3-D Secure. Zaleca się, aby płatność ta opiewała na taką samą kwotę co późniejsze obciążenia (w przypadku subskrypcji) lub na kwotę 0 (zero) jednostek w danej walucie (nie dojdzie wtedy do obciążenia salda klienta, ale zostanie dokonane uwierzytelnienie i autoryzacja w banku).
Nie należy wycofywać płatności inicjującej zapisanie karty, chyba że w związku z rezygnacją. Jeśli Klient nie ma być obciążony ale Sprzedawca chce zapisać jego kartę (np. darmowy okres usługi) zaleca się, aby płatność z flagą cof=storingdokonać na kwotę 0 (zero) jednostek w danej walucie (nie dojdzie wtedy do obciążenia salda klienta, ale zostanie dokonane uwierzytelnienie i autoryzacja w banku). Wycofanie płatności może być przez bank rozumiane jako rezygnacja usługi, i skutkować odrzuceniami późniejszych transakcji cyklicznych.
Należy ograniczać do minimum ponawianie płatności w przypadku odrzucenia Organizacje kartowe wprowadziły następujące ograniczenia w zakresie ponawiania próby obciążenia, w przypadku gdy płatność zostanie odrzucona:
- maksymalnie 1 próba obciążenia dziennie;
- maksymalnie 3 próby obciążenia w ciągu 16 dni. Po tym okresie nie wolno dokonywać dalszych prób obciążenia.
Nie należy kumulować zaległych płatności Należy unikać sytuacji, gdy kilka zaległych, nieudanych płatności klienta skutkuje wieloma próbami obciążeń. W praktyce, jeśli klient zalega z wieloma płatnościami, to jeśli próba jednej się nie powiedzie, pozostałe próby też zakończą się niepowodzeniem.
Należy przerwać subskrypcję gdy karta nie nadaje się do płatności Jeśli kod odrzucenia wskazuje na blokadę karty lub inny przypadek wskazany w tabeli kodów odrzuceń, należy zaprzestać dalszych obciążeń, ponieważ ta karta nie jest i nie będzie już aktywna.
Przy zmianie kwoty płatności cyklicznych, klient powinien ponownie wykonać płatność z silnym uwierzytelnieniem. Zmiana kwoty obciążeń cyklicznych, a więc zmiana warunków umowy wymaga ponownego silnego uwierzytelnienia klienta (SCA)
Dokonanie silnej autoryzacji - wymagającej udziału klienta - jest dla banku potwierdzeniem akceptacji nowego cyklu obciążeń.
Należy używać preautoryzacji jeśli spodziewamy się, że kwota będzie zwrócona, lub docelowe obciążenie będzie tylko na część kwoty preautoryzacji.
Należy unikać preautoryzacji jeśli nie jest ona konieczna.
Preautoryzacja umożliwia blokadę środków z wykorzystaniem silnego uwierzytelnienia, bez jej pobierania.
W zależnosci od umowy z Elavon Visa/MasterCard mogą pobierać stałą, drobną opłatę za każdą preautoryzację (poza prowizją od wykonanej płatności).

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

Większość kart płatniczych nadaje się do jednorazowych płatności Internetowych oraz cyklicznych (o ile ich właściciele włączą w swoim banku obsługę tych płatności i ustawią odpowiednie limity kwotowe). Istnieje jednak część kart, którymi można dokonać jednorazowych płatności internetowych, ale które 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.

Zarówno dla Sprzedawcy jak i Klienta byłaby niewygodna sytuacja, w której udaje się pomyślnie dodać kartę i dokonać pierwszej płatnosci (z SCA) a po miesiącu okazuje się, że dalsze płatności tą kartą nie są możliwe.

Aby unikać takiej sytuacji warto zaraz po dodaniu karty (płatność z cof=storing i silnym uwierzytelnieniem 3D-Secure ) dokonać preautoryzacji z parameterem cof=recurring. Po udanej preautoryzacji (state=preauthorized) można ją wycofać, a kartę klienta uznać za nadajacą się do płatności cyklicznych.

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 cof=recurring. Część banków ma politykę odrzucania transakcji internetowych bez CVV, przy jednoczesnym akceptowaniu transakcji oznaczonych jako “recurring” bez CVV, a od 1 stycznia 2021 będzie to dotyczyło wszystkich europejskich banków.

Krok Działanie Opis
1 Płatność inicjująca z zapisaniem profilu klienta Sprzedawca wywołuje płatność z parameterem cof=storing, na kwotę która będzie później cyklicznym obciążeniem lub 0zł (Elavon). Należy spodziewać się, że klient będzie musiał przejść weryfikację 3D-Secure.
POWODZENIE PŁATNOŚCI: karta obsługuje płatności internetowe, można przejść do kroku 2. Ta płatność nie powinna być wycofywana/zwracana. Po pomyślnej płatności pozostaje do późniejszego użycia profil klienta cli_xxxxxxxxxx.
NIEPOWODZENIE PŁATNOŚCI: karta nie obsługuje płatności internetowych, więc na pewno nie uda się kolejna próba obciążenia1,3.
2 Utworzenie subskrypcji
lub
Obciążenie klienta w ramach pierwszej opłaty
lub
Druga autoryzacja lub preautoryzacja
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ążenia1.

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.

link Płatności cykliczne (recurring) i powtarzające się (one-click, rozszerzające)

Czym jest card on file?

Card on file jest usługą umożliwiającą zapisanie danych karty płatniczej w Espago - w celu dokonywania obciążeń klienta bez konieczności ponownego wprowadzania danych karty przez jej posiadacza. Określenie Card on file oraz parametr cof funkcjonuje w bramce Espago od lipca 2019r.

Aby skorzystać z card on file w Espago należy:

  • wykonać płatność z silnym uwierzytelnieniem SCA (3D-Secure) i wartością cof=storing (zapisanie karty w ramach card on file) w żądaniu API. Dane zostaną zapisane w Profilu Klienta, a w odpowiedzi zostanie przesłany jego unikalny identyfikator. Dokonanie pierwszej płatności w opisany powyżej sposób jest konieczne aby móc dokonywać kolejnych obciążeń.
  • Wywołanie kolejnych płatności przy użyciu odczytanego Profilu Klienta w modelu card on file. Z punktu widzenia acquirera i banku te płatności będą powiązane z płatnością inicjującą.

Funkcjonalność

Dane karty w Profilu Klienta można aktualizować, a profil - w razie potrzeby - usunąć żądaniem API. Card on file w Espago daje pełnię możliwości wykorzystania potencjału płatności przewidzianych przez organizacje kartowe, co opisane jest w dalszych częściach rozdziału. Obciążenia na podstawie zapisanych danych karty dzielą się na:

  • transakcje inicjowane przez sprzedawcę (Merchant Initiated Transaction) na podstaiwe umowy, np. płatności cykliczne, odroczone, wyrównanie salda;
  • transakcje inicjowane przez posiadacza karty (Cardholder Initiated Transactions) np. one-click.

Płatności inicjowane przez sprzedawcę (Merchant Initiated Transaction)

Po poprawnym przeprocesowaniu płatności inicjującej z wykorzystaniem silnego uwierzytelnienia (SCA), można dokonać kolejnych obciążeń w procesie inicjowanym przez Sprzedawcę - na podstawie umowy zawartej z posiadaczem karty. Przykłowe obciążenia tego typu to:

  • comiesięczna płatność abonamentowa za usługę lub członkostwo w klubie/siłowni;
  • wyrównanie salda po wykonanej usłudze zleconej przez klienta np. przejazd taksówką lub wypożyczenie samochodu na minuty.

Płatności inicjowane przez posiadacza karty

Płatności inicjowane przez posiadacza karty, np. typu one-click muszą być oznaczone jako cof=unscheduled. Są to płatności, które następują w wyniku akcji dokonanej przez posiadacza karty, np.:

  • potwierdzenie zakupu w sklepie internetowym przyciskiem “Płacę”;
  • zakup usługi w aplikacji mobilnej.

link Parametr COF - wartości

Parametr cof przyjmuje wartości jest typu string.

Każdą płatność związaną z zapisaniem karty lub użyciem zapisanej karty i inicjowaną przez sprzedawcę należy oznaczać parametrem cof. W przypadku braku tego parametru, płatność z użyciem profilu klienta traktowana jest jako inicjowana przez klienta i wymaga silnej weryfikacji SCA (3-D Secure).

Płatność inicjująca

storing - powoduje zapisanie danych karty i zwraca identyfikator profilu klienta, który może być użyty dla przyszłych płatności. Płatność ta powinna opiewać na kwotę równą każdej kolejnej płatności cyklicznej lub w innych przypadkach - na dowolną kwotę.

Płatności inicjowane przez sprzedawcę (MIT)- zlecenia stałe (standing instructions)

recurring - płatności cykliczne o stałym interwale mniejszym niż rok, w okresie świadczenia usługi w sposób ciągły lub usług świadczonych cyklicznie;
unscheduled - płatności przy użyciu zapisanych danych karty, na stałą lub różną kwotę, która nie jest wykonywana zgodnie z określonym harmonogramem lub interwałem, np. wyrównanie salda za usługę świadczoną na żądanie (np. carsharing, czasowe wypożyczanie hulajnóg);
instalment - płatności ratalne za wykonaną usługę, zgodnie z umową zawartą z posiadaczem karty [usługa zostanie włączona w 2021]

Płatności inicjowane przez sprzedawcę (MIT) - specyficzne dla branży (industry-specific)

delayed_charge - płatność uzupełniająca (odroczona) po wykonaniu usługi.
Przykładowe zastosowanie - w hotelach, żegludze, wypożyczalni pojazdów.

no-show - płatność na podstawie zawartego umowie uprawnienia sprzedawcy do obciążenia karty w przypadku, gdy z przyczyn leżących po stronie posiadacza karty usługa nie mogła być wykonana.
Przykładowe zastosowanie - niepojawienie się gościa w przypadku rezerwacji bezzwrotnej.

reauthorisation - płatność za zakup dokonany po pierwotnej autoryzacji, może odzwierciedlać różne, szczególne przypadki, np. rozszerzenie usługi ponad pierwotną kwotę autoryzacji.
Przykładowe zastosowanie:
* w eCommerce - przy podzielonej dostawie lub jej opóźnieniu - gdy pierwotna autoryzacja nastąpiła tylko na część kwoty odpowiadającej częściowej dostawie i konieczne jest obciążenia za kolejną część;
* przy przedłużeniu najmu pojazdu lub pobytu w hotelu;

resubmission - płatność za wykonaną usługę, ponowiona w związku z nieuzyskaniem autoryzacji podczas pierwszej próby obciążenia karty;

poll Subskrypcje Espago

link Działanie subskrypcji Espago

Subskrypcje Espago to mechanizm płatności cyklicznych, realizowanych w sposób automatyczny - z określoną częstotliwością i stałą kwotą obciążenia. Usługa ta pozwala Sprzedawcy zdefiniować plany i na ich podstawie uruchamiać subskrypcje. Automatyzacja jest realizowana po stronie Espago i nie wymaga każdorazowo inicjowania nowego obciążenia przez Sprzedawcę zapytaniem do API.

Do stworzenia subskrypcji niezbędny jest także obiekt klienta z przypisanymi danymi karty kredytowej. Łącząc plan z obiektem klienta tworzy się subskrypcje.

  1. 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.
  2. Sprzedawca inicjuje płatność z silnym uwierzytelnieniem (SCA - 3D-Secure) i parametrem cof=storing, na kwotę odpowiadającą pojedynczemu obciążeniu w ramach planu. Jeśli płatność się powiedzie, Sprzedawca w odpowiedzi otrzumuje identyfikator profilu klienta.
  3. Po utworzeniu profilu klienta, Sprzedawca może uruchomić dla niego subskrypcję. W momencie utworzenia subskrypcji (o ile nie jest to subskrypcja opóźnionym startem) następuje pierwsza próba obciążenia. Jeśli obciążenie się powiedzie, subskrypcja zostaje uruchomiona.
  4. 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.

Informacje o płatnościach cyklicznych (stanach, dotychczasowych próbach obciążeń itd) są zbierane w postaci faktur. Dostępne są one tylko przy płatnościach cyklicznych realizowanych po stronie Espago.

link Konfiguracja

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

  1. Przejść do zakładki
  2. Przejść do okna edycji serwisu wybierając przycisk “Edytuj”
  3. Ustawić adres url żądania zwrotnego (więcej na temat żądań zwrotnych w rozdziale “Back request”)
  4. 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, a w środowisku testowym krótsze czast (np. liczone w minutach).



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

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

link Plany

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

Tworząc plan ustala się takie dane jak: typ okresu obciążenia (np. day, month), wartość okresu obciążenia (w przypadku typu okresu period=7 oraz period_unit=day uzyskujemy cykliczność obciążania co 7 dni) oraz kwota pojedyńczego obciążenia. Wszelkie dotyczące tworzenia planów znajdują się w poniższych podrozdziałach.

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ładowe zapytanie o utworzenie planu:

curl -i https://sandbox.espago.com/api/plans -H \
'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD \
-d "description=opis planu" \
-d "period_unit=month" \
-d "period=1" \
-d "amount=50" \
-d "currency=pln"


require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/plans")
request = Net::HTTP::Post.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"
request.body = "description=opis planu&period_unit=month&period=1&amount=50&currency=pln"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end


$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/plans');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "description=opis planu&period_unit=month&period=1&amount=50&currency=pln");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close ($ch);

{
  "id":"pl_77299uAqqIu4a6eQB",
  "description":"opis planu",
  "period":1,
  "period_unit":"month",
  "amount":"50.0",
  "currency":"pln",
  "created_at":1559739533
}


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ć

curl -i https://sandbox.espago.com/api/plans/ID \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD


require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/plans/ID")
request = Net::HTTP::Get.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end


$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/plans/ID');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close ($ch);

{
  "id":"pl_77299uAqqIu4a6eQB",
  "description":"opis planu",
  "period":1,
  "period_unit":"month",
  "amount":50.0,
  "currency":"pln",
  "created_at":1559739533
}


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ąć

curl -i https://sandbox.espago.com/api/plans/ID \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD \
-X DELETE 

require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/plans/ID")
request = Net::HTTP::Delete.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end


$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/plans/ID');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');

curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close ($ch);

W odpowiedzi wysyłamy - Status: 204 NoContent

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

Reszta paramterów i wartości jest identyczna, jak przy tworzeniu nowego 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.

curl -i https://sandbox.espago.com/api/plans/ID \
-X PUT -u ms_771eUTliRiZ:SeCreT_P@ssw0rD \
-d "description=Aktualzacja planu" \
-d "period_unit=month" \
-d "period=1" \
-d "amount=75" \
-d "currency=pln"


require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/plans/ID")
request = Net::HTTP::Put.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request.body = "description=Aktualzacja planu&period_unit=month&period=1&amount=75&currency=pln"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end


$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/plans/ID');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "description=Aktualzacja planu&period_unit=month&period=1&amount=75&currency=pln");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');

curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close ($ch);

W odpowiedzi wysyłamy - Status: 204 No Content

Pobieranie listy dostępnych planów następuje w wyniku wysłania żądania metodą GET na adres: https://sandbox.espago.com/api/plans

curl -i https://sandbox.espago.com/api/plans \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD 


require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/plans")
request = Net::HTTP::Get.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end


$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/plans');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close ($ch);

{
  "count":3,
  "plans":[
  {
    "id":"pl_772F0N8AqpLJ8tUhK",
    "description":"Karnet EXCLUSIVE PRO",
    "period":1,
    "period_unit":"month",
    "amount":119.0,
    "currency":"pln",
    "created_at":1559745412
  },
  {
    "id":"pl_772eAqoP50JRfV3Fo",
    "description":"Karnet PRO",
    "period":1,
    "period_unit":"month",
    "amount":79.0,
    "currency":"pln",
    "created_at":1559745395
  },
  {
    "id":"pl_772tYQqPm5QaD9ye9",
    "description":"Karnet NORMAL",
    "period":1,
    "period_unit":"month",
    "amount":50.0,
    "currency":"pln",
    "created_at":1559745382
  }]
}


link Subskrypcje

Subskrypcja (abonament) jest to przypisanie planu do klienta.

Domyślnie subskrypcja działa od momentu jej uruchomienia (następuje jest wtedy pierwsze obciążenie), i kolene obciążaenia w ramach tej subskrypcji 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 maksymalnie do 4 godzin później).

Subskrypcja jest zatrzymywana gdy:

  • pierwsza płatnosć się nie powiedzie (czyli subskrypcja 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ż możliwość uruchomienia 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.

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. Wartość musi być znacznikiem czasu w formacie unix. Domyślnie (bez parametru start_time) subskrypcja jest uruchamiana w momencie wywołania żądania. Parametr wymaga wartości czasu unix pomiędzy: 12h po zapytaniu oraz przed czasem zdefioniowanym jako kolejne wywołanie (period). Szczegóły w następnym rozdziale.
curl -i https://sandbox.espago.com/api/subscriptions \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD \
-d "client=client_id" \
-d "plan=plan_id"
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/subscriptions")
request = Net::HTTP::Post.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"
request.set_form_data(
  "client" => "client_id",
  "plan" => "plan_id",
)

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/subscriptions');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "client=client_id&plan=plan_id");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close ($ch);
W odpowiedzi poza informacją dotyczącą subskrypcji wysyłamy także dane pierwszego 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 Back request) 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.

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

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ć

curl -i https://sandbox.espago.com/api/subscriptions/ID \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/subscriptions/ID")
request = Net::HTTP::Get.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/subscriptions/ID');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close ($ch);
{
  "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
  }
}

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ąć

curl -i https://sandbox.espago.com/api/subscriptions/ID \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD \
-X DELETE 
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/subscriptions/ID")
request = Net::HTTP::Delete.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/subscriptions/ID');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');

curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close ($ch);
W odpowiedzi wysyłamy - status: 204 No Content

Pobieranie listy aktywnych subskrypcji następuje w wyniku wysłania żądania metodą GET na adres: https://sandbox.espago.com/api/subscriptions. Możliwe jest wysłanie parametrów dodatkowych, lecz nie są one obowiązkowe.

Parametr Opis Wartość domyślna
page Numer strony 1 (pierwsza strona)
per Liczba subskrypcji na każdej stronie 25 (25 subskrypcji)
curl -i https://sandbox.espago.com/api/subscriptions \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD \
-d "page=2" \
-d "per=5"
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/subscriptions")
request = Net::HTTP::Post.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"
request.set_form_data(
  "page" => "2",
  "per" => "5",
)

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/subscriptions');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "page=2&per=5");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close ($ch);

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

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ć. Możliwe jest wysłanie parametrów dodatkowych, lecz nie są one obowiązkowe.

Parametr Opis Wartość domyślna
page Numer strony 1 (pierwsza strona)
per Liczba subskrypcji na każdej stronie 25 (25 subskrypcji)
curl -i https://sandbox.espago.com/api/clients/CLIENT_ID/subscriptions \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD \
-d "page=2" \
-d "per=5"
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/clients/CLIENT_ID/subscriptions")
request = Net::HTTP::Post.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"
request.set_form_data(
  "page" => "2",
  "per" => "5",
)

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/clients/CLIENT_ID/subscriptions');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "page=2&per=5");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close ($ch);

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

link 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ś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

curl -i https://sandbox.espago.com/api/clients/CLIENT_ID/invoices/ \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/clients/CLIENT_ID/invoices/")
request = Net::HTTP::Get.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/clients/CLIENT_ID/invoices/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close ($ch);

{
  "count":1,
  "invoices":[
    {
      "id":"in_7728vjvj-BdSK0B64",
      "date":1559903458,
      "client":"cli_772YYE_98HM1DmAD",
      "subscription":"sub_772pHbFAL2vs-z8g",
      "amount":"119.00",
      "currency":"pln",
      "paid":true,
      "issuer_response_code":"00",
      "attempts":1,
      "next_payment_attempt":null,
      "created_at":1559903458,
      "last_payment":"pay_772Nkgo8MS-25osp"
    }
  ]
}

Znaczenie pól w odpowiedzi:

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

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!

curl -i https://sandbox.espago.com/api/invoices/(:invoice_id)/pay \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/invoices/")
request = Net::HTTP::Post.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/invoices/(:invoice_id)/pay');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close ($ch);
{
  "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,
    "last_payment":"pay_772Nkgo8MS-25osp"
}

Dla opłaconej wcześniej faktury wysyłana jest odpowiedź z kodem błędu 422 "Unprocessable Entity.

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

curl -i https://sandbox.espago.com/api/invoices/ID_FAKTURY \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/invoices/ID_FAKTURY")
request = Net::HTTP::Get.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/invoices/ID_FAKTURY');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close ($ch);
{
  "id":"in_7728vjvj-BdSK0B64",
  "date":1559903458,
  "client":"cli_772YYE_98HM1DmAD",
  "subscription":"sub_772pHbFAL2vs-z8g",
  "amount":"119.00",
  "currency":"pln",
  "paid":true,
  "issuer_response_code":"00",
  "attempts":1,
  "next_payment_attempt":null,
  "created_at":1559903458,
  "last_payment":"pay_772Nkgo8MS-25osp"
}

link Pozycje faktury

Pozycje faktury są informacją na temat jednej płatności dla danego cyklu subskrypcji - zawierają informacje na temat próby opłacenia danej faktury. Jeżeli się ona nie powiedzie powstanie kolejna pozycja faktury i próba ponownego obciążenia wg danej faktury oraz okresu ustawionego w konfiguracji powtarzania nieudanych obciążeń subskrypcji. Więcej o konfiguracji subskrypcji espago można znaleźć w dziale Subskrypcje Espago - konfiguracja.

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
curl -i https://sandbox.espago.com/api/invoice_items \
-H 'Accept: application/vnd.espago.v3+json' \
-u app_id:password \
-d "currency=currency" \
-d "date=unix_time" \
-d "amount=100" \
-d "client=client_id" \
-d "description=Opis transakcji"
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/invoice_items")
request = Net::HTTP::Post.new(uri)
request.basic_auth("app_id", "password")
request["Accept"] = "application/vnd.espago.v3+json"
request.body = "currency=currency&date=unix_time&amount=100&client=client_id&description=Opis transakcji"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/invoice_items');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "currency=currency&date=unix_time&amount=100&client=client_id&description=Opis transakcji");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, 'app_id' . ':' . 'password');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);
{
  "id": "ii_1sbC2i-UHMWJXZH",
  "client": "cli_xNKNXh-_kWu6Qi",
  "description": "Opis transakcji",
  "amount": "100.00",
  "currency": "PLN",
  "created_at": 1381755981
}

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

curl -i https://sandbox.espago.com/api/invoices/(:invoice_id)/line_items \
-H 'Accept: application/vnd.espago.v3+json' \
-u app_id:password
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/invoices/:invoice_id/line_items")
request = Net::HTTP::Get.new(uri)
request.basic_auth("app_id", "password")
request["Accept"] = "application/vnd.espago.v3+json"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/invoices/:invoice_id/line_items');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

curl_setopt($ch, CURLOPT_USERPWD, 'app_id' . ':' . 'password');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);

{
  "count": 1,
  "invoice_items": [
    {
    "id": "ii_1KZ0VBahlukLI2X",
    "client": "cli_OU7k00vEMGi53C",
    "description": "Pozycja 1",
    "amount": "7.00",
    "currency": "PLN",
    "created_at": 1371631057
    }
  ]
}

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

curl -i https://sandbox.espago.com/api/invoice_items/(:id) \
-X DELETE \
-H 'Accept: application/vnd.espago.v3+json' \
-u app_id:password
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/invoice_items/:id")
request = Net::HTTP::Delete.new(uri)
request.basic_auth("app_id", "password")
request["Accept"] = "application/vnd.espago.v3+json"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/invoice_items/(:id)');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');

curl_setopt($ch, CURLOPT_USERPWD, 'app_id' . ':' . 'password');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);
Status uzyskany w odpowiedzi to 204 "No content"

receipt Informacje zwrotne (back request)

link Konfiguracja

Bramka Espago wysyła asynchronicznie do serwisu Sprzedawcy informacje zwrotne w kilku sytuacjach:

  • informacja o statusie płatności - po wykonaniu dowolnej płatności w APIv3.0 (przy płatności z 3D-Secure, request jest wysyłany dopiero po weryfikacji i uzyskaniu odpowiedzi z banku),
  • informacja o statusie płatności - po wykonaniu płatności w ramach subskrypcji,
  • informacja o statusie subskrypcji - gdy status subskrypcji się zmieni, np. gdy zostaje zdezaktywowana,
  • informacja o utworzonym tokenie - domyśnie opcja wyłączona, wykorzystywana przez specyficznych Sprzedawców.

Odpowiedzi o zmianie statusu transakcji przychodzą asynchronicznie na zdefiniowany przez Państwa adres żądania zwrotnego. Zapytania zwrotne powinny wykorzystywać protokół HTTPS (port 443), możliwa też jest komunikacja na port HTTP (port 80). W środowisku testowym Sandbox dodatkowo serwer ma możliwość wysyłania informacji zwrotnych na porty 8002 i 8003.

UWAGA
W przypadku braku odpowiedzi “HTTP 200” z aplikacji Sprzedawcy akcja jest ponawiana przez serwer Espago przez 24h z rosnącym interwałem.

Po uzyskaniu dostępu do panelu merchanta należy wykonać następujące czynności:
1. Przejść do zakładki:
2. Przejść do okna edycji serwisu klikając przycisk “Edytuj”.
3. Uzupełnić pole “URL żądania zwrotnego (application/json v. 3.0.)” - na ten adres wysyłane będą odpowiedzi.
4. Uzupełnić pola “Login BasicAuth (dla URL żądania zwrotnego)” oraz “Hasło BasicAuth (dla URL żądania zwrotnego)”. Za ich pomocą autoryzowanie będą odpowiedzi od bramki Espago.

UWAGA
Walidacja loginu i hasła dla żądań zwrotnych nie jest wymagana, lecz jej stosowanie jest silnie zalecane ze względów bezpieczeństwa.

link Informacja zwrotna przy 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_772sMqGEogv63CSk",
  "description": "order_263",
  "channel": "elavon",
  "amount": "56.94",
  "currency": "PLN",
  "state": "executed",
  "client": "cli_7725o4SHuhgnHAVe",
  "created_at": 1560160387,
  "card": {
    "company": "VI",
    "last4": "4242",
    "year": 2030,
    "month": 1,
    "first_name": "Jan",
    "last_name": "Kowalski",
    "authorized": null,
    "created_at": 1560160386
  },
  "issuer_response_code": "00",
  "reversable": true,
  "transaction_id": "tr_772b9YYzb"
}
Parametr Uwagi Opis
id ID płatności. Umożliwia m.in. późniejsze odszukanie płatności, sprawdzenie statusu, zwrot. Ma postać pay_xxxxxxxxxxxxxxxx i długość 18 lub 20 znaków.
description Opis płatności przesłany w zapytaniu na /api/charges.
channel Kanał płatności.
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 obiekt 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.
tds_status_reason Kod zawierający przyczynę stanu autoryzacji 3D-Secure 2. Opisy tych kodów dostępne są w sekcji Do pobrania jako Kody statusu 3D-Secure.
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/obiekt 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.

link Informacja zwrotna przy płatnościach cyklicznych

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

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

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

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

link 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), jest to funkcja domyślnie wyłączona.
Aby informacja zwortna została wysłana, przy tworzeniu tokenu (POST /api/tokens) konieczne jest dodanie parametru “card[description]” długości 5-60 znaków, z punktu widzenia Sprzedawcy powinien to być unikalny identyfikator.

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 “card[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 w części dotyczącym karty 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.

undo Zwroty

link Zwrot istniejącej płatności po rozliczeniu

W poniższym rozdziale opisane zostały zwroty istniejącej płatności po rozliczeniu. Jeżeli chcesz się dowiedzieć o wycofywaniu istniejącej płatności przed rozliczeniem przejdź tutaj.

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ładowe zapytanie

curl -i https://sandbox.espago.com/api/charges/(:id)/refund \
 -X POST \
 -H 'Accept: application/vnd.espago.v3+json' \
 -u app_id:password \
 -d "amount=n"
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/charges/")
request = Net::HTTP::Post.new(uri)
request.basic_auth("app_id", "password")
request["Accept"] = "application/vnd.espago.v3+json"
request.set_form_data(
  "amount" => "n",
)

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/charges/(:id)/refund');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "amount=n");
curl_setopt($ch, CURLOPT_USERPWD, 'app_id' . ':' . 'password');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);
{
  "id": "pay_COy6zH9fLj1d7K",
  "description": "Opis transakcji",
  "channel": "elavon",
  "amount": "49.99",
  "refunded_amount": "15.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",
  "transaction_id": "tn_AKZ71ysMF"
}

accessibility_new Profil klienta

link Obiekt klienta

Profil klienta w Espago służy do przechowywania danych klienta, ze szczególnym uwzględnieniem danych karty. Profil klienta, który posiada kartę płatniczą zapisaną przy użyciu silnego uwierzytelnienia (SCA) można obciążać wiele razy korzystając z Płatności wielokrotnych lub Subskrypcji Espago.

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

link 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 i jest ona aktywna
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
sca_payment obiekt tablica z informacjami o transakcji inicjującej recurring (czyli pierwsza lub najnowsza płatnosć z cof=storing i 3-D Secure przy użyciu tego profilu klienta). Informuje o płatności, której ID będzie przesyłane do Banku przy płatnościach cyklicznych. Przykład: "sca_payment": { "id": "pay_aaaaaaaaaaaa", "amount": "19.00", "updated_at": 1605775020, "client": "cli_xxxxxxxxxxxxxxx" }

link Tworzenie nowego profilu

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. Obowiązkowy
curl -i https://sandbox.espago.com/api/clients \
-H "Accept: application/vnd.espago.v3+json" \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD \
-d "description=Jan Kowalski" \
-d "card=token_id"
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/clients")
request = Net::HTTP::Post.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"
request.body = "description=Jan Kowalski&card=token_id"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/clients');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "description=Jan Kowalski&card=token_id");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);
{
  "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
}


Zamiast podawać token karty można podać bezpośrednio jej dane, lecz ze względów bezpieczeństwa przekazywanie ich 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).

Dane karty można podać wg następującego schematu (wszystkie pola są obowiązkowe):

Parametr Opis Komentarze
card[first_name] Imię właściciela karty
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

link 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

curl -i https://sandbox.espago.com/api/tokens \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD \
-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"
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/tokens")
request = Net::HTTP::Post.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"
request.set_form_data(
  "card[first_name]" => "Jan",
  "card[last_name]" => "Kowalski",
  "card[month]" => "02",
  "card[number]" => "4242424242424242",
  "card[verification_value]" => "123",
  "card[year]" => "2018",
)

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
// Generated by curl-to-PHP: http://incarnate.github.io/curl-to-php/
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/tokens');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "card[first_name]=Jan&card[last_name]=Kowalski&card[number]=4242424242424242&card[verification_value]=123&card[year]=2018&card[month]=02");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);
{
  "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
  }
}

Parametr used przyjmuje wartości logiczne true lub false. Jeżeli wartość wynosi false, oznacza to, że token nie został jeszcze użyty.

link Sprawdzanie informacji o tokenie

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

  • kraju wystawcy karty
  • nazwy banku
  • rodzaju karty

Sprawdzenie informacji o tokenie może trwać do kilku sekund, co może wiązać się wolniejszą odpowiedzią API.

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

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

curl -i https://sandbox.espago.com/api/tokens/cc_776Hzu24ArvnooVvq/check_type \
-X POST \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/tokens/cc_776Hzu24ArvnooVvq/check_type")
request = Net::HTTP::Post.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/tokens/cc_776Hzu24ArvnooVvq/check_type');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);
{
    "id":"cc_776Hzu24ArvnooVvq",
    "created_at":1570612905,
    "used":false,
    "card":{
        "company":"VI",
        "last4":"4242",
        "year":2021,
        "month":2,
        "first_name":"Jan",
        "last_name":"Kowalski",
        "authorized":null,
        "card_type":"D",
        "country":"HKG",
        "bank":"U",
        "created_at":1570612905
    }
}

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

link Modyfikacja profilu

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ąć

curl -i https://sandbox.espago.com/api/clients/CLIENT_ID \
-X DELETE \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/clients/CLIENT_ID")
request = Net::HTTP::Delete.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/clients/CLIENT_ID');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');

curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);

W odpowiedzi wysyłamy Status 204: no content

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 takie jak ma to miejsce przy tworzeniu klienta.


UWAGA
Jeżeli aktualizacji ulega którakolwiek z danych dotyczących karty to 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).
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.

curl -i https://sandbox.espago.com/api/clients/ID_KLIENTA \
-X PUT \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD \
-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]=2025" \
-d "card[month]=02"
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/clients/ID_KLIENTA")
request = Net::HTTP::Put.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"
request.body = "description=Jan Kowalski \
&email=client@example.com \
&card[first_name]=Jan \
&card[last_name]=Kowalski \
&card[number]=4242424242424242 \
&card[verification_value]=123 \
&card[year]=2025 \
&card[month]=02"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/clients/ID_KLIENTA');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "description=Jan Kowalski&email=client@example.com&card[first_name]=Jan&card[last_name]=Kowalski&card[number]=4242424242424242&card[verification_value]=123&card[year]=2025&card[month]=02");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');

curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);
{
  "email":"client@example.com",
  "id":"cli_772q8GcejiQfRl4z",
  "created_at":1560960175,
  "description":"Jan Kowalski",
  "card":{
    "company":"VI",
    "last4":"4242",
    "year":2025,
    "month":2,
    "first_name":"Jan",
    "last_name":"Kowalski",
    "authorized":null,
    "created_at":1561125908
  },
  "deleted":false
}

Dane klienta zostaną zaktualizowane tylko wtedy, gdy jego nowa karta nadaje się do płatności internetowych oraz cyklicznych. 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.

curl -i https://sandbox.espago.com/api/clients/CLIENT_ID/update_if_authorized \
-X PUT \
-H "Accept: application/vnd.espago.v3+json" \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD \
-d "card=TOKEN"
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/clients/CLIENT_ID/update_if_authorized")
request = Net::HTTP::Put.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"
request.set_form_data(
  "card" => "TOKEN",
)

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/clients/CLIENT_ID/update_if_authorized');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "card=TOKEN");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');

curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);
{
  "updated":true,
  "client":{
    "email":"client@example.com",
    "id":"cli_772q8GcejiQfRl4z",
    "created_at":1560960175,
    "description":"Jan Kowalski",
    "card":{
      "company":"VI",
      "last4":"4242",
      "year":2022,
      "month":2,
      "first_name":"Jan",
      "last_name":"Kowalski",
      "authorized":true,
      "authorized_cvv_cvc":true,
      "issuer_response_code":"00",
      "created_at":1561126879
    },
    "deleted":false
  }
}

link Pobieranie danych profilu

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ć

curl -i https://sandbox.espago.com/api/clients/CLIENT_ID \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/clients/CLIENT_ID")
request = Net::HTTP::Get.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/clients/CLIENT_ID');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);

{
  "email":"client@example.com",
  "id":"cli_772q8GcejiQfRl4z",
  "created_at":1560960175,
  "description":"Jan Kowalski",
  "card":{
    "company":"VI",
    "last4":"4242",
    "year":2022,
    "month":2,
    "first_name":"Jan",
    "last_name":"Kowalski",
    "authorized":true,
    "authorized_cvv_cvc":true,
    "issuer_response_code":"00",
    "created_at":1561126879
    },
  "deleted":false",
    "sca_payment": {
        "amount":0.00,
        "created_at":1561126879
        }
}

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)
curl -i https://sandbox.espago.com/api/clients \
-X GET \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD \
-d "page=2" \
-d "per=15"
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/clients")
request = Net::HTTP::Get.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"
request.set_form_data(
  "page" => "2",
  "per" => "15",
)

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/clients');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "page=2&per=15");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);
{
  "count":19,
  "clients":[
    {
      "email":"client@example.com",
      "id":"cli_772q8GcejiQfRl4z",
      "created_at":1560960175,
      "description":"Jan Kowalski",
      "card":{
        "company":"VI",
        "last4":"4242",
        "year":2022,
        "month":2,
        "first_name":"Jan",
        "last_name":"Kowalski",
        "authorized":true,
        "authorized_cvv_cvc":true,
        "issuer_response_code":"00",
        "created_at":1561126879
      },
      "deleted":false
    },
    {
      "email":"test@example.com",
      "id":"cli_772psATGSdMbS8NS",
      "created_at":1560960154,
      "description":"Jan Kowalski id:321",
      "card":{
        "company":null,
        "last4":null,
        "year":null,
        "month":null,
        "first_name":null,
        "last_name":null,
        "authorized":null,
        "created_at":null
      },
      "deleted":false
    },
    (. . .)
  ]
}

link Autoryzacja karty klienta na żądanie

Autoryzacja polega to na zarezerwowaniu i zwróceniu 1 PLN (lub 1 EUR, itp) w celu sprawdzenia czy karta obsługuje płatności internetowe.

  • Jeśli autoryzacja się powiedzie oznacza to, że karta obsługuje płatności internetowe, że jest ważna i aktualnie posiada środki na koncie.
  • Jeśli autoryzacja się nie powiedzie to znaczy, że jest prawie pewne, że kolejne obciążenia się również nie powiodą (wyjątkiem jest tu odrzucenie autoryzacji ze względu na chwilowy brak środków lub wyczerpanie limitu transakcji danego dnia, ale najczęstszym powodem odrzucenia jest nieaktywowanie płatności Internetowych/E-commerce/MOTO lub limity ustawione na 0PLN).

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

UWAGA
Jeśli autoryzacja jest pierwszą operacją wykonywaną przy pomocy danej karty/danego klienta to podczas tej autoryzacji będzie użyty kod CVV (może być użyty tylko jeden raz), wszystkie następne transakcje będą już wykonywane bez kodu CVV. Część kart może nie obsługiwać płatności bez kodu CVV (a co za tym idzie nie nadają się do płatności cyklicznych) co może powodować sytuację w której autoryzacja się powiodła, a dalsze próby obciążania już nie. Aby tego uniknąć należy zaraz po udanej autoryzacji dokonać drugiej autoryzacji lub płatności.


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

curl -i https://sandbox.espago.com/api/clients/CLIENT_ID/authorize \
-X POST \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/clients/CLIENT_ID/authorize")
request = Net::HTTP::Post.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/clients/CLIENT_ID/authorize');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);

{
  "email":"client@example.com",
  "id":"cli_772q8GcejiQfRl4z",
  "created_at":1560960175,
  "description":"Jan Kowalski",
  "card":{
    "company":"VI",
    "last4":"2239",
    "year":2025,
    "month":2,
    "first_name":"Jan",
    "last_name":"Kowalski",
    "authorized":true,
    "issuer_response_code":"00",
    "created_at":1561369769
  },
  "deleted":false
}

link Bezpieczna strona do tworzenia i aktualizacji karty klienta

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

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

Aby stworzyć “client_card_page” - bezpieczną stronę, gdzie Klient może zostać przekierowany aby bezpiecznie przekazać dane karty - należy wysłać zapytanie POST na następujący adres API:
https://sandbox.espago.com/api/clients/card_page
a następnie przekierować klienta na adres podany w odpowiedzi.

Parametry HTTP

Parametr Wymagane Opis Komentarz
client ID klienta Powiniem być podany tylko w przypadku modyfikacji istniejącego już klienta
client[description] check Opis/nazwa klienta Musi zawierać przynamniej 5 znaków
card[email] check 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 Możliwe wartości:
all (domyślnie) - 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
check Informacja jak testować kartę klienta 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
positive_url Adres URL, na który klient ma być przekierowany po zapisaniu danych karty.
negative_url Adres URL, na który klient ma być przekierowany gdy zrezygnuje lub gdy wystąpi błąd.
title Krótki opis, w jakim celu ta karta jest podawana - wyświetlony zostanie na stronie. Przynajmniej 5 znaków


Jeżeli serwis ma włączoną opcję “automatycznej autoryzacji klienta podczas jego utworzenia” to “check” jest domyślnie ustawiony jako “recurring”. W przeciwnym wypadku jako “nothing”.


curl -i https://sandbox.espago.com/api/clients/card_page \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD \
-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"
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/clients/card_page")
request = Net::HTTP::Post.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"
request.body = "client[description]=Jan Kowalski id:321&client[email]=test@example.com&check=recurring&store=recurring&title=Card for future subscription for the radio ABC"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/clients/card_page');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "client[description]=Jan Kowalski id:321&client[email]=test@example.com&check=recurring&store=recurring&title=Card for future subscription for the radio ABC");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);
{
  "id":"cpl_772AUdz2l2DMHCvz",
  "url":"https://sandbox.espago.com/client_card_page/cpl_772AUdz2l2DMHCvz",
  "client":"cli_772IYA6M52V4njJR",
  "store":"recurring",
  "check":"recurring",
  "title":"Card for future subscription for the radio ABC",
  "valid_to":1561459867,
  "created_at":1561373467,
  "used":false,
  "positive_url":null,
  "negative_url":null
}

Teraz można także używać profil klienta (cli_772IYA6M52V4njJR) tak jak normalnie.
Parametr URL zawiera url strony client_card_page dla tego klienta. Taki link jest ważny jedną 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.

link Sprawdzanie informacji o karcie

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

  • kraju wystawcy karty
  • nazwy banku
  • rodzaju karty

Sprawdzenie informacji o karcie może trwać do kilku sekund, co może wiązać się wolniejszą odpowiedzią API. Ten sam problem może wystąpić przy tworzeniu profilu klienta, gdy jest włączone automatyczne sprawdzenie informacji na temat jego karty. W celu odpytywania o informacje karty wymagany jest kontakt z Espago w celu uruchomienia tej usługi.

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

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

curl -i https://sandbox.espago.com/api/clients/cli_772IYA6M52V4njJR/check_type \
-X POST \
-H 'Accept: application/vnd.espago.v3+json' \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/clients/cli_772IYA6M52V4njJR/check_type")
request = Net::HTTP::Post.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/clients/cli_772IYA6M52V4njJR/check_type');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);
{
  "email":"test@example.com",
  "id":"cli_772IYA6M52V4njJR",
  "created_at":1561373467,
  "description":"Jan Kowalski id:321",
  "card":{
    "company":"VI",
    "last4":"4242",
    "year":2020,
    "month":2,
    "first_name":"Jan",
    "last_name":"Kowalski",
    "authorized":true,
    "authorized_cvv_cvc":true,
    "issuer_response_code":"00",
    "card_type":"D",
    "country":"HKG",
    "bank":"U",
    "created_at":1561373520
  },
  "deleted":false
}

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

vpn_key Dosyłanie CVV

link Po co dosyłać CVV

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


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

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

link Tworzenie tokenu CVV

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

1. Wywołanie IFrame

Klient wywołuje IFrame przystosowany do generowania tokenów cvv, a następnie go wypełnia i przesyła do espago

<script src="https://js.espago.com/espago-1.2.js"></script>
 <script 
   async=""
   data-id="EspagoFrameScript"
   data-key="VrYVaA1CjmRooKh63YYv"
   data-live="false"
     data-cvv-only="true"
   data-button="Pay"
   src="https://js.espago.com/iframe-1.0.js">
 </script>

 <a id="pay_btn">Zapłać</a>
$('#pay_btn').click( () => {
  showEspagoFrame()
})

Odebranie tokenu

Po wywołaniu formularza i podaniu danych karty przez płatnika, skrypt wysyła je bezpośrednio do serwera Espago. W przypadku utworzenia tokenu, skrypt domyślnie szuka na stronie z której został wywołany formularza o identyfikatorze “espago_form” i dodaje w nim pole z tokenem.

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

<form id="espago_form">
  <input type="hidden" id="cvv_token" name="cvv_token" value="cvv_xxxxxx">
</form>

Wywołanie płatności

Wywołanie płatności wraz z dodanym parametrem cvv=cvv_token_id.

curl -i https://sandbox.espago.com/api/charges \
-H "Accept: application/vnd.espago.v3+json" \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD \
-d "amount=10" \
-d "currency=pln" \
-d "client=cli_772IYA6M52V4njJR" \
-d "description=Espago docs" \
-d "cvv=cv_772oAPNIwkEZlEIPo"

link Parametry ramki

Parametr Wymagany Wartości domyślne Informacje
async done “” Nie może mieć wartości innej niż domyślna
data-id done EspagoFrameScript Nie może mieć wartości innej niż domyślna
src done adres skryptu Nie może mieć wartości innej niż domyślna
data-key done String, Klucz publiczny Merchanta
data-cvv-only done String, jeśli ma wartość ‘true’, EspagoFrame działa w trybie tokenu CVV - tylko pole CVV jest wyświetlane.
data-live 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-company String, wskazuje markę zapisanej karty, logo danej marki będzie wyświetlone obok pola CVV w sekcji informacji o zapisanej karcie. Dostępne: AX, DC, DI, JC, MC, MD, UP, VI.
data-last4 String, wskazuje ostatnie 4 cyfry z numeru zapisanej karty, będą one wyświetlone obok pola CVV w sekcji informacji o zapisanej karcie.
data-valid-to String, format: ‘MMRRRR’, wskazuje datę ważności zapisanej karty, będzie ona wyświetlone obok pola CVV w sekcji informacji o zapisanej karcie.
data-lang pl String, Język w jakim będzie wyświetlony formularz w standardzie ISO 639-1. Dostępne: da, de, en, et, fr, it, lt, lv, pl, ru, sv.
data-success function(data) {} Funkcja callback wywoływana w przypadku, gdy token zostanie wygenerowany. Uwaga, podanie funkcji callback wyłącza domyślne działanie skryptu - pole ‘cvv_token’ nie zostanie dołączone do formularza.
data - string, wygenerowany token z bramki Espago.
data-error 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 function() {} Funkcja wywoływana w przypadku, gdy użytkownik zamknie okno dialogowe (klikając “x” lub klawisz “Esc”).
data-target 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 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 Tekst wyświetlany poniżej nagłówka i nazwy sklepu (pobranej automatycznie z API Espago)
data-button Zapisz (pl) Etykieta tekstowa wyświetlona na przycisku zatwierdzania formularza.
Uwaga - domyślna wartość jest zależna od parametru języka ‘data-lang’

link Płatność przy użyciu tokenu CVV

Płatność przy użyciu tokenu CVV odbywa się w taki sam sposób, co zwykła płatność, ale posiada dodatkowy parametr cvv, zawierający id tokenu cvv.

Przykładowe zapytanie

curl -i https://sandbox.espago.com/api/charges \
-H "Accept: application/vnd.espago.v3+json" \
-u ms_771eUTliRiZ:SeCreT_P@ssw0rD \
-d "amount=10" \
-d "currency=pln" \
-d "client=cli_772IYA6M52V4njJR" \
-d "description=Espago docs" \
-d "cvv=cv_772oAPNIwkEZlEIPo"
require 'net/http'
require 'uri'

uri = URI.parse("https://sandbox.espago.com/api/charges")
request = Net::HTTP::Post.new(uri)
request.basic_auth("ms_771eUTliRiZ", "SeCreT_P@ssw0rD")
request["Accept"] = "application/vnd.espago.v3+json"
request.body = "amount=10&currency=pln&client=cli_772IYA6M52V4njJR&description=Espago docs&cvv=cv_772oAPNIwkEZlEIPo"

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.espago.com/api/charges');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "amount=10&currency=pln&client=cli_772IYA6M52V4njJR&description=Espago docs&cvv=cv_772oAPNIwkEZlEIPo");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, 'ms_771eUTliRiZ' . ':' . 'SeCreT_P@ssw0rD');

$headers = array();
$headers[] = 'Accept: application/vnd.espago.v3+json';
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);

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

<script src='https://js.espago.com/espago-1.2.js' type='text/javascript'></script>

<form action='cv_token.html' id='espago_new_cvv_form' method='POST'>
  <input id='espago_new_verification_value' type='text' value='712'>
  <span id='espago_new_verification_value_error'></span>
  <input type='submit' value='Create CVV token'>
</form>
var espago = new Espago({public_key: 'PfcMBQnqWjNF2ihkv9xs', custom: true, live: false})

$("#espago_new_cvv_form").submit(function(event){
  event.preventDefault()

  if (espago.validate_new_cvc()){
    $("#espago_new_verification_value_error").text("")
  } else {
    $("#espago_new_verification_value_error").text("Błędne dane!")
  }
  espago.create_new_cvv()
})

payment Espago Terminals

link Czym jest Espago Terminals

Espago Terminals umożliwia integrację fizycznych terminali płatniczych z systemem sprzedaży dostępnym przez przeglądarkę. Integracja polega na wysłaniu płatności na terminal przez request API i otrzymaniu przez system sprzedaży informacji o statusie transakcji. Umożliwia też realizację zwrotów inicjowanych w systemie sprzedaży.

Standardowa integracja może zostać rozszerzona o funkcjonalność, która umożliwia powiązanie ID transakcji z terminala z klientem w serwisie sprzedawcy i na tej podstawie ponowne obciążenie karty bez jej fizycznej obecności (o ile umożliwia to regulamin sprzedaży).

Wykorzystanie Espago Terminals jest spójne z API Espago (wykorzystywanym w e-commerce, e-invoicing i usługach recurringowych), ponieważ po dokonaniu płatności na terminalu i uzyskaniu od Espago Terminals profilu klienta wszelkie operacje wykonywane są w ten sam sposób w bramce Espago w oparciu o ten profil.

Do przeprowadzenia wdrożenia została przygotowana przez Espago symulacja fizycznego terminala, dzięki czemu partner integrujący nie potrzebuje dostępu do testowego fizycznego terminala jak i testowych kart płatniczych.

link Zakres stosowania Espago Terminals

Ze względu na charakter działania terminali płatniczych Espago Terminals posiada kilka ograniczeń technicznych:
1. Komputer (dalej zwany POS), z którego wysłana ma być płatność musi bezpośrednio znajdować się w tej samej sieci LAN z terminalem.
2. POS musi posiadać przeglądarkę Chrome (w wersji min. 57) lub Firefox (w wersji min. 52).
3. Przeglądarka musi mieć zainstalowane dedykowane rozszerzenie Espago Terminals.
4. Espago Terminals współpracuje tylko z niektórymi agentami rozliczeniowymi. Więcej informacji na ten temat można uzyskać pod adresem sprzedaz@espago.com.

Rozszerzenie Espago Terminals

Nasze rozszerzenie zostało stworzone w celach bezpieczeństwa transakcji, a bez niego nasze rozwiązanie nie będzie działać poprawnie. Służy ono do bezpośredniej komunikacji między naszym API, a terminalem płatniczym.

Poza instalacją rozszerzenia nie jest potrzebne żadne dodatkowe oprogranowanie czy specjalna konfiguracja. Rozszerzenie zostało stworzone w taki sposób, aby nie wymagało żadnej konfiguracji, oraz działało niezwłocznie po dodaniu do przeglądarki.

Rozszerzenie jest dostępne w dziale Do pobrania. link

link Integracja

Po uzyskaniu dostępu do konta od działu wsparcia należy się zalogować pod adresem https://terminals-beta.espago.com/users/sign_in. Po tym zaleca się zmianę hasła. Można tego dokonać w panelu zarządzania swoim kontem - znajduje się on pod przyciskiem sybolizującym “konto” w lewym dolnym rogu.

W następnym kroku należy przejść do zakładki “Services”. Tam będzie można odnaleźć swój serwis testowy.
W Espago Terminals każdy użytkownik może posiadać wiele serwisów, a do serwisów może należeć wiele terminali, jednak każdy serwis posiada oddzielny dostęp do API i nie mogą one wymieniać między sobą informacji czy współdzielić terminali.

Po wybraniu swojego serwisu należy kliknąć przycisk “Edit Service” oraz ustalić hasło dostępu do API - nie może ono być przekazywane osobom postronnym. Należy również podać back_request_url - parametr określający adres, na który zostanie wysłany back request z informacją o statusie transakcji po jej wykonaniu, jak i login i hasło basic auth mające służyć do autoryzacji back requestów.
Należy również podać domyślne wartości positive_url oraz negative_url wskazujące na adresy, na które ma zostać przekierowany POS po ukończeniu transakcji.

Ostatnim krokiem jest konfiguracja terminali. Aby tego dokonać należy z poziomu serwisu wybrać “View Terminal” dla wybranego terminala, następnie “Edit Terminal”. Nazwa może być dowolna - wygodna dla integratora. Kluczowymi parametrami podstawowej konfiguracji jest adres IP sieci LAN oraz port, na którym nasłuchiwać będzie terminal. Na etapie integracji z środowiskiem testowym te parametry nie są istotne do poprawnego przeprowadzenia płatności.

Po tej konfiguracji można zacząć wysyłać requesty do bramki Espago Terminals według instrukcji w kolejnych rozdziałach. Espago udostępnia również narzędzie do podglądania zapytań wysyłanych do bramki. Dostępne one są w zakładce Api Requests.

Wirtualny Terminal

Mając na uwadze to, iż dostęp do Espago Terminals oraz integracja może nastąpić dużo wcześniej, niż dostępny będzie fizyczny terminal stworzyliśmy wirtualny terminal testowy wbudowany w nasze rozszerzenie. Wszystkie płatności wysyłane na środowisko testowe (https://terminals-beta.espago.com) będą obsługiwane przez niego.
Po poprawnym zapytaniu o płatność i przejściu w link rozszerzenie Espago Terminals do przeglądarki uruchomi nowe okno z terminalem wirtualnym, który przedstawia kluczowe informacje dla programisty, które wysłał na terminal. Na dole okna będzie możliwość wybrania odpowiedzi wysłanej na terminal.

Po poprawnej integracji oraz przejściu kilku testów zespół Espago uruchomi środowisko produkcyjne, za pomocą którego będzie można wysyłać płatności na fizyczne terminale.

link Działanie Espago Terminals

1. Request z danymi do wykonania transakcji

Wysłanie requestu do API Espago Terminals z danymi terminala oraz informacjami o transakcji na adres terminals.espago.com/api/charges.

{
  "amount": 12.00,
  "currency": "EUR",
  "description": "Payment #5656",
  "terminal": "1234567",
  "positive_url": "https://espago.com/success",
  "negative_url": "https://espago.com/failure"
}

2. Odpowiedź z adresem do przekierowania

Po podaniu poprawnych danych Espago Terminals w odpowiedzi wyśle adres, na który powinien zostać przekierowany komputer POS, wraz z informacją o utworzonej płatności.

{
  "link": "https://terminals.espago.com/pay/tpl_7d4vh_1hgg?token=60d5f7cb576c8691c8f8be2e700bc581",
  "payment_guid": "tp_4455rgT6Ve"
}

3. Wysłanie płatności na terminal płatniczy

Po przekierowaniu dostępna będzie strona, która wywoła rozszerzenie Espago Terminals. Następnie pobierze ono dane dot. płatności, nawiąże połączenie z terminalem i prześle odpowiednie instrukcje.
W tym momencie Klient dokonuje płatności kartą na terminalu w zwykły sposób, zgodnie z instrukcją użytkowania terminala.

4. Odpowiedź ze statusem transakcji

Po zakończeniu transakcji na stronie wyświetli się status transakcji, po czym nastąpi przekierowanie do państwa serwisu. W przypadku niepowodzenia również zostanie to zaznaczone, a szczegółowe informacje dotyczące przyczyny niepowodzenia zostaną wyświetlone na terminalu. Informacje dotyczące transakcji zostaną wysłane na adres podany jako back request.

{
  "payment": {
    "id": "tp_7d7z-noWFPW",
    "description": "Payment #5656",
    "state": "success",
    "amount": "12.00",
    "currency": "EUR"
  }
}

link Parametry obciązenia

Nowa płatność na terminalu następuje w wyniku wysłania żądania typu POST na adres https://terminals.espago.com/api/charges. Tak jak w przypadku standardowego API Espago zapytanie należy autoryzować za pomocą nagłówka Authorization z wartością Basic app_id:password.

Dostępne są następujące parametry:

Parametr Opis Uwagi
terminal TID Tid terminala, na który ma zostać wysłana płatność
description Opis transakcji Musi składać się z 5 do 99 znaków. Powinien być stosowany do powiązania płatności z klientem serwisu.
amount Kwota transakcji Liczba dziesiętna, np. 123.45
currency Waluta Trzyliterowy skrót zgodny z walutą przyjmowaną przez terminal
positive_url obowiązkowy adres powrotny po pozytywnym zakończeniu transakcji
negative_url obowiązkowy adres powrotny po negatywnym zakończeniu transakcji
fetch_client Obiekt klienta Wartość true spowoduje przekazaniem obiektu klienta w back requeście

W odpowiedzi Espago Terminals prześle link do przekierowania komputera POS lub w przypadku niepoprawnego zapytania jego powód.

link Parametry back requestów

Po zakończonej płatości Espago Terminals wysyła informacje dotyczące jej statusu.
Przykładowa odpowiedź:

{
  "payment": {
    "id": "tp_7d7z-noWFPW",
    "description": "Order #55665",
    "state": "success",
    "amount": "12.99",
    "currency": "PLN"
  },
  "client": {
    "id": "cli_7d7Cm9pP61YyvOKZ",
    "card": {
      "full_name": "Myrna Cummings",
      "company": "VI",
      "last4": "0002",
      "year": "2024",
      "month": "12",
      "country_code": "pl"
    }
  }
}
Parametr Opis Uwagi
payment Dane dotyczące płatności
payment id Id płatności Nadawane przez Espago Terminals
payment description Opis płatności Nadawane przez merchanta przy tworzeniu płatności
payment state Status płatności Wartość inna niż success oznacza niepowodzenie
payment amount Kwota płatności
payment currency Waluta płatności
client Dane dotyczące klienta Zwracane tylko gdy fetch_client=true
client id Id profilu klienta w Espago
client card Dane karty przypisanej do profilu

link Status płatności

Espago Terminals zapisuje całą komunikację z terminalem oraz wszelkie potrzebne informacje o płatności, w tym jej status. Można się zapoznać z tymi informacjami w panelu na https://espago.terminals.com/manage, lecz w przypadku niejasności to informacja na ekranie terminala zawsze stanowi nadrzędne źródło informacji.

Możliwe stany płatności na terminalu:

Stan Opis
new Płatność utworzona w serwisie Espago Terminals, lecz link do niej przypisany nie został wykorystany
sent Płatność wysłana na terminal, oczekuje na zakończenie
success Płatność została wykonana, konto klienta obciążone.
rejected Płatność odrzucona.
failed Płatność zakończona niepowodzeniem ze względu na czynniki zewnętrzne.

link Płatności wielokrotne na terminalu

Wykonywanie płatności wielokrotnych w oparciu o pierwszą transakcję wykonaną na terminalu jest bardzo proste w implementacji, zwłaszcza gdy merchant posiada już integrację ze standardową bramką płatności Espago.

Aby uzyskać referencję transakcji po płatności przy jej tworzeniu poprzez request na endpoint /api/charges należy dodać parametr fetch_client i nadać mu wartość true. Wtedy gdy płatność zostanie udana w back requeście dostaniemy obiekt klienta z parametrem id.

{
  "payment": { ... },
  "client": {
    "id": "cli_7d7Cm9pP61YyvOKZ",
    "card": {
      "full_name": "Myrna Cummings",
      "company": "VI",
      "last4": "0002",
      "year": "2024",
      "month": "12",
      "country_code": "pl"
    }
  }
}

Po udanej płatności Espago Terminals tworzy profil klienta dla standardowej bramki Espago. ID oznacza ID profilu, który można podawać zamiast tokenu (client: ...) w parametrach tworzenia płatności i można go używać w taki sam sposób jak zwykły profil klienta utworzony przez zwykły request do bramki Espago.
Więcej na temat profilu klienta można przeczytać w rozdziale profil klienta.

web Espago.js

link Działanie Espago.js

UWAGA: opisane tu użycie Espago JS jest akceptowanym, ale starszym rozwiązaniem niż Espago iFrame. Dla nowych integracji zdecydowanie sugerujemy wykorzystanie rozwiązania iFrame dające więcej możliwości i będące ciągle rozwijane.

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 (lub Espag iFrame) 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. 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. 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 typu “name” - do działania skryptu wystarczy “id”. Aby uzyskać te dane można odczytać je z odpowiedzi bramki Espago przy tworzeniu profilu klienta (zapytanie /api/clients) lub płatności (zapytanie /api/charges).

1. Wypełnienie formularza

Klient wypełnia formularz swoimi danymi, a następnie klikając przycisk wywołuje akcję wytworzenia tokenu

<script src='https://js.espago.com/espago-1.2.js' type='text/javascript'></script>
<form action='/charge' id='espago_form' method='POST'>
  <input id='espago_card_number' type='text'>
  <input id='espago_first_name' type='text'>
  <input id='espago_last_name' type='text'>
  <input id='espago_month' type='text'>
  <input id='espago_year' type='text'>
  <input id='espago_verification_value' type='text'>
  <input type='submit' value='Pay'>
</form>

2. Odebranie tokenu

Funkcja `create_token()` to 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. Domyślnie funkcja espago.create_token() wykonuje akcję submit.

var espago = new Espago({public_key: 'PfcMBQnqWjNF2ihkv9xs', custom: true, live: false})

$("#espago_form").submit(function(event){
  event.preventDefault()
  if (!espago.validate_card_number()){
    alert("Błędne dane!")
  }

  if (!espago.validate_first_name()){
    alert("Błędne dane!")
  }

  if (!espago.validate_last_name()){
    alert("Błędne dane!")
  }

  if (!espago.validate_card_date()){
    alert("Błędne dane!")
  }

  if (!espago.validate_card_cvc()){
    alert("Błędne dane!")
  }

  espago.create_token()
})

3. Wywołanie płatności

Wywołanie zwykłej płatności z tokenem - czytaj więcej na temat płatności

link Parametry konstruktora 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:'});

Parametry

Parametr Obowiązkowy Wartości domyślne Znaczenie
public_key done Klucz publiczny Merchanta
live true Parametr, który wskazuje gdzie będą wysyłane dane do utworzenia tokenu.
Parametr ‘true’ oznacza wysyłanie danych na środowisko produkcyjne, parametr ‘false’ na środowisko testowe.
form #espago_form Nazwa formularza
card_number #espago_card_number ID Pola z numerem karty klienta
first_name #espago_first_name ID pola z imieniem właściciela karty
last_name #espago_last_name ID Pola z nazwiskie, właściciela karty
month #espago_month ID pola z miesiącem ważności karty
year #espago_year ID pola z rokiem ważności karty
cvc #espago_verification_value ID pola z numerem weryfikacyjnym karty
custom false Wartość ‘true’ pozwala na zdefiniowanie własnych parametrów success i error.
success function(data) {} Funkcja callback. Akcje w niej zawarte wykonują się w przypadku otrzymania pozytywnej odpowiedzi zwrotnej.
error function(data) {} Funkcja callback. Akcje w niej zawarte wykonują się w przypadku wystąpienia błędu podczas komunikacji z serwerem.
submit true Zatwierdzenie formularza i wysłanie danych.

link Tworzenie tokenu

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()

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: (data) => { 
    alert("success")
  },
  error: (data) => { 
    alert("error");
  }
})

link Pola formularza

Domyślne ID pola Typ pola Znaczenie
espago_card_number text Numer karty klienta
espago_first_name text Imię klienta
espago_last_name text Nazwisko klienta
espago_month text Miesiąc wygaśnięcia karty
espago_year text Rok wygaśnięcia karty
espago_verification_value text Kod potwierdzenia

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

compare_arrows Kompatybilność

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

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


Niektóre starsze systemy, biblioteki lub przeglądarki nie wspierają takich połączeń; powinny one zostać zaktualizowane lub zastąpione nowszymi rozwiązaniami - ten wymóg dotyczy wszystkich połączeń do API, przekierowania 3D-Secure klientów oraz dostępu do panelu WWW.

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

System/ aplikacja/ biblioteka Minimalna kompatybilna wersja Uwagi
Windows 7 i nowsze Uwaga: W starszych systemach należy użyć alternatywnych, aktualnych przeglądarek (np. Chrome, Firefox, Opera)
Windows Server 2008 R2 i nowsze Windows 2008 R2 wymaga włączenia obsługi TLSv1.2 w rejestrach systemu oraz włączenia obsługi dodatkowych szyfrów
Android 4.4.4 i nowsze 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 i nowsze 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

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

Protokół Dostępne zestawy szyfrów
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

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

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

Jeżeli Państwa aplikacje nie może nawiązać połączenia SSL/TLS z bramką Espago, to w celu potwierdzenia/wykluczenia problemów z protokołami SSL/TLS została utworzona dodatkowa domena https://oldssl-sandbox.espago.com dająca dostęp do tego samego serwera Sandbox). oldssl-sandbox.espago.com spełnia starsze wymagania (akceptuje również TLSv1.0), umożliwia testowanie płatności pomimo nie spełniania nowych wymogów dotyczących SSL. Ten adres powinien służyć tylko do sprawdzenia łączności, w przypadku zupełnej niemożliwości połączenia się aplikacji przez API do sandbox.espago.com (tzn. podejrzenia że problem dotyczy zestawienia połączenia SSL/TLS). Jeżeli Państwa aplikacji łączy się z oldssl-sandbox, a nie łączy się z sandbox, oznacza to prawdopodobnie że Państwa oprogramowanie nie obsługuje protokołu TLSv1.2 i wymaga aktualizacji/wymiany.

sandbox.espago.com spełnia aktualne wymagania SSL/TLS, identyczne lub nawet bardziej restrykcyjne niż bramka produkcyjna. Jeśli Państwa aplikacja łączy się z bramką https://sandbox.espago.com to znaczy że spełnia najnowsze wymagania i będzie z powodzeniem łączyć się z bramką produkcyjną po wprowadzeniu wszystkich zmian. W razie wątpliwości skontaktuj się z Działem Wsparcia Espago (Support), jesteśmy w stanie określić jakich protokołów aktualnie używa Państwa aplikacja w komunikacji z Espago. W tym celu podaj źródłowy adres IP oraz ID aplikacji (ms_xxxxxxxx).

link Migracja z APIv2

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

  1. 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.
  2. 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)
  3. 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.
  4. Informacje zwrotne (tzw. back requests) z bramki Espago są wysyłane po każdym obciążeniu, w APIv2.0 były wysyłane tylko przy płatnosciach cyklicznych (więcej).
    • 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 - 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.

link 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. Ma to również 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.

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.

Witamy na Espago docs!

W ramach naszej witryny stosujemy pliki cookies w celu świadczenia Państwu usług na najwyższym poziomie. Jeśli nie wyrażasz zgody, ustawienia dotyczące plików cookies możesz zmienić w swojej przeglądarce.

Zespół Espago