Powiadomienia o transakcjach

Powiadomienia o transakcjach to mechanizm ułatwiający automatyczną komunikację między Twoimi systemami i PayLane.

Zarówno Ty, jak i Twoi klienci możecie inicjować wiele różnych operacji płatniczych (płatności, zwroty środków itd.), ale są przypadki, gdy chcesz po prostu sprawdzić ich statusy (np. czy płatność się powiodła, czy środki zostały ściągnięte).
Są również operacje płatnicze, które odbywają się bez Twojego udziału, a o których z pewnością chciałbyś wiedzieć (np. chargebacki czy reversale).

Dzięki powiadomieniom o transakcjach nie musisz ręcznie kontrolować i sprawdzać transakcji w Merchant Panelu ani czekać na powiadomienia mailowe od PayLane.

Używanie powiadomień o transakcjach

Aby włączyć lub wyłączyć powiadomienia o transakcjach dla określonych kont, skontaktuj się z naszym supportem.

Harmonogramy

Notyfikacje są wysyłane w pakietach obejmujących maksymalnie 100 transakcji. Takie paczki są tworzone i wysyłane na bieżąco lub w odstępach 5-minutowych (zależy to od metody płatności). Jeśli pakiet nie zostanie wysłany pomyślnie za pierwszym razem, system będzie próbował wysłać go ponownie co 5 minut przez pierwszą godzinę, a później co godzinę.

Jeśli pakiet notyfikacji nie zostanie odebrany przez Twój system przez określony czas (2 dni), stosowna informacja o tym zostanie wysłana do supportu PayLane. Dzięki temu powiadomimy Cię o tym i pomożemy rozwiązać ewentualne problemy.

Wdrożenie

Notyfikacje są wysyłane z użyciem HTTP POST.

Aby odbierać notyfikacje od PayLane, musisz napisać skrypt, który pozwoli Ci odbierać dane POST i zwrócić odpowiedź z określoną zawartością. Skrypt musi być dostępny z wykorzystaniem jednego z następujących protokołów:

  • HTTP,
  • HTTPS.

Zapytania

Struktura zapytania
Nazwa Typ Opis
content array Notification content (array of notification data arrays).
content_size integer Size of the content array – number of notifications in package.
communication_id string(30) Unique string identifying the notifications package.
token string(50) Optional. Static string sent only if configured for merchant account.

Tablica content zawiera tablice reprezentujące poszczególne notyfikacje.

Struktura tablicy content
Nazwa Typ Opis
type string(6) Transaction type. You can find the full list on the Transaction types page.
id integer(10) Optional. Filled only if notification is about other transaction type than sale (see type field). Accordingly, id field may represent id_refund, id_chargeback etc.
id_sale integer(10) PayLane sale ID number. If notification is about other transaction type than sale, this id points to related sale transaction.
date string(10) Transaction date, YYYY-MM-DD format.
amount decimal(12,2) Transaction amount (depending on the case: sale amount, refund amount etc.).
currency string(3) Transaction currency code.
text string(200) UTF-8 encoded Optional. Transaction description. Accordingly, it may be sale description, refund reason, chargeback reason etc.

Przykłądowe dane POST (w postaci tablicy PHP):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
Array
(
    [content] => Array
        (
            [0] => Array
                (
                    [type]          => S
                    [id_sale]       => 123
                    [date]          => 2012-05-29
                    [amount]        => 12.34
                    [currency_code] => EUR
                    [text]          => Product #1
                )
            [1] => Array
                (
                    [type]          => R
                    [id_sale]       => 123
                    [id]            => 99
                    [date]          => 2012-05-30
                    [amount]        => 12.34
                    [currency_code] => EUR
                    [text]          => Money back guarantee
                )
        )
    [content_size]     => 2
    [communication_id] => 2012-05-30 10:41:36 0002 00933
    [token]            => token
)

Odpowiedź

Skrypt powinien dawać odpowiedź HTTP o kodzie 200 (OK). W odpowiedzi powinna się znaleźć tylko wartość communication_id otrzymanego pakietu notyfikacji. Cokolwiek innego lub pusta strona zostanie zinterpretowane jako błąd.

Przykładowy klient

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
$user = "user";
$password = "password";

// check HTTP Basic authentication data
if (!isset($_SERVER['PHP_AUTH_USER']) || !isset($_SERVER['PHP_AUTH_PW'])
    || $user != $_SERVER['PHP_AUTH_USER'] || $password != $_SERVER['PHP_AUTH_PW']) {

    // authentication failed
    header("WWW-Authenticate: Basic realm=\"Secure Area\"");
    header("HTTP/1.0 401 Unauthorized");
    exit();
}

// check communication
if (empty($_POST['communication_id'])) {
    die('Empty communication id');
}

// check if token correct
if ('YOUR_TOKEN' !== $_POST['token']) {
    die('Wrong token');
}

foreach ($_POST['content'] as $notification) {
    if ($notification['type'] === 'S') { // sale created
        // transaction completed, do something useful with id_sale
        $id_sale = $notification['id_sale'];
    }
}

// return communication_id
die($_POST['communication_id']);