VulCode

Integracja Tpay przez Open API

Przelewy, BLIK, karty i zwroty Tpay w sklepie, aplikacji albo na platformie z wieloma sprzedawcami. Z podpisem JWS sprawdzanym przy każdym powiadomieniu i statusami, którym można ufać.

Porównanie bramek płatności
Panel platformy: zamówienie 7731 od trzech sprzedawców opłacone jedną płatnością w Tpay i rozdzielone na transakcje podrzędne

Z czego składa się integracja Tpay

Od formularza w koszyku do księgowania wpłaty. Każda warstwa ma swoje zadanie i swój test.

Zanim zaczniemy

  • Konto w Tpay i dostęp do sandboxa zakładasz Ty, jako sprzedawca.
  • Jeśli sklep działa na popularnej platformie, Tpay ma do niej gotową wtyczkę i od niej zaczynamy.
  • Marketplace wymaga Programu Partnerskiego Tpay i osobnej umowy, więc ustalamy to na początku.
  • Klucze client_id i client_secret trzymamy w zmiennych środowiskowych, nigdy w kodzie.
Bez listy adresów IP

Tpay nie publikuje listy adresów IP, bo są dynamiczne. Jedynym zabezpieczeniem jest podpis, więc jego sprawdzenie jest obowiązkowe.

  1. Koszyk i formularz

    • wybór metody
    • pole kodu BLIK
    • zgoda na płatność powtarzalną

    Klient wybiera BLIK i wpisuje kod albo zgadza się na płatność powtarzalną.

  2. Twój serwer

    • token OAuth
    • POST /transactions
    • zapis transakcji przy zamówieniu

    Serwer tworzy transakcję i zapisuje ją przy zamówieniu.

  3. Tpay

    • strona płatności albo BLIK Level 0
    • autoryzacja w banku
    • rozliczenie

    Klient potwierdza płatność w banku, a Tpay ją rozlicza.

  4. Powiadomienia

    • podpis JWS w X-JWS-Signature
    • certyfikat sprawdzony z root CA Tpay

    Podpis JWS sprawdzony, zanim cokolwiek się zmieni.

    Tu zapada decyzja o statusie

  5. Zamówienie

    • status opłacone
    • zwroty
    • dziennik zdarzeń

    Status opłacone i wpis w dzienniku zdarzeń.

Trzy sposoby na BLIK w Tpay

BLIK może przekierować klienta, zostać na Twojej stronie albo pamiętać sklep na kolejne zakupy.

  • Z przekierowaniem

    formularz eBLIK
    Gdzie klient wpisuje kod
    na formularzu Tpay
    Pole w żądaniu
    groupId 150
    Klient zostaje w sklepie
    Nie
    Kolejne zakupy bez kodu
    Nie
    Dobre do
    najprostszego startu
    Potwierdzenie
    w aplikacji banku, kod BLIK jest ważny 2 minuty

  • Level 0

    kod na Twojej stronie
    Gdzie klient wpisuje kod
    w Twoim formularzu
    Pole w żądaniu
    blikToken z kodem
    Klient zostaje w sklepie
    Tak
    Kolejne zakupy bez kodu
    Nie
    Dobre do
    zakupów na telefonie
    Potwierdzenie
    w aplikacji banku, kod BLIK jest ważny 2 minuty

  • One Click

    alias zamiast kodu
    Gdzie klient wpisuje kod
    tylko przy pierwszej płatności
    Pole w żądaniu
    alias użytkownika
    Klient zostaje w sklepie
    Tak
    Kolejne zakupy bez kodu
    Tak
    Dobre do
    sklepów i aplikacji z kontami
    Potwierdzenie
    w aplikacji banku, kod BLIK jest ważny 2 minuty

Zwroty: pułapka statusu

Pełny i częściowy zwrot zachowują się w Tpay inaczej. Twój panel musi liczyć zwroty sam, a nie patrzeć tylko na status transakcji.

