Powiadomienia o transakcjach

Mechanizm powiadomień

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.

Dla kont testowych, powiadomienia wysyłane są tylko raz.

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
contentarrayNotification content (array of notification data arrays).
content_sizeintegerSize of the content array – number of notifications in package.
communication_idstring(30)Unique string identifying the notifications package.
tokenstring(50)Optional. Static string sent only if configured for merchant account.

Struktura tablicy content

Tablica content zawiera tablice reprezentujące poszczególne notyfikacje.   Przykładowe dane POST (w postaci tablicy PHP):

Opis pół tablicy

Nazwa Typ Opis
typestring(6)Transaction type. You can find the full list on the Transaction types page.
idinteger(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_saleinteger(10)PayLane sale ID number. If notification is about other transaction type than sale, this id points to related sale transaction.
datestring(10)Transaction date, YYYY-MM-DD format.
amountdecimal(12,2)Transaction amount (depending on the case: sale amount, refund amount etc.).
currency_codestring(3)Transaction currency code.
textstring(200) UTF-8 encodedOptional. Transaction description. Accordingly, it may be sale description, refund reason, chargeback reason etc.

Przykład zapytania

Przykładowe dane POST (w postaci tablicy PHP)
Przykładowe dane
PHP
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 
)

Przykładowy klient i 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
Próbka kodu
PHP
$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']);

Typy transakcji

Tabela typów

Typ Opis systemowy
SASale authorization. Only for card transactions in auth+capture model. Capture is indicated with “S” type notification. Associated with Sale Authorization ID in PayLane system.
SSale. Either card or Direct Debit. Associated with Sale ID in PayLane system.
RRefund. Multiple refunds for single sale may be performed. Associated with Refund ID in PayLane system.
RVReversal. Direct Debit transactions-specific. Sale was reversed e.g. because funds were not available on charged account.
RRORetrieval Request Open. Card transactions-specific. Request from bank for additional documents (sale proof). Unanswered retrieval requests in most cases result in chargeback being issued by the bank.
RRARetrieval Request Answer. Indicates that answer for retrieval request was sent (either using Merchant Panel or through PayLane Support).
RRCRetrieval Request Closed. End of retrieval request procedure.
CB1OChargeback 1 Open. Card transaction-specific. First chargeback was issued. Associated with Chargeback ID in PayLane system.
CB1RRChargeback 1 Reject Request. Indicates that request for chargeback rejection was sent. Requests may be sent using Merchant Panel or through PayLane Support (must be accompanied with sale proof documents).
CB1RFChargeback 1 Reject Fulfilled. Sent documents were accepted by the bank and chargeback was successfully rejected.
CB1RRCChargeback 1 Reject Request Cancellation. Chargeback rejection (CB1RF) was issued due to technical error and is cancelled.
CB1RChargeback 1 Reversal. Chargeback (CB1O) was issued due to technical error and is reversed.
CB1CChargeback 1 Closed. Chargeback procedure is closed (chargeback expires). Closed chargebacks cannot be contested.
CB2OChargeback 2 Open. Second chargeback. May be issued only if first chargeback procedure is closed and first chargeback was successfully rejected. Procedure is similar to first chargeback. Associated with Chargeback ID in PayLane system.
CB2RRChargeback 2 Reject Request. See CB1RR.
CB2RFChargeback 2 Reject Fulfilled. See CB1RF.
CB2RRCChargeback 2 Reject Request Cancellation. See CB1RRC.
CB2RChargeback 2 Reversal. See CB1R.
CB2CChargeback 2 Closed. See CB1C. Closing second chargeback ends whole chargeback procedure.
CADCompliance Arbitration Debit. Arbitration resulted in money returned to client. Treated similarly to chargeback in PayLane system and associated with Chargeback ID.
CACCompliance Arbitration Credit. Issued after CAD. Arbitration resulted in money returned to merchant. Treated similarly to successful chargeback rejection in PayLane system.
PAOPre-Arbitration or Pre-Compliance Open. Marks request for an arbitration which takes place before credit card company arbitral court. Such disputes can be initiated by merchant request in some especially difficult cases.
PAAPre-Arbitration or Pre-Compliance Answer. Answer to previously made request for arbitration.
PACPre-Arbitration or Pre-Compliance Closed. End of Pre-Arbitration or Pre-Compliance phase.
AOArbitration Open. Announces start of arbitration before credit card company court. Only if request for arbitration was accepted.
EOREnd of Ruling. Closing of arbitral court hearing.
ODObjection Declined. Sent after RRA, CB1RR or CB2RR. Indicates that sent documents (for Retrieval Request or Chargeback Rejection) were not accepted. For retrieval request it usually means that chargeback will be issued, for chargebacks it means that chargeback stands.
CCancellation. Notification from credit card issuer to merchant that no debit entries from the credit card in question will be accepted in the future.