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

Dane dostępowe

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

Przykład przekierowania

W najprostszym przypadku można przedstawić prostu formularz HTML ze stosownymi informacjami, który wysyłamy z użyciem POST. Nie ma potrzeby wymagać danych od klienta, większość informacji można przygotować samemu, a więc większość pól może zostać ukryta. Oto jak mogłoby to wyglądać:

1
2
3
4
5
6
7
8
9
10
11
12
13
<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="en">
    <input type="hidden" name="hash" value="6926ed14d1ae4d8eb2350d3c15e6a420e3bb7052" />

    <button type="submit">Zapłać z PayLane</button>
</form>

Obliczanie hash

Wartość hash jest liczona w następujący sposób:

1
2
hash = SHA1(salt + "|" + description + "|" + amount + "|"
       + currency + "|" + transaction_type)
Przykład:
1
2
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.

Pole POST Wymagane Format Opis
merchant_id Tak string (32) 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 Tak string(2-20) Tylko znaki alfanumeryczne. 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 Tak string(10000) Dozwolone podstawowe tagi HTML. Krótki opis produktu/usługi/transakcji.
Pojawi się w polu opisu na formularzu płatniczym.
amount Tak decimal(12,2) Używaj kropki (.) jako separatora dziesiętnego. Całkowita kwota do pobrania.
currency Tak string(3) 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 Tak string(1) 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 Tak string(500) Adres strony, na którą klient zostanie przekierowany po dokonaniu płatności, np. http://mojsklep.pl/zaplacone/.
hash Tak string(40) Security hash.
language Tak string(2) 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.
customer_name Nie string(50) Imię i nazwisko klienta.
customer_email Nie string(80) Adres e-mail klienta.
customer_address Nie string(46) Adres klienta.
customer_zip Nie string(9) Kod pocztowy klienta (jeśli dotyczy).
customer_city Nie string(40) Miasto.
customer_state Nie string(40) Stan/województwo (jeśli dotyczy).
customer_country Nie string(2) Kod kraju klienta ISO 3166, np. PL lub GB.

Odpowiedź

Kiedy klient płaci (zatwierdza Secure Form), zostaje przekierowany na Twoją stronę (adres podany w polu back_url). W trakcie przekierowania przekazywany jest zestaw parametrów (z użyciem POST lub GET, wedle Twoich preferencji).

Pole POST Typ danych 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:

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