Notyfikacje

Notyfikacje inaczej webhooks to mechanizm, który umożliwia aplikacjom otrzymywanie powiadomień o określonych zdarzeniach w czasie rzeczywistym. W kontekście Tpay API, webhooki są wykorzystywane do informowania Twojego serwera o różnych wydarzeniach związanych z transakcjami, zwrotami lub tokenizacją kart.

Bezpieczeństwo

Wszystkie powiadomienia POST są podpisane podpisem JWS.

Korzystamy z RFC 7515: JSON Web Signature (JWS).

Podpis jest dostępny w nagłówku X-JWS-Signature, który jest jednym z nagłówków HTTP dołączanych do powiadomień.

Treść powiadomienia powinna być weryfikowana na podstawie publicznie dostępnych certyfikatów:

• Certyfikat podpisu: https://secure.tpay.com/x509/notifications-jws.pem
• Certyfikat root Tpay CA: https://secure.tpay.com/x509/tpay-jws-root.pem

Dzięki temu możesz upewnić się, że powiadomienie pochodzi z zaufanego źródła i że jego treść nie została zmieniona podczas transmisji.

Ze względów bezpieczeństwa weryfikacja podpisu JWS jest obowiązkowa.

Przykład implementacji walidacji JWS:

<?php
// Get Request X-JWS-Signature header
$jws = isset($_SERVER["HTTP_X_JWS_SIGNATURE"])
    ? $_SERVER["HTTP_X_JWS_SIGNATURE"]
    : null;
if (null === $jws) {
    exit("FALSE - Missing JSW header");
}
// Extract JWS header properties
$jwsData = explode(".", $jws);
$headers = isset($jwsData[0]) ? $jwsData[0] : null;
$signature = isset($jwsData[2]) ? $jwsData[2] : null;
if (null === $headers || null === $signature) {
    exit("FALSE - Invalid JWS header");
}
// Decode received headers json string from base64_url_safe
$headersJson = base64_decode(strtr($headers, "-_", "+/"));
// Get x5u header from headers json
$headersData = json_decode($headersJson, true);
$x5u = isset($headersData["x5u"]) ? $headersData["x5u"] : null;
if (null === $x5u) {
    exit("FALSE - Missing x5u header");
}
// Check certificate url
$prefix = "https://secure.tpay.com";
if (substr($x5u, 0, strlen($prefix)) !== $prefix) {
    exit("FALSE - Wrong x5u url");
}
// Get JWS sign certificate from x5u uri
$certificate = file_get_contents($x5u);
// Verify JWS sign certificate with Tpay CA certificate
// Get Tpay CA certificate to verify JWS sign certificate. CA certificate be cached locally.
$trusted = file_get_contents("https://secure.tpay.com/x509/tpay-jws-root.pem");
// in php7.4+ with ext-openssl you can use openssl_x509_verify
if (1 !== openssl_x509_verify($certificate, $trusted)) {
    exit("FALSE - Signing certificate is not signed by Tpay CA certificate");
}
// or using phpseclib
$x509 = new \phpseclib3\File\X509();
$x509->loadX509($certificate);
$x509->loadCA($trusted);
if (!$x509->validateSignature()) {
    exit("FALSE - Signing certificate is not signed by Tpay CA certificate");
}
// Get request body
$body = file_get_contents("php://input");
// Encode body to base46_url_safe
$payload = str_replace("=", "", strtr(base64_encode($body), "+/", "-_"));
// Decode received signature from base64_url_safe
$decodedSignature = base64_decode(strtr($signature, "-_", "+/"));
// Verify RFC 7515: JSON Web Signature (JWS) with ext-openssl
// Get public key from certificate
$publicKey = openssl_pkey_get_public($certificate);
if (
    1 !==
    openssl_verify(
        $headers . "." . $payload,
        $decodedSignature,
        $publicKey,
        OPENSSL_ALGO_SHA256
    )
) {
    exit("FALSE - Invalid JWS signature");
}
// or using phpseclib
$publicKey = $x509
    ->getPublicKey()
    ->withHash("sha256")
    ->withPadding(\phpseclib3\Crypt\RSA::SIGNATURE_PKCS1);
if (!$publicKey->verify($headers . "." . $payload, $decodedSignature)) {
    exit("FALSE - Invalid JWS signature");
}
// JWS signature verified successfully.
// Process request data and send valid response to notification service.
$transactionData = $_POST;
echo "TRUE";

