Tokenizacja kart

Tokenizacja karty płatniczej to proces, w którym wrażliwe dane karty płatnika są zastępowane indywidualnym ciągiem znaków (token), którym można się posługiwać w kolejnych transakcjach, zamiast używania danych karty. Jest to szczególnie przydatne w przypadkach płatności cyklicznych (np. abonament, raty itp.). Token może być przechowywany w Twoim systemie, za pomocą którego można zarówno obciążać kartę, jak i dokonywać zwrotów. Sprawdź, jak wykorzystać zapisany token do realizacji płatności.

Uwaga

Domyślnym sposobem tokenizacji kart płatniczych w Tpay był dotychczas zapis karty do postaci card-on-file (COF). Naturalną ewolucją tokenizacji kart płatniczych jest zmiana z COF na tokeny sieciowe (network token) - w Tpay za to rozwiązanie odpowiada usługa Tokenizacja Plus. Więcej przeczytasz w sekcji Tokenizacja Plus.

Zanim zaczniesz

Upewnij się, że:

Tokenizacja podczas obciążenia karty

Zrealizuj płatność kartą i dodatkowo w jej wyniku otrzymaj token płatniczy. Ten scenariusz nazywamy też: tokenizacją podczas realizacji transakcji kartowej.

Ten sposób tokenizacji znajdzie zastosowanie np. w takich scenariuszach:

Platforma subskrypcyjna ze stałą miesięczną opłatą - pierwszy miesiąc abonamentu jest płatny od razu, a w ramach tej samej transakcji zapisujesz kartę do dalszych, automatycznych rozliczeń.
Sklep zapisujący kartę przy pierwszym zamówieniu - płatnik płaci za swoje pierwsze zamówienie, a jednocześnie zapisujesz jego kartę, którą będzie mógł wybrać przy kolejnych zakupach.
Usługa z płatnością roczną - pierwsza opłata roczna jest jednocześnie momentem zapisania karty do kolejnych, corocznych rozliczeń.

Wyślij zapytanie o utworzenie transakcji kartowej

Aby utworzyć transakcję kartową, wyślij żądanie POST na endpoint:

https://api.tpay.com/transactions

Sprawdź szczegóły w dokumentacji API Reference: POST /transactions

W zapytaniu określ następujące parametry:

amount	Kwota transakcji.
description	Opis transakcji widoczny dla płatnika.
payer.email	Adres e-mail płatnika.
payer.name	Imię i nazwisko płatnika.
pay.groupId	Identyfikator grupy płatności dla kart: 103.
pay.cardPaymentData.save	Parametr określający chęć otrzymania tokenu płatniczego: 1

Podstawowe body żądania powinno wyglądać następująco:

{
  "amount": 0.1,
  "description": "Testowa płatność kartowa",
  "payer": {
    "email": "[email protected]",
    "name": "Jan Nowak"
  },
  "pay": {
    "groupId": 103,
    "cardPaymentData": {
      "save": 1
    }
  }
}

Przykład:

curl --location 'https://api.tpay.com/transactions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token> \
--data-raw '{
   "amount": 0.1,
   "description": "Testowa płatność kartowa",
   "payer": {
      "email": "[email protected]",
      "name": "Jan Nowak"
   },
   "pay": {
      "groupId": 103,
	"cardPaymentData" : {
		"save": 1
	}
   }
}'

Po wysłaniu żądania otrzymasz w odpowiedzi schemat Transaction Created.

Najważniejsze parametry odpowiedzi:

result	success - Transakcja została utworzona pomyślnie.
status	pending - Transakcja oczekuje opłacenia.
transactionPaymentUrl	Adres URL, na który należy przekierować płatnika.

Przykładowa odpowiedź:

