Transaction Notifications

Transaction Notifications is a service that simplifies automatic communication between your systems and PayLane.

The idea behind it is this: you or your customers may initiate many payment operations (sales, refunds etc.), but there are cases, when you simply need to check their statuses (i.e. whether a payment was cleared).
There is also a number of operations that are performed without your input (i.e. chargebacks or reversals).

Thanks to Transaction Notifications you don’t have to control and check transactions manually in the Merchant Panel or wait for email notifications from PayLane.

Using Transaction Notifications

In order to have Transaction Notifications enabled or disabled for specific accounts, please contact our support.

Schedules

Notifications are sent in packages of no more than 100 transactions. Packages are created and sent either instantly or in 5-minute intervals (this depends on the payment method). If a package is not sent successfully, the system will try to send it again every 5 minutes and after an hour – every hour.

If a package fails to be received by your system during a specified period of time (two days), additional information will be sent to PayLane Support. Your staff will be queried about the problem with receiving notifications and helped in resolving it if necessary.

For test accounts, notifications are sent only once.

Implementation

Notifications are sent using HTTP POST.

In order to receive notifications, you need to write a script that will be able to receive POST data and return a response with specific content. The script must be accessible by one of the following protocols:

  • HTTP,
  • HTTPS.

Requests

Request structure
Name Type Description
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.

The content array contains arrays that represent specific notifications.

content structure
Name Type Description
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_code 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.

Example POST data (represented as PHP array):

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
)

Response

The script is expected to respond with a HTTP response 200 (OK). Response content should contain only communication_id of received notifications package. Anything else or empty page will be interpreted as failure.

Example client

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']);