Pamiętaj, że jest to tylko podstawowy przykład, który ma pomóc Ci zrozumieć proces weryfikacji podpisu JWS i powinien być dostosowany do Twoich wymagań. Istnieje wiele zewnętrznych bibliotek do weryfikacji tokenów JWS. Listę tych bibliotek w różnych językach można znaleźć na stronie https://jwt.io/libraries.

Idempotentna obsługa powiadomień

Twój system musi być przygotowany na sytuację, w której jedno powiadomienie zostanie wysłane więcej niż jeden raz. Ponowne przesłanie powiadomienia nie może skutkować ponowną realizacją usługi, wydaniem towarów ani żadnymi innymi operacjami o charakterze nieodwracalnym. Każde powiadomienie dla danej transakcji będzie zawsze zawierać ten sam identyfikator, co pozwala na bezpieczną weryfikację i zapobieganie zdublowanym operacjom.

Wymagania i ograniczenia systemu powiadomień

System powiadomień nie obsługuje przekierowań 302 i 301.

Oznacza to, że nie jest możliwe przekierowywanie powiadomień wysyłanych z wynikowego URL na inny adres. Jeśli system sprzedawcy jest skonfigurowany, aby na przykład przekierowywać z HTTP na HTTPS, należy wpisać docelowy adres, który będzie odbierał powiadomienia po wszystkich przekierowaniach.

Poprawność odbierania powiadomień można zweryfikować za pomocą narzędzia do testowania powiadomień.

Serwery Tpay.com są wyposażone w zaporę sieciową, która blokuje ruch na innych portach niż standardowe porty www (tj. 80, 8080, 443).

Obecnie obsługiwanym protokołem przez Tpay jest protokół TLS 1.2, który zapewnia poufność i integralność transmisji danych oraz uwierzytelnianie serwera. Serwery używające starszych protokołów, takich jak SSLv3, mogą powodować błąd w odbieraniu powiadomień.

Automatyczne ponowne wysyłanie powiadomień

Mechanizm powiadomień, gdy nie otrzyma poprawnej odpowiedzi, będzie próbował wysłać powiadomienia zgodnie z harmonogramem powiadomień.

Po trzeciej niepoprawnej odpowiedzi z Twojego systemu, na adres e-mail sprzedawcy zostanie wysłana wiadomość informacyjna. W takim przypadku należy poprawić skrypt odbierający, aby prawidłowo przetwarzał przekazane parametry.

Zalecamy również upewnienie się, że podpis JWS przeszedł poprawną walidacje, skonfigurowano identyfikator sprzedawcy (Merchant ID) oraz kod bezpieczeństwa (dawniej Kod Potwierdzający).

Manualne ponowne wysyłanie powiadomień

System pozwala sprzedawcom na ponowne wysyłanie powiadomień dotyczących ich transakcji. Obecnie w zakładce szczegółów transakcji dostępne są następujące opcje:

1. Wysyłanie powiadomień za pomocą przycisku Wyślij ponownie. Powiadomienie zostanie wysłane na URL punktu końcowego powiadomień. Jeśli podczas tworzenia transakcji nie zdefiniowano URL wyniku lub nie został on ustawiony w Panelu Akceptanta, ta opcja nie będzie dostępna.
2. Wysyłanie przypomnienia o niedokończonej transakcji na adres e-mail płatnika. Transakcja, która nie została opłacona przez płatnika, otrzymuje status pending. Dla takich transakcji możliwe jest wysłanie przypomnienia o niedokończonej transakcji na adres e-mail płatnika podany na początku transakcji. Płatnik otrzyma wiadomość umożliwiającą dokończenie płatności. Opcja Wyślij przypomnienie, może być używana raz na 3 godziny.

Notyfikacja po zaksięgowaniu transakcji

Gdy transakcja zostanie poprawnie zaksięgowana wysyłamy powiadomienie POST z typem zawartości application/x-www-form-urlencoded do punktu końcowego Twojego systemu.

Konfiguracja adresu notyfikacji

Endpoint, na który zostanie wysłana notyfikacja o zaksięgowaniu transakcji, możesz skonfigurować w Panelu Akceptanta (Ustawienia > Powiadomienia).

Jeśli masz zaznaczoną opcję Zezwól na nadpisanie, możesz podać adres URL endpointa w parametrze callbacks.notification.url podczas tworzenia transakcji, na który zostanie wysłane powiadomienie zamiast domyślnego endpointu zapisanego w ustawieniach konta.