{
  "result": "success",
  "requestId": "858fa92dc62db44e2c1f",
  "transactionId": "01K5BK4HEPB0WBCGT51FMTYSYJ",
  "title": "TR-CWM-CNYHA6X",
  "posId": "ps_e4dkPVDEm4Jg7267",
  "status": "pending",
  "date": {
    "creation": "2024-06-06 21:31:35",
    "realization": null
  },
  "amount": 0.1,
  "currency": "PLN",
  "description": "Testowa płatność kartowa",
  "hiddenDescription": "",
  "payer": {
    "payerId": "py_a9rjlZWxRLdG1bqY",
    "email": "[email protected]",
    "name": "Jan Nowak",
    "phone": "",
    "address": "",
    "city": "",
    "country": "PL",
    "postalCode": ""
  },
  "payments": {
    "status": "pending",
    "method": "pay_by_link",
    "amountPaid": 0,
    "date": {
      "realization": null
    }
  },
  "transactionPaymentUrl": "https://secure.tpay.com/?title=TR-CWM-CNYHA6X&uid=01HZQGHZP5P3P7YV8A4BRVDX17"
}

Przekieruj płatnika na Panel Transakcyjny

Przekieruj płatnika na URL zawarty w odpowiedzi w polu transactionPaymentUrl.

Płatnik wypełnia formularz danymi karty i zatwierdza formularz.

Uwierzytelnienie 3D Secure (3DS)

Jeśli zajdzie taka potrzeba, przekierujemy płatnika na stronę organizacji wydającej kartę płatniczą w celu dokonania uwierzytelnienia 3DS.

3DS to protokół uwierzytelniania, który ma na celu zwiększenie bezpieczeństwa transakcji internetowych realizowanych kartami płatniczymi. 3DS jest realizowany poprzez dodanie dodatkowego kroku uwierzytelnienia, zanim transakcja zostanie przekazana do autoryzacji.

Płatnik jest proszony o podanie dodatkowych danych uwierzytelniających. Mogą to być hasło, kod SMS, odcisk palca, autoryzacja w aplikacji banku lub inne metody weryfikacji tożsamości.

Jeśli płatnik pomyślnie przejdzie proces uwierzytelniania, transakcja zostanie przekazana do autoryzacji. W przeciwnym razie transakcja jest odrzucana.

Płatnik zostanie przekierowany na stronę sukcesu lub porażki

Gdy płatność zostanie zakończona, płatnik zostanie przekierowany na stronę sukcesu (success page) lub stronę porażki (error page) w zależności od tego, czy transakcja się udała.

Obsłuż powiadomienie

Poinformujemy Ciebie o statusie transakcji na webhook transakcyjny. Sprawdź szczegóły.

Dodatkowe parametry, które zostaną wysłane na webhook transakcyjny to:

card_token	Token karty, wykorzystaj go do późniejszych transakcji.
token_expiry_date	Data wygaśnięcia tokenu w formacie `MMYY`. Obecna tylko, jeśli token ma datę wygaśnięcia.
card_tail	Ostatnie 4 cyfry numeru stokenizowanej karty.
card_brand	Marka stokenizowanej karty. Możliwe wartości to Visa lub Mastercard.

Tokenizacja bez obciążenia karty

Tokenizacja bez obciążenia karty płatnika to scenariusz, w którym płatnik podaje numer karty. W tym procesie autoryzujemy płatność przy użyciu 3D Secure (3DS), ale nie obciążamy konta płatnika żadną kwotą. Na końcu wydajemy odpowiadający karcie token.

Ten sposób tokenizacji znajdzie zastosowanie np. w takich scenariuszach:

Darmowy okres próbny - zapisujesz kartę płatnika na start okresu próbnego, bez pobierania jakiejkolwiek opłaty; pierwsza faktyczna płatność następuje po jego zakończeniu.
Zapisanie karty w koncie klienta - płatnik dodaje kartę w ustawieniach swojego konta, bez wcześniejszego zamówienia, aby móc z niej skorzystać przy przyszłych zakupach.
Usługa w modelu pay-as-you-go - zapisujesz kartę przy rejestracji płatnika, a rozliczenia następują później, w zależności od faktycznego zużycia.

Wyślij zapytanie o utworzenie tokenizacji bez obciążenia

Aby rozpocząć tokenizację bez obciążenia, wyślij żądanie POST na endpoint:

https://api.tpay.com/tokens

Sprawdź szczegóły w dokumentacji API Reference: POST /tokens

W zapytaniu określ następujące parametry:

payer.email	Adres e-mail płatnika.
payer.name	Imię i nazwisko płatnika.
callbackUrl	Adres URL, na który prześlemy informację o wyniku tokenizacji. Pole obowiązkowe.

