home Wstęp

link Wypróbuj

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

W pierwszym kroku zostaje utworzony iFrame, który ma za zadanie przesłać dane karty do bramki Espago, następnie pobrać go i umieścić w formularzu.
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.
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 zostaje wysłane właściwe zapytanie do bramki Espago. Składa się ono m..in. z użytkownika, kwoty i waluty, a pole card przechowuje token.
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=[SPECIAL_TEXT]" \
 -d "description=Espago docs"
Spodziewana odpowiedź od bramki Espago w formacie json. Kluczowymi inormacjami 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 główne możliwości integracji z bramką płatnosci Espago:

Umieszczenie iFrame na stronie sprzedawcy


Umieszczenie skryptu z iFrame (do podania danych karty) lub formularza przy wykorzystaniu skryptu Espago JS, realizacja wszystkich operacji związanych z płatnościami 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, następnie odebranie informacji z bramki Espago informacji i przyjecie klienta przekierowanego z powrotem do 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 zupełnie nie ma potrzeby integracji z bramką Espago, sprzedawca musi zintegrować sklep jedynie z modułem Przelewy24.

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

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

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 kart płatniczych należy używać wymienionych niżej testowych numerów kart. Zabronione jest używanie rzeczywistych numerów kart.

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



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

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



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

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 w celu dodatkowej autoryzacji poprzez np kod przysłany SMS'em lub zalogowanie się na stronę banku.

Obsługiwanie kart posiadających zabezpieczenie 3D Secure jest niezbędne do poprawnego obsługiwania płatności. Na prośbę Sprzedawcy dział wsparcia Espago może wyłaczyć zabezpieczenie 3D Secure (domyślnie włączone), jednak jest to niezalecane.


Obciążenie klienta posiadającego zabezpieczenie 3D Secure zwraca posiada status new oraz posiada 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.

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] Środki są zarezerwowane (blokada) na koncie klienta ale nie są jeszcze pobrane.
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 dodatkowe doprecyzowanie przyczyny odrzucenia i nie jest konieczne jego sprawdzanie (użyteczniejszą informacją jest kod “issuer_response_code”).

Komunikat Znaczenie Przyczyna Uwagi
declined transakcja odrzucona Nieaktywowany rodzaj usługi (MOTO, ecommerce), również brak środków
card expired karta utraciła ważność Przekroczony termin ważności karty
invalid amount niewłaściwa kwota Ma to związek z limitem kwotowym/liczby płatności
invalid card nieprawidłowa karta
invalid profile nieprawidłowe konto MID Odrzucenie przez Elavon, np. ze względu na niekatywny MID Komunikat występuje wraz z kodem issuer_response_code=00
referral A / pick up card karta do zatrzymania Karta oznaczona jako zablokowana/zagubiona/skradziona. UWAGA: Nie należy powtarzać obciążeń dla tej karty! Może to zostać uznane za próbę oszustwa!
referral B transakcja wymaga potwierdzenia wymaga kontaktu z bankiem dla potwierdzenia transakcji, transakcja jest od traktowana jako odrzucona w systemie Espago
serv not allowed nieobsługiwany typ karty Merchant nie obsługuje danego typu karty np. American Express, Diners Club, w przypadku braku rejestracji BRAM także MasterCard
3ds_not_authorized odrzucenie podczas 3D-Secure Nieprawidłowe poświadczenie 3D-Secure lub inny błąd związany z 3D-Secure.

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

