Secure Form

Wprowadzenie do Secure Form

Secure Form to gotowe i łatwe w implementacji rozwiązanie płatnicze, dzięki któremu możesz przyjmować płatności z PayLane. Wystarczy, że przekierujesz klienta na formularz płatniczy, który od nas dostaniesz. Nie musisz także przechodzić żadnych audytów/skanów PCI ani nawet mieć certyfikatu SSL (choć posiadanie go jest oczywiście zalecane). Wszystko to dlatego, że płatność odbywa się z całości po naszej stronie, tj. w domenie PayLane.

Z punktu widzenia klientów, dokonywanie płatności może wyglądać następująco:  

  1. Po wybraniu produktów/usług na stornie sprzedawcy, klient wyraża chęć, by zapłacić za zakupy.
  2. Klient zostaje przekierowany na stronę PayLane, na której znajduje się Secure Form; wprowadza tam dane niezbędne do dokonania płatności.
  3. Po wysłaniu formularza, klient zostaje przekierowany z powrotem na stronę sprzedawcy, gdzie dowiaduje się o statusie transakcji/płatności.

Co czeka programistę?

Musisz tylko przekazać informacje (z użyciem POST) dotyczące transakcji (takie jak nazwa produktu, cena itp.) do naszego Secure Form. Po wysłaniu formularza, klient zostanie przekierowany z powrotem na Twoją stronę, do której przesłane zostaną też informacje zwrotne. Do Ciebie należy już wybór, czy zostaną przesłane z użyciem POST czy GET. Możesz wykorzystać te dane, by poinformować klienta o statusie transakcji.

Podsumowując, cały proces może być przedstawiony z poniższych krokach:

  1. Klient, będąc na stronie sprzedawcy, chce zapłacić za wybrane produkty/usługi.
  2. Strona sprzedawcy wysyła informacje o transakcji do formularza płatniczego PayLane oraz przekierowuje tam klienta.
  3. Po wypełnieniu formularza, PayLane wykorzystuje podane informacje, by przetworzyć płatność (komunikuje się z centrami rozliczeniowymi, bankami, organizacjami kartowymi itp.).
  4. Wymienione instytucje (ich lista zależna jest od danej metody płatności) odpowiadają PayLane, pozwalając na przetworzenie płatności.
  5. PayLane zwraca informacje o statusie płatności do strony sprzedawcy.
  6. Sprzedawca może wykorzystać otrzymane informacje, by powiadomić klienta, czy transakcja się udała i jaki jest jej status.

Realizacja

Secure Form to gotowy formularz płatniczy przygotowany przez PayLane. Jeśli nie chcesz integrować się z naszymi systemami przez API, Secure Form jest rozwiązaniem dla Ciebie.

Wystarczy, że przekierujesz klienta na przygotowany przez PayLane formularz płatniczy. Klient bezpiecznie dokona tam płatności i powróci na Twoją stronę.

Przykład
HTML
<form action="https://secure.paylane.com/order/cart.html" method="post">
    <input type="hidden" name="amount" value="19.99">
    <input type="hidden" name="currency" value="EUR">
    <input type="hidden" name="merchant_id" value="john_test">
    <input type="hidden" name="description" value="TR001" />
    <input type="hidden" name="transaction_description" value="Product 1 transaction" />
    <input type="hidden" name="transaction_type" value="S">
    <input type="hidden" name="back_url" value="http://johns-shop.com/purchased">
    <input type="hidden" name="language" value="pl">
    <input type="hidden" name="hash" value="6926ed14d1ae4d8eb2350d3c15e6a420e3bb7052" />
    <button type="submit">Zapłać z PayLane</button>
</form>

Dane dostępowe do Secure Form

Żeby uzyskać dane dostępowe do Secure Form, po prostu zaloguj się do Merchant Panelu, wybierz kolejno Administracja -> Integracja -> Podstawowe -> Integracja Secure Form. Znajdziesz tam swoje merchant_id oraz hash salt – dzięki tym informacjom możesz poprawnie przekierować klientów na Secure Form przez POST.

Obliczanie hash

Wartość hash jest liczona w następujący sposób:
hash = SHA1(salt + "|" + description + "|" + amount + "|"
       + currency + "|" + transaction_type)

Przykład:

hash = SHA1("MySalt|TR001|19.99|EUR|S") 
= "6926ed14d1ae4d8eb2350d3c15e6a420e3bb7052"

Możesz ustawić wartość salt w Merchant Panelu. Nigdy nie należy przesyłać wartości salt ani liczyć wartości hash po stronie klienta. Powinno to się odbywać zawsze po stronie serwera.

Wartości zapytania

Poniżej znajdziesz pełna listę parametrów, które mogą (lub muszą) być wysłane w zapytaniu POST.
*Pola customer_* nie są wymagane, jednak ich użycie jest mocno zalecane, ponieważ w przypadku nie wysłania ich, użytkownik będzie proszony o uzupełnienie tych danych na Secure Formie PayLane.

