PayLane.js

Przebieg płatności z użyciem PayLane REST.js:

  1. Kod HTML jest przesyłany do przeglądarki; strona jest wyświetlana.
  2. Klient PayLane.js zostaje zainicjowany i czeka na zatwierdzenie formularza płatności.
  3. Gdy formularz zostaje zatwierdzony, klient PayLane.js wysyła informacje o karcie do serwerów PayLane. W odpowiedzi generowany jest tymczasowy token dla karty (64-bajtowy heksadecymalny łańcuch znaków), który wstawiany jest do formularza płatności w formie ukrytego pola.
  4. Proces wysyłania formularza płatności jest wznawiany, a serwery sprzedawcy otrzymują token wraz z pozostałymi informacjami z formularza (z wyłaczaniem wrażliwych danych karty).
  5. Sprzedawca może wywołać metodę sale/authorization/checkCar/checkCard3DSecure używając wygenerowanego tokenu (musi to nastąpić w ciągu 15 minut od wygenerowania tokenu; po upływie tego czasu traci on ważność).

Inicjalizacja:

Oto prosty przykład typowego formularza płatności:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<form id="checkout-form" action="" type="">
    <!-- merchant's input elements, as many as required -->
    <input type="text" name="first-name" value="">
    <input type="text" name="last-name" value="">
    <input type="text" name="email" value="">
    <input type="text" name="address" value="">

    <!-- card related input elements: -->
    <input type="text" value="" data-paylane="cc-number">
    <input type="text" value="" data-paylane="cc-expiry-month">
    <input type="text" value="" data-paylane="cc-expiry-year">
    <input type="text" value="" data-paylane="cc-cvv">
    <input type="text" value="" data-paylane="cc-name-on-card">

    <input type="submit" value="submit">
</form>

Rzeczywisty kod formularza można dowolnie zmieniać według własnych potrzeb, należy jednak spełniać przy tym poniższe wymagania:

  1. Pola dotyczące danych kart muszą mieć ustawione stosowne atrybuty data-paylane.
  2. Pola dotyczące danych kart nie mogą mieć atrybutów name. To wymóg bezpieczeństwa, który zapobiega wysłaniu danych kart do serwerów sprzedawcy.
  3. Formularz płatniczy musi miec nadany unikalny atrybut id. Klient PayLane.js będzie się posługiwał tą wartością.

W następnej kolejności zainicjalizuj klienta PayLane.js:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<script src="path/to/paylane.js"></script>
<script>
    try
    {
        var client = new PayLaneClient({
            publicApiKey : 'PUBLIC_API_KEY',
            paymentForm  : 'checkout-form',
        });
    }
    catch (e)
    {
        console.log(e); // exceptions are fatal
    }
</script>

Klient PayLane.js wymaga podania jedynie publicznego klucza API oraz wskazania na formularz płatniczy.

  • klucz API jest 40-znakowym łańcuchem znaków, który można znaleźć w Merchant Panelu PayLane (Menu => Konto => Ustawienia konta merchanckiego => API)
  • na formularz płatniczy można wskazać przekazując jako argument jedną z poniższych wartości:
    1. atrybut id formularza
    2. węzeł drzewa DOM, który reprezentuje formularz (np. osiągalny przez document.forms[i])
    3. obiekt jQuery zawierający jedynie formularz płatniczy

Poniższe wartości mogą być opcjonalnie przekazane do klienta PayLane.js (jeśli nie zostaną zdefiniowane, zostaną użyte wartości):

  1. cardNumberInputName (domyślnie: cc-number) – alternatywna wartość data-paylane odnosząca się do pola numeru karty
  2. cardExpiryMonthInputName (domyślnie: cc-expiry-month) – alternatywna wartość data-paylane odnosząca się do pola miesiąca ważności karty
  3. cardExpiryYearInputName (domyślnie: cc-expiry-year) – alternatywna wartość data-paylane odnosząca się do pola roku ważności karty
  4. cardSecurityvarInputName (domyślnie: cc-cvv) – alternatywna wartość data-paylane odnosząca się do pola kodu CVV2/CVC2
  5. cardHolderInputName (domyślnie: cc-name-on-card) – alternatywna wartość data-paylane odnosząca się do pola z imieniem i nazwiskiem posiadacza karty
  6. errorTypeInputName (domyślnie: paylane_error_type) – alternatywna wartość name odnosząca się do pola typu błędu
  7. errorCodeInputName (domyślnie: paylane_error_code) – alternatywna wartość name odnosząca się do pola kodu błędu
  8. errorDescriptionInputName (domyślnie: paylane_error_description) – alternatywna wartość name odnosząca się do pola opisu błędu
  9. tokenInputId (domyślnie: paylane-token) – alternatywna wartość id odnosząca się do pola tokenu
  10. tokenInputName (domyślnie: paylane_token) – alternatywna wartość name odnosząca się do pola tokenu
  11. errorHandler (domyślnie: pusta funkcja) – an funkcja obsługi błędu,przyjmuje trzy argumenty: type, code, description
  12. callbackHandler (domyślnie: pusta funkcja) – opcjonalna funkcja obsługująca zatwierdzenie formularza. Zostanie ona wywołana w momencie, gdy zakończy się wykonywanie żądania AJAX z tokenem. Token pojawi się w formularzu jako ukryte pole i zostanie przekazany do funkcji jako jedyny argument. Jeśli funkcja nie zostanie określona, zatwierdzenie formularza będzie miało standardowy przebieg.
    1
    2
    3
    4
    5
    6
    7
    /**
    Custom token callback handler.

    @param {string} token Temporary credit card token
    @return {void}
    */
    callbackHandler: function(token){}

Obsługa błędów:

PayLane.js może wywoływać wyjątki i błędy.

Wyjątki moga powstać jedynie podczas inicjalizacji klienta, np. gdy wymagany formularz lub jego pola nie zostaną znalezione lub został podany pusty klucz publiczny. Takie wyjątki muszą być obsłużone standardowo z użyciem try/catch, aczkolwiek nie powinny wystepować, jeśli tylko formularz został prawidłowo przygotowany.

Z kolei błędy mogą występować niespodziewanie z różnych przyczyn, takich jak przerwy w połączeniu sieciowym, źle sformatowane dane (np. token czy numer karty) itp. Klient PayLane.js umożliwia obsługe błędów na dwa sposoby: z użyciem funkcji obsługi błędów (przekazywanej do konstruktora jako errorHandler) i jako ukryte pola formularza (które można obsłużyć po stronie serwera).

1. Funkcja obsługi błedów:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
/**
 * Custom error handler which allows the merchant to
 * handle errors raised by the PayLaneClient class,
 * such as connection errors or erroneous API responses.
 *
 * @param  {int}    type          Error type from PayLaneClient.errorTypes
 * @param  {int}    [code]        Error code from the API response
 * @param  {string} [description] Error description from the API response
 * @return {void}
 */

function errorHandler(type, code, description)
{
    console.log(type, code, description);
}

2. Ukryte pola formularza:


Poniższe ukryte pola zostaną dodane do formularza płatniczego (należy pamietać ich, że ich nazwy mogą zostać nadpisane podczas przekazywania parametrów error* do konstruktora):

  • paylane_error_type: typ błędu; 1, jeśli to błąd połączenia, 2, jeśli to błąd zwrócony przez API REST.js PayLane
  • paylane_error_code: występuje tylko w przypadku błędów API (kod zwracany przez API REST.js)
  • paylane_error_description: występuje tylko w przypadku błędów API (opis zwracany przez API REST.js)