Podstawowe body żądania powinno wyglądać następująco:

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

Przykład:

curl --location 'https://api.tpay.com/tokens' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token> \
--data-raw '{
    "payer": {
        "name": "Jan Nowak",
        "email": "[email protected]"
    },
    "callbackUrl": "https://your-page.com/webhook/tokens"
}'

Po wysłaniu żądania otrzymasz w odpowiedzi schemat CardTokenizationCreated.

Najważniejsze parametry odpowiedzi:

result	success - Tokenizacja została utworzona poprawnie.
id	Identyfikator tokenizacji.
url	Adres URL, na który należy przekierować płatnika, w celu dokończenia procesu tokenizacji.

Przykładowa odpowiedź:

{
  "result": "success",
  "requestId": "34d5c290829d7a92c8c6",
  "id": "TO-BRA-01HZKX1YR6KDGH79YTVY4KCQ6B",
  "url": "https://cards.tpay.com/pay/01HZKX1Z0JSC4DX7KS2ANC459R"
}

Uwaga

Parametr id przechowaj w swoim systemie.

Przekieruj płatnika na Panel Transakcyjny

Przekieruj płatnika na URL zawarty w odpowiedzi w polu url.

Następnie płatnik wypełnia formularz danymi karty i zatwierdza go.

Uwierzytelnienie 3D Secure (3DS)

Jeśli zajdzie taka potrzeba, przekierujemy płatnika na stronę organizacji wydającej kartę płatniczą w celu dokonania uwierzytelnienia 3DS.

3DS to protokół uwierzytelniania, który ma na celu zwiększenie bezpieczeństwa transakcji internetowych realizowanych kartami płatniczymi. 3DS działa poprzez dodanie dodatkowego kroku uwierzytelnienia, zanim transakcja zostanie przekazana do autoryzacji.

Płatnik jest proszony o podanie dodatkowych danych uwierzytelniających. Mogą to być hasło, kod SMS, odcisk palca, autoryzacja w aplikacji lub inne metody weryfikacji tożsamości.

Jeśli płatnik pomyślnie przejdzie proces uwierzytelniania, tokenizacja zostanie przekazana do autoryzacji. W przeciwnym razie zostanie ona odrzucona.

Płatnik zostanie przekierowany na stronę sukcesu lub porażki

Gdy płatność zostanie zakończona, płatnik zostanie przekierowany na stronę sukcesu (success page) lub stronę porażki (error page) w zależności od tego, czy transakcja się udała.

Obsłuż powiadomienie

Poinformujemy Cię o wyniku tokenizacji na adres podany w parametrze callbackUrl. Sprawdź szczegóły.

Jeśli w Panelu Akceptanta nie ustawiłeś adresu URL do powiadomień dot. tokenizacji lub ustawiłeś go z włączoną opcją Zezwól na nadpisanie adresu URL powiadomienia dot. tokenizacji, na ten sam adres (callbackUrl) będziemy też wysyłać powiadomienia o późniejszych aktualizacjach tokenu. Sprawdź szczegóły.

Tokenizacja Plus

Tokenizacja Plus to sposób tokenizacji karty, w którym oprócz wydania tokenu na potrzeby kolejnych transakcji kartowych, w tle wykonuje ona także tokenizację sieciową danych karty. Tokenizacja sieciowa to uzyskanie w miejsce danych karty, tokenu sieciowego wydanego bezpośrednio przez organizacje kartowe Visa lub Mastercard. Inne nazwy tokenu sieciowego z którymi możesz się spotkać to: (ang.) network token, (ang.) scheme token, token Visa, token Mastercard.

W ten sposób w ramach usługi Tokenizacja Plus, Tpay będzie wykorzystywał do procesowania transakcji token sieciowy, zamiast danych karty. Wartością tokenu sieciowego jest to, że w sytuacji gdy stokenizowana karta płatnicza przestanie być ważna i płatnik w jej miejsce otrzyma nową, nastąpi automatyczne przedłużenie jej tokenu sieciowego, co w praktyce oznacza, że płatności cykliczne będą kontynuowane bez potrzeby interwencji sklepu czy właściciela karty. Gdy stokenizowana sieciowo karta zostanie zawieszona lub zamknięta, sklep otrzyma odpowiednią notyfikację, dzięki której będzie mógł np. skontaktować się z płatnikiem w celu zabezpieczenia ciągłości płatności.