Struktura zapytania

Pole
Format
Wymagane
Opis
merchant_id
string (32)
tak
Twój Numer ID umożliwiający dostęp do Secure Form. Możesz znaleźć ten numer w Merchant Panelu (account => secure form customization => options)
description
string(2-20) Tylko znaki alfanumeryczne
tak
Identyfikator transakcji, który zostanie przekazany do systemu PayLane. Będzie później widoczny w Merchant Panelu jako opis danej transakcji. Dozwolone są jedynie znaki alfanumeryczne.
transaction_description
string(2-10000)
tak
Krótki opis produktu/usługi/transakcji. Pojawi się w polu opisu na formularzu płatniczym.
amount
decimal(12,2) Używaj kropki (.) jako separatora dziesiętnego.
tak
Całkowita kwota do pobrania.
currency
string(3)
tak
Kod waluty ISO 4217; kwota określona w wartości amount będzie pobrana w tej walucie (na przykład “PLN” lub “EUR”).
transaction_type
string(1)
tak
Typ transakcji; są dwie możliwe wartości: S – sale (sprzedaż), A – authorization only (tylko autoryzacja). W przypadku płatności kartami, wybierz preferowaną wartość; w przypadku innych metod płatności, wybierz S
back_url
string(500)
tak
Adres strony, na którą klient zostanie przekierowany po dokonaniu płatności, np. http://mojsklep.pl/zaplacone
hash
string(40)
tak
Security hash.
language
string(2)
nie
Kod języka ISO 639. Obecnie Secure Form może być wyświetlony w następujących językach:
en – angielski,
pl – polski,
de – niemiecki,
es – hiszpański,
fr – francuski,
nl – holenderski,
it – włoski.
Jeżeli to pole nie zostanie wysłane, formularz wybierze język na podstawie języka przeglądarki lub wyświetli się w wersji angielskiej.
customer_name
string(50)
nie
Imię i nazwisko klienta (zalecane*).
customer_email
string(80)
nie
Adres e-mail klienta (zalecane*).
customer_address
string(46)
nie
Adres klienta (zalecane*).
customer_zip
string(9)
nie
Kod pocztowy klienta (jeśli dotyczy).
customer_city
string(40)
nie
Miasto (zalecane*).
customer_state
string(40)
nie
Stan/województwo (jeśli dotyczy).
customer_country
string(2)
nie
Kod kraju klienta ISO 3166, np. PL lub GB (zalecane*).

Odpowiedź

Kiedy klient zapłaci (dokona płatności w Secure Formie), zostanie przekierowany z powrotem na Twoją stronę (na adres podany w polu back_url). W trakcie przekierowania przekazywany jest zestaw parametrów za pomocą metody POST lub GET (metoda ustawiana w Merchant Panelu).

Struktura odpowiedzi

Pole
Format
Opis
status
string
Status transakcji:
  • PENDING – płatność oczekuje na realizację;
  • PERFORMED – płatność została pomyślnie zrealizowana;
  • CLEARED – środki zostały pobrane (otrzymano potwierdzenie z banku);
  • ERROR – płatność nie powiodła się.
description
string(20)
Identyfikator transakcji – ten sam, który był wysłany w żądaniu.
amount
decimal(12,2)
Kwota transakcji.
currency
string(3)
Kod waluty transakcji w standardzie ISO 4217, np. PLN, GBP, EUR.
hash
string(40)
Security hash.
id_authorization
integer(10)
Numer ID autoryzacji transakcji w systemie PayLane. Pusty, jeśli:
  • typ transakcji to S (sale),
  • wystąpił błąd.
id_sale
integer(10)
Numer ID transakcji w systemie PayLane. Pusty, jeśli:
  • typ transakcji to A (authorization),
  • wystąpił błąd.
id_error
integer(10)
Numer ID błędu w systemie PayLane. Pusty, jeśli błąd nie wystąpił.
error_code
integer(3)
Kod błędu.
error_text
string(500)
Krótki opis błędu.
fraud_score
decimal(4,2)
Wynik oceny ryzyka. 0.00 – niskie ryzyko, 10.00 – wysokie ryzyko. Puste, jeśli ocena ryzyka nie została przeprowadzona.
avs_result
string(2)
Wynik sprawdzania AVS. Puste, jeśli sprawdzenie AVS nie zostało przeprowadzone.

Liczenie wartości hash z odpowiedzi

PayLane wykorzystuje tę samą wartość salt do wygenerowania innej wartości hash wysyłanej w odpowiedzi. Jest ona liczona w następujący sposób:
hash = SHA1(salt + "|" + status + "|" + description + "|"
        + amount + "|" + currency + "|" + id)
Wartość id to, w zależności od otrzymanej odpowiedzi, albo id_sale, albo id_authorization. Jeśli zostanie zwrócony błąd, wartość id powinna być pustym łańcuchem znaków.

Wystarczy, że porównasz otrzymaną w odpowiedzi wartość hash z obliczoną przez siebie, by poznać status transakcji.