Przykład:

{
  "amount": 0.1,
  "description": "Test transaction Visa Mobile",
  "payer": {
    "email": "[email protected]",
    "name": "Jan Nowak"
  },
  "pay": {
    "groupId": 171
  },
  "callbacks": {
    "notification": {
      "url": "https://www.your-endpoint.com"
    }
  }
}

Parametry notyfikacji

Po każdej udanej transakcji następujące parametry zostaną wysłane na Twój endpoint.

* Pola, które zawsze znajdą się w treści powiadomienia.

Dodatkowe parametry, EISOP.

Oczekiwana odpowiedź

W odpowiedzi na powiadomienie o transakcji z Twojego serwera oczekujemy:

HTTP Code: 200

Body:

TRUE

Notyfikacja po tokenizacji bez obciążenia

Gdy tokenizacja bez obciążenia, realizowana poprzez endpoint /tokens zostanie poprawnie zakończona to wysyłamy powiadomienie POST z typem zawartości application/json do wskazanego endpointu Twojego systemu.

Konfiguracja adresu notyfikacji

Endpoint, na który zostanie wysłana notyfikacja o wyniku tokenizacji, musisz ustawić w parametrze callbackUrl, podczas tworzenia tokenizacji bez obciążenia. Parametr callbackUrl jest polem obowiązkowym - wynik tokenizacji nigdy nie jest wysyłany na adres URL ustawiony w Panelu Akceptanta.

Przykład:

{
  "payer": {
    "name": "Jan Nowak",
    "email": "[email protected]"
  },
  "callbackUrl": "https://your-page.com/webhook/tokens"
}

Parametry notyfikacji

Po każdej udanej tokenizacji następujące parametry zostaną wysłane na Twój endpoint.

Przykład:

{
  "type": "tokenization",
  "data": {
    "tokenizationId": "TO-XXX-XXXXX",
    "token": "fdc235...",
    "cardBrand": "Mastercard",
    "cardTail": "1111",
    "tokenExpiryDate": "0625"
  }
}

Oczekiwana odpowiedź

W odpowiedzi na powiadomienie o tokenizacji z Twojego serwera oczekujemy:

HTTP Code: 200

Body:

{
  "result": true
}

Notyfikacja dla aktualizacji tokenu lub karty

Poinformujemy cię o każdej zmianie statusu tokenu płatniczego lub wizerunku karty w programie Tokenizacja Plus. Zobacz więcej.

Konfiguracja adresu notyfikacji

Adres URL, na który wysyłane są powiadomienia o aktualizacji tokenu, zależy od sposobu utworzenia tokenu oraz konfiguracji w Panelu Akceptanta (Ustawienia > Powiadomienia → URL powiadomień o tokenie).

Tokeny utworzone w ramach tokenizacji bez obciążenia

Podczas tokenizacji do tokenu zapisywany jest adres URL do powiadomień o jego aktualizacjach:

• jeśli opcja Zezwól na nadpisanie adresu URL powiadomienia dot. tokenizacji jest włączona - zapisywany jest adres podany w parametrze callbackUrl,
• jeśli opcja jest wyłączona, a w Panelu Akceptanta ustawiony jest adres URL do powiadomień dot. tokenizacji - zapisywany jest ten adres z Panelu Akceptanta,
• jeśli w Panelu Akceptanta nie ustawiono adresu URL do powiadomień dot. tokenizacji - zapisywany jest adres podany w parametrze callbackUrl.

Tokeny utworzone w ramach tokenizacji podczas obciążenia karty

Ten sposób tokenizacji nie przewiduje parametru callbackUrl, dlatego do tokenu zawsze zapisywany jest adres z pola URL do powiadomień dot. tokenizacji.

Wysyłka powiadomienia

Niezależnie od sposobu utworzenia tokenu, w momencie wysyłki powiadomienia sprawdzamy aktualny stan opcji Zezwól na nadpisanie adresu URL powiadomienia dot. tokenizacji:

• jeśli opcja jest włączona - powiadomienie wysyłamy na adres zapisany przy tokenie (patrz wyżej),
• jeśli opcja jest wyłączona - powiadomienie wysyłamy na aktualny adres z pola URL do powiadomień dot. tokenizacji.

Parametry notyfikacji

Po każdej aktualizacji statusu tokenu następujące parametry zostaną wysłane na Twój endpoint.