W ramach programu Tokenizacja Plus dla tokenów, udostępniamy wizerunek karty oraz informujemy o każdej zmianie na karcie.

Uwaga

Tokenizacja Plus jest domyślnie włączona od 2026.08 dla korzystających z agenta rozliczeniowego Elavon. Rozwiązania dla innych agentów rozliczeniowych (Pekao, Worldline) są w przygotowaniu.

Uwaga

Jeśli korzystałeś z tokenizacji przed włączeniem Tokenizacja Plus, włączenie Tokenizacji Plus nie wpływa na działanie integracji z API Tpay. Niezależnie od tego, czy dany token został objęty tokenizacją sieciową czy był zapisywany jako card-on-file (COF), wszystko działa tak samo. Sposób jego tworzenia i wykorzystania jest identyczny, a request i response pozostają takie same. Nie musisz (ani nie możesz) samodzielnie wybierać mechanizmu stojącego za tokenem.

Uwaga

Włączenie Tokenizacji Plus

Jeśli chcesz skorzystać z Tokenizacji Plus, zgłoś ten fakt zespołowi wsparcia Tpay. Jeśli nie zgłosisz tego samodzielnie, a zauważymy transakcje kartowe kwalifikujące się do Tokenizacji Plus, włączymy tę usługę z naszej strony. Samodzielne zgłoszenie spowoduje jednak, że tokeny sieciowe będą dostępne już od pierwszych wykonanych tokenizacji, bez oczekiwania na automatyczne wykrycie po stronie Tpay.

Utworzenie tokenu

Token w ramach Tokenizacji Plus otrzymasz automatycznie, tworząc token jedną z dwóch metod opisanych w tym dokumencie - nie musisz nic dodatkowo konfigurować:

Uwaga

Wybór metody nie ma wpływu na objęcie tokenu programem Tokenizacja Plus. O ile transakcja kwalifikuje się do programu, tokenizacja sieciowa zostanie wykonana niezależnie od tego, czy token powstał z obciążeniem, czy bez obciążenia karty.

Pobranie statusu tokenu wraz z wizerunkiem karty

Aby pobrać status tokenu wraz z wizerunkiem karty, wyślij żądanie GET na endpoint:

https://api.tpay.com/tokens/{tokenValue}

Zastąp {tokenValue} wartością tokenu otrzymaną w notyfikacji webhook tokens.

Przykładowy URL:

https://api.tpay.com/tokens/bfbde8ba10da6215fe92fb28b8787d154afc5cdacaee72fbb91042ccf544f871

Sprawdź szczegóły w dokumentacji API Reference: GET /tokens/{tokenValue}

Uwaga

Ten endpoint zwraca obecnie informacje wyłącznie dla tokenów wygenerowanych w ramach włączonej usługi Tokenizacja Plus. Rozszerzenie jego działania o pozostałe tokeny jest w przygotowaniu.

Parametry odpowiedzi:

paymentInstrument	Mechanizm stojący za tokenem `NETWORK_TOKEN` (token sieciowy wydany w ramach Tokenizacji Plus) lub `COF` (standardowy zapis karty - card-on-file).
expirationDate	Data wygaśnięcia stokenizowanej karty w formacie `MMRR`.
tokenStatus	Status tokenu (ACTIVE, DELETED, SUSPENDED). Dostępny wyłącznie dla tokenów sieciowych - dla tokenów `COF` zwracany jest `null`.
cardTail	Ostatnie 4 cyfry numeru stokenizowanej karty.
cardImage	Adres URL z wizerunkiem stokenizowanej karty. Dostępny wyłącznie dla tokenów sieciowych - dla tokenów `COF` zwracany jest `null`.

Przykładowa odpowiedź dla tokenu sieciowego (Tokenizacja Plus):

