Dziennik zmian Espago

• Zmiany w konfiguracji SSL bramki:
  • SANDBOX/test: usunięcie zestawu szyfrów DH i DHE w TLSv1.2, dodanie nowych.
  • PRODUKCJA: usunięcie szyfrów wykorzystujących CBC. Aktualna konfiguracja SSL w bramce produkcyjnej jest taka, jaka była w bramce SANDBOX przez ostatnie 2 lata.
  • Szyfry w TLSv1.3 bez zmian.
• INFORMACJA: Szyfry DH/DHE zostaną usunięte z bramki produkcyjnej po I kwartale 2024.

• Dodanie rozdziału opisującego integracje z Szybkimi Przelewami.

• Udostępnienie nowych wersji skryptów iFrame 2.0 (https://js.espago.com/iframe-2.0.js) oraz JS 1.3 (https://js.espago.com/espago-1.3.js), z polepszonym wyglądem, akceptacją 2 cyfrowego roku.
• Dodanie ścieżki https://js.espago.com/iframe.js dla skryptu iFrame, wskazującej zawsze na najnowszą wersję Espago iFrame (wcześniej iframe-1.0.js, aktualnie iframe-2.0.js).
• Dodanie rozdziału opisującego integracje z płatnościami BLIK.

• Dodanie rodziału opisującego integracje z portfelem Google Pay

• Wprowadzenie podziału kodów odpowiedzi płatności kartowych na kategorie.

• Zaprzestanie wspierania weryfikacji 3D-Secure v1 przez Visę i MasterCard, pozostawienie wersji EMVCo 3D Secure v2. Z punktu widzenia Sprzedawcy flow płatności się nie zmienia.
• Zmiana zachowania testowych kart w bramce “Sandbox” - każda karta przy płatności jednorazowej oraz z cof=storing wymaga uwierzytelnienia 3DSecure (również karta 4242 4242 4242 4242).

• W odpowiedzi na zapytanie API zawierające nieprawidową treść (np. brakującą wartość parametru obowiążkowego lub zły format) w obiekcie errors został dodany parametr code, który zawiera koleno: nazwę pola i wynik walidacji.
• Wyłączenie API v2.

• zmiana zachowania Subskrypcji Espago - przy nieudanej próbie obciążenia karty w ramach Subksrypcji Espago, po otrzymaniu odpowiedzi issuer_response_code z komunikatem z kategorii “nie ponawiaj”, subskrypcja zostaje zatrzymana. Aby uruchomić nową subskrypcję dla danego Profilu Klienta, należy zaktualizować ten profil zmieniając kartę na nową oraz dokonać silnego uwierzytelnienia. Alternatywnie, można utworzyć nowy zupełnie Profil Klienta, dokonać silnego uwierzytelnienia i uruchomić nową subskrypcję.

• W zapytaniu obciążającym kartę (/api/charges): wycofanie parametru skip_3ds ze względu na niezgodność z regulacjami PSD2

• Wyłączenie Aktualizacji danych karty klienta tylko gdy karta jest zautoryzowana, gdyż metoda ta nie spełnia wymogów PSD2.
• Wyłączenie Automatycznej autoryzacji klienta przy utworzeniu, gdyż metoda ta nie spełnia wymogów PSD2.

• Uzupełnienie dokumentacji i pliku SQL o kody odrzuceń 1A i 65 (związane z brakiem SCA/3D-Secure), oraz kody B## (odrzucanie Espago płatności, o których wiadomo, że nie będą mogły się powieść)

• Wyłączenie akceptacji protokołu TLSv1.1 w bramce produkcyjnej Espago (aktualnie wspierane: TLSv1.2 oraz TLSv1.3)

• Stopniowe włącznie 3-D Secure w wersji 2 (EMV 3-D Secure) dla kolejnych serwisów. Dla serwisów posiadających włączone 3DSv1.0.2 nie ma potrzeby wprowadzania zmian w integracji, różni się tylko ścieżka URL, na którą jest przekierowany klient.

• Rozpoczęcie używania statustu płatności state=tds_redirected, oznaczającego przekierowanie klienta na uwierzytelnienie 3-D Secure (zarówno v2 jak i v1). Wcześniej taki status miała w tym czasie tylko transakcja przypisana do płatności.

• Dodanie parametru sca_payment do właściwości profilu klienta. Jeśli jest pusty, nie jest zwracany, pojawia się i jest aktualizowany gdy został użyty parametr cof=storing przy płatności inicjującej, płatności z użyciem profilu klienta lub aktualizacji profilu klienta.

• Dodanie płatności na kwotę “0” PLN/EUR/itp, służącej do uwierzytelnienia klienta z SCA i zapisania danych karty, bez konieczności obciążania go kosztami (lub wycofywania tej płatności). Funkcja (kwota 0) dostępna dla płatności realizowanych pezez acquirera Elavon.

• Udostępnienie nowego kanału płatności kartowych poprzez operatora SIX/SaferPay (w zależności od umowy: channel=six_cc ).

Aktualizacja kodów odrzuceń issuer_response_code dotyczących 3D-Secure:

E3 oznacza błąd banku przy 3D-Secure.
E4 (nowy) oznacza odrzucenie przez bank autoryzacji 3D-Secure klienta.
E5 (nowy) oznacza resztę błędów związanych z zabezpieczeniem 3D-Secure.

Utworzenie nowej dokumentacji pod adresem https://start.espago.com
Stara dokumentacja (https://developers.espago.com) pozostaje dostepna.

Dodanie do płatności parametru Card on file (cof = storing, recurring, instalment, unscheduled i inne), oznaczającego różne płatności związane z subskrypcjami i płatnościami wielokrotnymi:
* Parametr “cof=storing” dodany do płatności z 3D-Secure umożliwia zapisanie profilu klienta po tej płatności (nie potrzeba osobnego zapytania tworzącego profil klienta).
* Dla zachowania kompatybilności wstecz, od sierpnia 2019r domyślnie wszystkie płatności z parametrem “recurring=true” mają w Espago ustawiany automatycznie “cof=recurring” (Sprzedawca może nadpisać ten parametr podając w zapytaniu inną wartość parametru cof).

Zmiana wytycznych związanych z zabezpieczeniem 3D-Secure (zmiany związane z PSD2 i przygotowaniem do 3D-Secure v2.0.0)

• każda płatność pojedyncza powinna być realizowana z zabezpieczeniem 3D-Secure
• każda subskrypcja powinna zostać rozpoczęta lub poprzedzona płatnością z 3D-Secure
• każda płatność przy użyciu profilu klienta (w ramach subskrypcji, one-click, na żądanie sprzedawcy) powinna być oznaczona odpowiednim parametrem COF (card on file).

Uwaga dotycząca siłowni i integratorów obsługujących siłownie:

• sprawdzenie 3D-Secure przed uruchomieniem cyklicznych opłat wymaga zmiany sposobu zapisywania karty gdy klient zapisuje się w lokalu siłowni. Potwierdzenie 3D-Secure może wymagać od niektórych posiadaczy kart np. PKO zalogowania się do banku (i podania SMS'a), stąd sugerowanym rozwiązaniem jest aby ten element był wykonywany na urządzeniu klienta.
• Proponowanym rozwiązaniem jest przesłanie klientowi (np. mailem, lub wyświetlenie w recepcji jako QR-kod) linku, pod którym klient dokończy dodwanie karty i przejdzie weryfikację 3DS.
• W przypadku klientów rejestrujących się (lub aktualizujących dane karty) przez stronę internetową powyższy problem nie występuje, klient po prostu powinien być przekierowany na proces 3D-Secure w przeglądarce.

Wprowadzenie 22 maja 2019r. w środowisku produkcyjnym (secure) zmian dotyczących długości parametrów ID. Zmiany dotyczą tylko nowo tworzonych obiektów.

• Zmiana początkowych znaków w parametrze ID transakcji z “tn_” na “tr_”. Długość ID transakcji pozostanie 12 znaków (tr_xxxxxxxxx).
• Zwiększenie długości z 18 do 20 znaków wszystkich (poza ID transakcji) nowych parametrów ID:
• ID płatności (pay_xxxxxxxxxxxxxxxx)
• ID klientów (cli_xxxxxxxxxxxxxxxx)
• ID tokenów i tokenów CVV
• ID planów i subskrypcji
• ID invoice i invoce item (faktury - elementy subskrypcji)
• Zwiększenie z 12 do 14 długość parametrów ID nowych serwisów.

Wprowadzenie w środowisku testowym (sandbox) zmian, które wejdą na serwer produkcyjny od 22 maja 2019r (opisane w sekcji “Maj 2019”). Zmiany dotyczą tylko nowo tworzonych obiektów.

Dodanie kodu issuer_response_code 15 (wydawca karty nie odnaleziony/testowa karta) dla języka PL i EN w pliku SQL w dziale Do pobrania.

• Dodanie dwuetapowego uwierzytelnienia w panelu Sprzedawcy.
• Dodanie wysyłania informacji zwrotnych (back_request) przy zwrocie płatności.

• Wdrożenie obsługi zabezpieczenia AMEX Safekey (3D-Secure na kartach American Express), co umożliwia w pełni akceptację kart AMEX.

• Dodanie do panelu www opcji zwrotu płatności.

• Dodanie do płatności możliwości:
  1.ustawienia języka per transakcja (parametr locale),
  2.wskazania adresu email do wysłania powiadomienia (parametr email),
  3.wymuszenia niewysyłania powiadomienia mailowego nawet jeśli profil klienta posiada adres (parametr skip_email

• Wprowadzenie możliwości przyjmowania płatności kartami China Union Pay (UP/CUP).

• Wyłączenie akceptacji protokołu TLSv1.0 w bramce produkcyjnej Espago.

• Dodanie strony Espago do aktualizacji profili klienta.

• Aktualizacja listy kodów odrzuceń. Dodanie kodów: R0, R1, 68, liczne poprawki w opisach kodów w języku PL, EN oraz FR. Nowy format pliku SQL z listą komunikatów.

• Dodanie rozwiązania Espago iFrame - nowy, ulepszony względem Espago JS sposób tworzenia tokenów/przyjmowania płatności od klienta na stronie Sprzedawcy.

• Dodanie opcji pominięcia funkcji 3D-Secure.
• Dodanie Espago iFrame.

• Dodanie opcji aktualizacji klienta tylko w przypadku pomyślnej autoryzacji karty.

• Dodanie możliwości uzyskania przez API informacji o kraju i nazwie banku wydającego kartę klienta.
• Liczne usprawnienia panelu WWW.
• Zmiany w stopce w powiadomieniach mailowych do klientów: dodanie linka do FAQ oraz danych do kontaktu ze sprzedawcą (dane można uzupełnić przez panel WWW).

• Dodanie rozdzielników pól “|”, w sposobie wyliczania sumy kontrolnej. Aktualizacja dotyczy MasterPass oraz Strony Płatności. Stary sposób wyliczania sumy kontrolnej bedzie funkcjonował do I kwartału 2017.

• Wydanie wersji 1.2 skryptu Espago JS: https://js.espago.com/espago-1.2.js Użycie nowego skryptu (w miejsce dotychczasowego 1.1) - nie wymaga dodatkowych zmian na stronie Sprzedawcy. Nowy skrypt zawiera kilka usprawnień, a także wnosi obsługę tworzenia tokenów CVV.

• Dodanie parametru payment_id (ID płatnosci w postaci pay_xxxxxxxx) do informacji zwrotnej (back request) wysyłanej z bramki Espago do serwisu sprzedawcy podczas obciążeń w ramach subskrypcji.
• Dodanie nowych statusów płatności dla odrzuceń i błędów związanych z weryfikacją klienta w ramach 3D-Secure. Parametr reject_reason “3ds_not_authorized”, parametr issuer_response_code “E3”.
• Drobne poprawki komentarzy do kodów odrzuceń12 i 62.

• Dodanie możliwości uruchomienia subskrypcji z opóźnionym startem.

• Dodanie ochrony przed przesłaniem znaków specjalnych tzw. “eskejpowanie”) we wszystkich opisowych parametrach (description, first_name, last_name, itp.) zgodnie z zaleceniami OWASP.

• Dodanie możliwości ustawienia URL przekierowania dla danej płatności - parametru positive_url i negative_url.

• Dodanie możliwości przekierowania na stronę płatności umieszczoną w bramce Espago.
• Aktualizacja opisów kodów odrzuceń “issuer_response_code”: 00, 05, 57 w dokumentacji oraz plikach sql/xml
• Dodanie nowych statusów płatności: “tds_redirected” oraz “resigned”.

Zmiany w wymaganiach SSL/HTTPS bramki

Podniesienie wymagań dla połączeń do bramki testowej https://sandbox.espago.com: ograniczenie akceptowalnych połączeń do TLSv1.2 i TLSv1.1 (wykluczenie TLSv1.0) oraz zwiększenie wymagań dla użytych szyfrów SSL (ssl_ciphers, wykreślenie części szyfrów używających CBC).

Konfiguracja HTTPS dostępna aktualnie w środowisku testowym będzie sukcesywnie wprowadzana w bramce produkcyjnej począwszy od lutego 2016r.

• Dodanie możliwości wielokrotnych, częściowych zwrotów (refund).
• Dodanie możliwości dosyłania kodu CVV do płatności wielokrotnych/na żądanie.

• Dalsza rozbudowa funkcji związanych z płatnościami Espago w module Przelewy24.

• Uruchomienie obsługi DCC (Dynamic Currency Conversion).
• Zmiany możliwych statusów płatności w APIv3.0, dodanie: dcc_decision, tds_status.
• Dodanie w dokumentacji opisu nowych kodów “issuer_response_code”: 91, 92, 95, 98.
• Zmiany w konfiguracji SSL/HTTPS, wyłączenie akceptacji szyfrów uznawanych za zbyt słabe.
• Aktualne ustawienia SSL w środowisku produkcyjnym są takie jakie były w środowisku testowym przez ostatnie kilka miesięcy. W środowisku testowym zabezpieczenia SSL zostały podniesione do poziomu, który zostanie wprowadzony w bramce produkcyjnej w ostatnim kwartale 2015.
• Jednocześnie informujemy, że w drugim kwartale 2016r. bramki zaprzestaną akceptacji połączeń SSL z protokołem TLS1 (akceptowane zostaną TLS1.1 oraz TLS1.2)

• Uruchomienie obsługi MasterPass.

• Dodanie w dokumentacji opisu nowych kodów “issuer_response_code”: 62 oraz 75.

• Wydanie nowego API v3.0. Dotychczasowa wersja APIv2.0 pozostaje w użyciu, jednak większość nowych funkcjonalności (opisywanych powyżej) będzie dotyczyć tylko APIv3.0.
• Rozpoczęcie obsługi 3D-Secure.

• Wydanie nowej wersji dokumentacji Espago API i przeniesienie jej na nową domenę.

• Wyłączenie obsługi SSLv3 dla połączeń przychodzących (API) oraz wychodzących (informacjie zwrotne wysyłane przy subskrypcjach).