Kod błędu Znaczenie Proponowany komunikat
00 Zaakceptowane obciążenie Transakcja zaakceptowana. Dziękujemy!
00 Blokada odpowiedzi na poziomie Elavon (sugerowany kontakt z Espago/Elavon) ODMOWA - wystąpił błąd. Transakcja została odrzucona ze względu na brak odpowiedzi z banku, blokadę konta Sprzedawcy, użycie nieobsługiwanego typu karty lub nieprawidłowe dane kary. Prosimy spróbować ponownie później lub skontaktować się z Działem Wsparcia Technicznego Espago.
01,02 Wymagana autoryzacja głosowa ODMOWA - problem z autoryzacją. Niezbędny kontakt z bankiem.
03 Nieprawidłowe/niepełne dane akceptanta ODMOWA - problem z autoryzacją. Podano nieprawidłowe dane karty. Spróbuj ponownie.
04,07 Karta zastrzeżona (z powodów innych niż kradzież/zgubienie) ODMOWA - karta zastrzeżona. Skontaktuj się z Twoim bankiem w celu wyjaśnienia przyczyny problemu. UWAGA: Nie należy powtarzać obciążeń dla tej karty! Może to zostać uznane za próbę oszustwa!
05 Płatności typu MOTO/eCommerce/subskrypcyjne nieaktywne lub niewspierane ODMOWA – bank odrzucił transakcję ze względu na ustawienia zabezpieczeń (np. karta nie obsługuje płatności cyklicznych/bez kodu CVV) albo blokadę środków lub karta nie obsługuje płatności internetowych/MOTO. Sprawdź ustawienia karty lub użyj innej karty.
13,61 Nieaktywowane płatności typu MOTO/eCommerce lub przekroczenie limitu ODMOWA – Sprawdź, czy dla Twojej karty dostępna jest usługa płatności internetowych lub MOTO, zweryfikuj ustawienia limitów dla takich transakcji lub skontaktuj się z Twoim bankiem (wystawcą karty) w celu wyjaśnienia przyczyny odmowy.
12 Nieprawidłowa transakcja ODMOWA - transakcja niedostępna dla tej karty. Skontaktuj się z Twoim bankiem w celu wyjaśnienia przyczyny problemu
14 Nieprawidłowy numer karty ODMOWA - podano nieprawidłowy numer karty. Sprawdź dane, czy karta jest wciąż aktywna czy przeterminowana i spróbuj ponownie.
30 Błędny format danych wiadomości autoryzacyjnej ODMOWA - skontaktuj się z Twoim bankiem w celu wyjaśnienia przyczyny problemu
41 Karta oznaczona jako zgubiona ODMOWA - karta oznaczona jako zgubiona – skontaktuj się z Twoim bankiem w celu wyjaśnienia przyczyny problemu. UWAGA: Nie należy powtarzać obciążeń dla tej karty! Może to zostać uznane za próbę oszustwa!
43 Karta oznaczona jako skradziona ODMOWA - karta oznaczona jako skradziona – skontaktuj się z Twoim bankiem w celu wyjaśnienia przyczyny problemu. UWAGA: Nie należy powtarzać obciążeń dla tej karty! Może to zostać uznane za próbę oszustwa!
51 Niewystarczające środki na koncie ODMOWA - niewystarczające środki na koncie. Zweryfikuj stan swojego konta i spróbuj ponownie.
54 Przeterminowana karta ODMOWA - karta utraciła ważność. Skontaktuj się z bankiem celem wyjaśnienia przyczyny lub użyj innej karty.
57 Typ transakcji niedozwolony dla karty ODMOWA – bank odrzucił transakcję ponieważ użyta karta nie może zostać użyta to tego typu transakcji (internetowe, MOTO lub cykliczne). Sprawdź ustawienia karty lub użyj innej karty.
59 Podejrzenie oszustwa ODMOWA - skontaktuj się z Twoim bankiem w celu wyjaśnienia przyczyny problemu
62 Ograniczenie karty, wykluczenie ze względu na kraj wydawcy. ODMOWA – użycie karty zostało ograniczone, np. ze względu na ograniczenie (embargo) nałożone na kraj wydawcy (banku). Skontaktuj się z bankiem w celu wyjaśnienia szczegółowej przyczyny problemu.
65 Przekroczony limit liczby użyć ODMOWA – przekroczony dzienny limit liczby transakcji dla tej karty. Dokonaj zmiany ustawień dziennych limitów lub spróbuj ponownie później.
75 Przekroczony limit błędnych prób podania CVV/CVC/PIN. ODMOWA – przekroczony limit błędnych prób podania kodu CVV/CVC/PIN. Zweryfikuj poprawność kodu zabezpieczającego na swojej karcie.
78 Nowa, nieaktywowana karta ODMOWA – Karta nie została aktywowana. Aktywuj kartę i spróbuj ponownie.
82, N7 Nieprawidłowy kod CVV ODMOWA – Nieprawidłowy kod CVV. Sprawdź poprawność wprowadzonych danych i spróbuj ponownie. UWAGA: Nie należy powtarzać obciążeń dla tej karty! Może to zostać uznane za próbę oszustwa!
91,92,94,98 Spróbuj Ponownie ODMOWA – Tymczasowy błąd po stronie banku, spróbuj ponownie.
E3 Błędna weryfikacja 3D-Secure: błąd banku. ODMOWA – Błąd banku. Spróbuj ponownie, lub skonsultuj się z bankiem lub sprzedawcą.
E4 Niepoprawna weryfikacja 3D-Secure w banku. ODMOWA – Bank zwrócił informacje o nieudaniej autoryzacji klienta.
E5 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 Możliwe scenariusze płatności wielokrotnych

Głównym celem płatności wielokrotnych jest zapisanie w bramce Espago danych karty klienta (w obiekcie Profil Klienta) i użycie ich do płatności cyklicznych (np. subskrypcje) lub płatności na żądanie klienta (np. szybsze płatności zapisanych klientów w sklepie). Realizowanie cyklicznych obciążeń kart klientów możliwe jest na kilka sposobów, wśród których należy rozróżnić dwa podstawowe scenariusze:

Płatności wielokrotne realizowane po stronie merchanta Płatności wielokrotne 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 realizowane po stronie Merchanta. Więcej informacji na temat subskrypcji Espago można znaleźć tutaj.