Przykład:

{
  "type": "token_update",
  "data": {
    "token": "fdc235..."
  }
}

Oczekiwana odpowiedź

W odpowiedzi na powiadomienie o zmianie statusu tokenu z Twojego serwera oczekujemy:

HTTP Code: 200

Body:

{
  "result": true
}

Po otrzymaniu powiadomienia o zmianie statusu tokenu zalecamy ponowne pobranie statusu tokenu wraz z wizerunkiem karty, aby zaktualizować informacje w swoim systemie, więcej informacji.

Notyfikacja dla BLIK One Click/Płatności Powtarzalne o utworzeniu aliasu

Gdy alias utworzony na endpoint zostanie wysłane powiadomienie POST. Zobacz więcej.

Konfiguracja adresu notyfikacji

Do odbioru powiadomień dla transakcji BLIK One Click i Płatności Powtarzalnych konieczne jest podanie adresu powiadomień w Panelu Akceptanta oraz włączenie opcji Zezwól na nadpisanie adresu URL powiadomienia.

Dane skonfigurować możesz w Panelu Akceptanta w menu Ustawienia → Powiadomienia → w sekcji URL do powiadomień.

Parametry notyfikacji

Po każdej rejestracji aliasu następujące parametry zostaną wysłane na Twój endpoint.

Notyfikacja będzie dostarczona jako żądanie POST z zawartością w formacie application/x-www-form-urlencoded.

Przykład:

id=1010&event=ALIAS_REGISTER&md5sum=d303c5af701cdfcaed02f66603239eef&msg_value%5Bvalue%5D=user_unique_alias_123&msg_value%5Btype%5D=UID&msg_value%5BexpirationDate%5D=2024-11-02+14%3A15%3A01

Oczekiwana odpowiedź

W odpowiedzi na powiadomienie o zmianie statusu tokenu z Twojego serwera oczekujemy:

HTTP Code: 200

Body:

TRUE

Notyfikacja dla BLIK One Click/Płatności Powtarzalne o wygaśnięciu, zmianie lub usunięciu aliasu

Gdy alias zostanie usunięty, zmieniony lub upłynie data jego ważności. Na endpoint zostanie wysłane powiadomienie POST. Zobacz więcej.

Konfiguracja adresu notyfikacji

Do odbioru powiadomień dla transakcji BLIK One Click i Płatności Powtarzalnych konieczne jest podanie adresu powiadomień w Panelu Akceptanta oraz włączenie opcji Zezwól na nadpisanie adresu URL powiadomienia.

Dane skonfigurować możesz w Panelu Akceptanta w menu Ustawienia → Powiadomienia → w sekcji URL do powiadomień.

Parametry notyfikacji

Po każdej aktualizacji statusu aliasu następujące parametry zostaną wysłane na Twój endpoint.

Notyfikacja będzie dostarczona jako żądanie POST z zawartością w formacie application/x-www-form-urlencoded.

Przykład:

id=1010&event=ALIAS_UNREGISTER&md5sum=d303c5af701cdfcaed02f66603239eef&msg_value%5Bvalue%5D=user_unique_alias_123&msg_value%5Btype%5D=UID&msg_value%5BexpirationDate%5D=

Oczekiwana odpowiedź

W odpowiedzi na powiadomienie o zmianie statusu tokenu z Twojego serwera oczekujemy:

HTTP Code: 200

Body:

TRUE

Notyfikacja Marketplace

Gdy płatność realizowana poprzez endpoint /marketplace/v1/transaction zostanie poprawnie zakończona to wysyłamy powiadomienie POST z typem zawartości application/json do punktu końcowego Twojego systemu.

Konfiguracja adresu notyfikacji

Endpoint, na który zostanie wysłana notyfikacja o transakcji marketplace, musisz skonfigurować w parametrze callbackUrl, podczas tworzenia transakcji marketplace.

{
  "payer": {
    "name": "Jan Nowak",
    "email": "[email protected]"
  },
  "callbackUrl": "https://your-page.com/webhook/tokens"
}

Parametry notyfikacji

Po każdej udanej transakcji marketplace następujące parametry zostaną wysłane na Twój endpoint.

* Pola, które zawsze znajdą się w treści powiadomienia.

Oczekiwana odpowiedź

W odpowiedzi na powiadomienie o transakcji marketplace z Twojego serwera oczekujemy:

HTTP Code: 200

Body:

{
  "result": true
}