{
  "paymentInstrument": "NETWORK_TOKEN",
  "expirationDate": "0427",
  "tokenStatus": "ACTIVE",
  "cardTail": "9588",
  "cardImage": "https://cards-img.tpay.com/01ABCDEFGH23456IJKLM7890NO_01ABCDEFGH23456IJKLMN7890V"
}

Przykładowa odpowiedź dla standardowego zapisu karty (card-on-file):

{
  "paymentInstrument": "COF",
  "expirationDate": "0427",
  "tokenStatus": null,
  "cardTail": "9588",
  "cardImage": null
}

Uwaga

Token otrzymuje paymentInstrument: COF także wtedy, gdy próba objęcia go Tokenizacją Plus się nie powiodła - w takim przypadku token pozostaje aktywny i dostępny do płatności jako standardowy zapis karty, a pola tokenStatus i cardImage zwracane są jako null

Pod adresem URL zwróconym w polu cardImage znajduje się gotowa do wyświetlenia wizualizacja karty płatnika, którą możesz zaprezentować np. w panelu klienta przy zapisanej metodzie płatności. Dotyczy to wyłącznie tokenów sieciowych (paymentInstrument: NETWORK_TOKEN).

Usunięcie tokenu

Aby usunąć i dezaktywować token płatniczy, wyślij żądanie DELETE na endpoint:

https://api.tpay.com/tokens/{tokenValue}

Zastąp {tokenValue} wartością tokenu otrzymaną w notyfikacji webhook tokens.

Przykładowy URL:

https://api.tpay.com/tokens/bfbde8ba10da6215fe92fb28b8787d154afc5cdacaee72fbb91042ccf544f871

Po wysłaniu żądania otrzymasz w odpowiedzi HTTP Status 204 - No Content.

Sprawdź szczegóły w dokumentacji API Reference: DELETE /tokens/{tokenValue}

Uwaga

Proces usuwania tokenu jest asynchroniczny.

Obsługa powiadomienia o zmianie statusu tokenu lub wizerunku karty

Będziemy informować Cię za pomocą notyfikacji dla aktualizacji tokenu lub karty o każdej zmianie statusu tokenu płatniczego lub wizerunku karty.

Sposób ustalenia adresu URL, na który wysyłamy to powiadomienie, opisaliśmy szczegółowo w sekcji Notyfikacja dla aktualizacji tokenu lub karty.

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

Płatność zapisanym tokenem

Uzyskany token wykorzystasz do obciążenia karty płatnika bez konieczności ponownego wprowadzania jej danych - np. w płatnościach cyklicznych (abonamenty, raty) lub przy ponownym zamówieniu. Dotyczy to każdego tokenu opisanego w tym dokumencie, niezależnie od tego, czy powstał w ramach Tokenizacji Plus, czy jako standardowy zapis karty (card-on-file) - sposób jego wykorzystania jest identyczny.

Aby zapłacić zapisanym tokenem, utwórz transakcję (POST /transactions) tak jak przy zwykłej płatności kartowej, a następnie opłać ją tokenem, wysyłając żądanie POST na endpoint:

https://api.tpay.com/transactions/{transactionId}/pay

Sprawdź szczegóły w dokumentacji API Reference: POST /transactions/{transactionId}/pay

W zapytaniu określ następujące parametry:

groupId	Identyfikator grupy płatności dla kart: 103.
cardPaymentData.token	Wartość zapisanego tokenu karty (parametr `card_token`/`token` otrzymany w notyfikacji).
cof	Typ płatności wykonywanej zapisanym tokenem, zgodny ze standardem Credentials On File - np. `cardholder_initiated`, `recurring` lub `unscheduled`.

{
  "groupId": 103,
  "cardPaymentData": {
    "token": "t59c2810d59285e3e0ee9d1f1eda1c2f4c554e24"
  },
  "cof": "recurring"
}

Po wysłaniu żądania otrzymasz w odpowiedzi taki sam schemat TransactionCreated, jak w przypadku standardowej transakcji kartowej.

Uwaga

Szczegółowy opis poszczególnych typów płatności zapisanym tokenem (CIT recurring, MIT recurring, MIT unscheduled), wymogów organizacji kartowych oraz przykładów end-to-end znajdziesz w dokumentacji dotyczącej rekurencji kartowej.