link Działanie płatności wielokrotnych

  1. Sprzedawca wywołuje płatność z parametrem cof=storing, (co tworzy w bramce Espago profil klienta z danymi karty), w odpowiedzi otrzymuje m.in. ID klienta i potwierdzenie wykonania płatności lub adres do przekierowania (SCA: 3D-Secure).
  2. Opcnonalnie, warto zaraz po utworzeniu profilu wywołać autoryzację profilu klienta, w celu sprawdzenia czy karta obsługuje płatnosci cykliczne (patrz: Problem kart nie nadających się do płatności cyklicznych).
  3. Później w wybranych przez siebie momentach Sprzedawca wywołuje żądanie płatności (zapytanie na /api/charges z podaniem m.in. ID klienta) dodając informację, że jest to płatność cykliczna (parametr cof=recurring).

Parametr cof=recurring jest potrzebny do poprawnego oznaczenia płatnościach cyklicznych/recurringowych (w nich nie jest potrzebny kod CVV/CVC, nie ma również przekierowania 3D-Secure) (Więcej na temat tworzenia profilu klienta można przeczytać w rozdziale profil klienta). Parametr cof=recurring został wprowadzony przez Visę i MasterCard w 2019r, i zastąpił wcześniejszy recurring=true.

UWAGA: Gdy ten scenariusz jest wykorzystywany jako oneclick payment/wielokrotne płatności na żądanie Klienta, to w żądaniach płatności (/api/charges) należy pominąć parametr cof=recurring, dzięki temu możliwe będzie przekierowanie klienta w ramach 3D-Secure. Warto tu również użyć dosyłania CVV gdyż zwiększa to bezpieczeństwo i szanse na powodzenie obciążenia w niektórych bankach.

link Zasady i dobre praktyki płatności cyklicznych

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

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.



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



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



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


Krok Działanie Opis
1 Utworzenie klienta Sprzedawca tworzy w bramce Espago profil klienta (z danymi karty).
2 Autoryzacja klienta Autoryzacja na żądanie lub automatyczna autoryzacja podczas tworzenia klienta (można ją włączyć w panelu WWW).
POWODZENIE: karta obsługuje płatności internetowe, można przejść do kroku 3.
NIEPOWODZENIE: karta nie obsługuje płatności internetowych, więc na pewno nie uda się kolejna próba obciążenia1,3
3 Utworzenie subskrypcji

Obciążenie klienta w ramach pierwszej opłaty

Druga autoryzacja
Utworzenie subskrypcji (z automatyczną pierwszą płatnością) lub pierwsze żądanie obciążenia klienta (w przypadku cykliczności realizowanej po stronie Sprzedawcy) lub drugie przeprowadzenie autoryzacji (w przypadku gdy Sprzedawca chce tylko sprawdzić działanie karty, bez jej obciążania).
POWODZENIE: karta obsługuje płatności internetowe i cykliczne. Kolejne obciążenia najprawdopodobniej się powiodą2.
NIEPOWODZENIE:
karta nie obsługuje płatności cyklicznych, więc na pewno nie powiodą się kolejna próby obciąż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

Wartość parametru cof jest typem string.

Płatność inicjująca

storing - zapisuje dane karty i zwracamy profil klienta, który może być użyty dla przyszłych płatności

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

instalment - płatności ratalne za wykonaną usługę, zgodnie z umową zawartą z posiadaczem karty;
recurring - płatności cykliczne o stałym interwale mniejszym niż rok, w okresie świadczenia usługi świadczonej 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;

Płatności inicjowane przez sprzedawcę - 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
}

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 tablica Parametry dotyczące użytej karty.
issuer_response_code Kod odpowiedzi z banku. Jeśli jest przekierowanie wynikające z 3D-Secure to ten parametr przyjmuje wartość 00 lub NULL do czasu dokonania płatności.
transaction_id ID transakcji. Przydatne do wyszukiwania płatności w panelu udostępnianym przez Elavon, gdyż tylko to ID jest widoczne w raportach Elavon (nie ma tam ID klienta ani ID płatności). Transakcja jest to “operacja”. Domyślnie jedna płatność ma jedną transakcję (tj. wykonanie płatności), po zwróceniu części lub całości płatności zostaje przypisane tu ID transakcji zwracającej płatność.
redirect_url opcjonalny Adres URL do przekierowania klienta jeśli obsługa 3D-Secure jest włączona oraz jeśli karta klienta obsługuje 3D-Secure.
reversable opcjonalny Parametr “reversable=true” informuje o możliwości zwrotu płatności przed rozliczeniem. Po rozliczeniu parametr przyjmuje wartość “false” i przestaje być widoczny we właściwościach płatności.
tds_redirect_form opcjonalny/ tablica Parametry umożliwiające przekierowanie klienta bezpośrednio do banku (zamiast do Espago przy użyciu redirect_url). W tym przypadku należy przekierować klienta formularzem na adres “action”, metodą POST przekazując parametry PaReq, MD i TermUrl. W większości imlementacji ta opcja nie jest polecana, przed użyciem prosimy o kontakt z Espago.

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

W obiekcie klienta, można przechowywać jego dane, ze szczególnym uwzględnieniem danych karty. Klienta utworzonego z pełnymi danymi karty, można obciążać wiele razy.

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

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

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

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

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.

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

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