Tokenizacja

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.

Wyróżniamy dwie opcje - tokenizację podczas realizacji transakcji kartowej oraz tokenizację bez obciążenia karty.

Zanim zaczniesz

Upewnij się, że:

• Posiadasz dane autoryzacyjne do API.
• Obsługujesz notyfikacje transakcji.
• Obsługujesz notyfikacje tokenizacji.
• Posiadasz włączone płatności kartowe.

Tokenizacja podczas realizacji transakcji kartowej

Zrealizuj płatność kartą i dodatkowo w jej wyniku otrzymaj token płatniczy. Ten scenariusz nazywamy tez: tokenizacją z obciążeniem.

Wyślij zapytanie o utworzenie transakcji kartowej

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

https://api.tpay.com/transactions

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

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:

Przykładowa odpowiedź:

{
  "result": "success",
  "requestId": "858fa92dc62db44e2c1f",
  "transactionId": "ta_9jQLGqzeY2eOVK01",
  "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:

Tokenizacja bez obciążenia

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.

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

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

https://api.tpay.com/tokens

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

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:

Przykładowa odpowiedź:

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

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 Scure (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 statusie tokenizacji na adres webhooka tokenizacji, który podałeś w body żądania (callbackUrl). Sprawdź szczegóły.

Tokenizacja Plus

Tokenizacja Plus to program, który oprócz wydania tokenu na potrzeby kolejnych transakcji kartowych, w tle wykonuje 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.

Utworzenie tokenu

Utworzenie tokenu zrealizujesz implementując:

• Tokenizacja bez obciążenia.

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

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

Parametry odpowiedzi:

Przykładowa odpowiedź:

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

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.

Obsługa powiadomienia o zmianie statusu tokenu lub wizerunku karty

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

Adres URL, na który wyślemy powiadomienie o zmianie statusu, to parametr callbackUrl, który został podany podczas tworzenia tokenu płatniczego.

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