Zwrot do zamówienia 10533 w panelu sklepu: drugi zwrot częściowy domyka 100% kwoty, ostrzeżenie o statusie i sprawdzone saldo konta Tpay
  • Zwrot częściowy domyka 100%Pierwszy zwrot objął jeden talerz, drugi resztę zamówienia, razem całą kwotę. Dla Tpay oba są zwrotami częściowymi.
  • Status transakcji bez zmianZwroty częściowe nie zmieniają statusu w Tpay, nawet gdy dojdą do 100%. Kwotę zwróconą liczy Twój system, a status refund daje tylko zwrot całkowity.
  • Saldo sprawdzone przed zleceniemZwrot ruszy tylko wtedy, gdy saldo konta pokrywa kwotę i prowizję. Panel pokazuje to, zanim zlecisz zwrot.

Płatność w marketplace Tpay

Jedna płatność klienta za produkty od kilku sprzedawców. Tak wygląda przebieg w API marketplace.

  1. Klient 02217,00 zł

    Koszyk od trzech sprzedawców, jedna płatność.

    Twoja platforma

    Tpay nie porównuje kwot podrzędnych z cenami produktów, więc platforma sprawdza je z koszykiem, zanim utworzy transakcję.

    80,00 + 73,00 + 64,00 = 217,00 zł
    POST /marketplace/v1/transaction
  2. Tpay: transakcja główna217,00 zł

    Klient płaci raz, a Tpay dzieli kwotę na transakcje podrzędne sprzedawców.

  3. transakcje podrzędne
    • Sprzedawca 0180,00 zł
      • Świeca sojowa 180 g x 2: 68,00 zł
      • Dostawa: 12,00 zł
      konto Tpay 01J9W3K8QZ…C0MD
    • Sprzedawca 0273,00 zł
      • Ręcznik lniany 50 x 90 cm: 59,00 zł
      • Dostawa: 14,00 zł
      konto Tpay 01J9X0D4TR…KZ3W
    • Sprzedawca 0364,00 zł
      • Notes A5 w kropki x 3: 54,00 zł
      • Dostawa: 10,00 zł
      konto Tpay 01JA1R9C3N…HB5Z
Warunek startu
Marketplace działa tylko w Programie Partnerskim Tpay i po podpisaniu osobnej umowy.
Identyfikatory
Sprzedawcy i punkty płatności mają identyfikatory ULID zakodowane w base32. Przechowujemy je przy kontach sprzedawców.
Powiadomienie o opłaceniu
Z wartością, którą platforma nadała transakcji, np. numerem zamówienia.

Lista kontrolna przed uruchomieniem

To sprawdzamy na sandboxie Tpay, zanim przyjmiesz pierwszą prawdziwą płatność.

  • Ścieżka płatności3
  • Powiadomienia i zwroty3

Ścieżka płatności

  • Token OAuth i jego odnowienie

    Token domyślnie żyje 2 godziny. Moduł odnawia go przed wygaśnięciem, zamiast czekać na błąd.

  • Przekierowanie na transactionPaymentUrl

    Adres płatności przychodzi w odpowiedzi na utworzenie transakcji. Nie składamy go sami.

  • BLIK po czasie

    Kod żyje 2 minuty. Sprawdzamy komunikat dla klienta i możliwość ponowienia płatności.

Powiadomienia i zwroty

  • Podpis JWS przy każdym powiadomieniu

    Bez listy adresów IP podpis jest jedynym dowodem, że powiadomienie przyszło od Tpay.

  • Powtórzone powiadomienie

    Drugie powiadomienie o tej samej płatności nie może drugi raz aktywować usługi ani wysłać paczki.

  • Licznik zwrotów częściowych

    Status w Tpay nie mówi, ile zwrócono, więc panel liczy to sam.

Najczęstsze pytania o Tpay

Odpowiedzi o BLIK-u, marketplace i powiadomieniach.

Czytaj dalej

Strony, które warto zobaczyć przy wyborze bramki.

Sprzedajesz sam czy z innymi sprzedawcami?

Napisz, gdzie mają działać płatności Tpay i czy potrzebujesz marketplace. Odpowiemy w godzinę z pytaniami i wyceną.