Tpay
API
Lista zmian

Karty

Płatności kartami to popularna metoda umożliwiająca dokonywanie transakcji przy użyciu kart debetowych lub kredytowych. Proces ten polega na wprowadzeniu danych karty, takich jak numer karty, data ważności oraz kod CVC/CVV, w formularzu płatności. Następnie, w celu weryfikacji tożsamości i zabezpieczenia transakcji, może być wymagane dodatkowe potwierdzenie, np. poprzez użycie 3D Secure, np. potwierdzenie w aplikacji wydawcy karty, kod na SMS lub kod PIN).

Zanim zaczniesz

Upewnij się, że:

Rodzaje obsługiwanych kart

Obecnie obsługujemy wyłącznie karty Visa i Mastercard.

Płatność w walucie

  • PLN - dokumentacja API Tpay.
  • Dla pozostałych walut - płatności w innych walutach są dostępne wyłącznie dla korzystających z acquirera Elavon. W celu implementacji skorzystaj z dokumentacji Tpay.

Transakcja kartowa

Realizuj płatności kartowe wykorzystując endpoint zakładania transakcji podając groupId: 103.

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 (w złotówkach).
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.

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
  }
}

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

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": "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.

Następnie 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 uwierzytelnienia 3DS.

3DS to protokół uwierzytelniania płatnika, 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 lub inne metody weryfikacji tożsamości.

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

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

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

Obsłuż powiadomienie

Poinformujemy Ciebie o statusie transakcji za pośrednictwem notyfikacji po zaksięgowaniu transakcji.

Transakcja kartowa on-site

Transakcja kartowa on-site polega na zaprezentowaniu w Twojej witrynie formularza do wprowadzenia danych karty płatniczej, który uzupełni płatnik.

Następnie podczas tworzenia transakcji, szyfrujesz dane karty kluczem publicznym RSA, dostępnym w Panelu Akceptanta

Zaszyfrowaną wartość przekazujesz w polu pay.cardPaymentData.card.

Uwaga

Pamiętaj, że każdego umożliwiającego płatności kartami, w szczególności udostępniającego je w swojej witrynie, obowiązują wytyczne bezpieczeństwa danych branży kart płatniczych PCI DSS (Payment Card Industry Data Security Standard), które są opisane na stronie standardu. Rozpocznij od strony: Czym jest kwestionariusz samooceny PCI DSS?

Zbuduj formularz płatności kartowej

W celu realizacji płatności kartowej wyświetl formularz płatności w swojej witrynie.

  1. Wyświetl płatność kartą jako dostępną metodę płatności.
  2. Wyświetl logo Visa oraz Mastercard.
  3. Umieść pola, w których płatnik może wpisać:
  • Numer karty.
  • Kod CVC/CVV.
  • Datę wygaśnięcia karty.
  1. Umieść regulamin Tpay - dostępny pod tym linkiem oraz klauzulę o przetwarzaniu danych osobowych - dostępną pod tym linkiem.

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 (w złotówkach).
description
Opis transakcji widoczny dla płatnika.
payer.email
Adres e-mail płatnika.
payer.name
Imię i nazwisko płatnika.
payer.groupId
Identyfikator grupy płatności dla kart: 103.

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
  }
}

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

Najważniejsze parametry odpowiedzi:

result
success - Transakcja została utworzona poprawnie.
status
pending - Transakcja oczekuje opłacenia.
transactionPaymentUrl
Adres URL, na który należy przekierować płatnika.
transactionId
Unikalny identyfikator transakcji - przechowaj go w swoim systemie.

Przykładowa odpowiedź:

{
  "result": "success",
  "requestId": "858fa92dc62db44e2c1f",
  "transactionId": "ta_9jQLGqzeY2eOVK01",
  "title": "TR-CWM-CNYHA6X",
  "posId": "ps_e4dkPVDEm4Jg726q",
  "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"
}

Zaszyfruj dane karty

Przygotuj ciąg znaków według wzoru:

numer karty|data wygaśnięcia (MM/RR lub MM/RRRR)|CVV lub CVC|host

Przykład:

1234567891234567|05/25|123|https://accountwebsite.com

Zaszyfruj ciąg znaków, używając klucza publicznego RSA oraz schematu wypełniania zgodnego ze standardem PKCS#1 v1.5.

Opłać transakcję wykorzystując zaszyfrowane dane karty

W celu opłacenia transakcji kartowej wykorzystaj wcześniej przechowany parametr transactionId, wysyłając żądanie POST na adres:

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

Umieść transactionID w adresie URL np.:

https://api.tpay.com/transactions/ta_jrkNGj5L29pnlbqw/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 karty: 103.
cardPaymentData.card
Zaszyfrowane dane karty.

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

{
  "groupId": 103,
  "cardPaymentData": {
    "card": "SxzdtoeZWhbQ2jufH7qBj55KGMc722+ULiNZN0ZSYff5keLEtfw6PP+aVCxZBRigaUyN2krJ3xy/0zREs59j6EclpPrEGtdtHOow1iNaLaabNvTN9mVN2FVeV1BRzDD4FSex9V2AK7j0+YII4JtPhYlYx4URWHe/5UqEYQjyoWc="
  }
}

Przykład:

curl --location 'https://api.tpay.com/transactions/ta_9jQLGqzeY2eOVK01/pay'\
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token> '\
--data '{
  "groupId": 103,
  "cardPaymentData": {
			"card": "SxzdtoeZWhbQ2jufH7qBj55KGMc722+ULiNZN0ZSYff5keLEtfw6PP+aVCxZBRigaUyN2krJ3xy/0zREs59j6EclpPrEGtdtHOow1iNaLaabNvTN9mVN2FVeV1BRzDD4FSex9V2AK7j0+YII4JtPhYlYx4URWHe/5UqEYQjyoWc=",
	}
}'

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

Obsłuż 3D Secure (3DS)

Parametr status o wartości pending, oznacza, że transakcja wymaga dodatkowego uwierzytelnienia 3DS. Przekieruj płatnika na adres zawarty w parametrze transactionPaymentUrl, gdzie będzie mógł zrealizować uwierzytelnienie 3DS.

Obsłuż powiadomienie

Oczekuj na swoim URL do powiadomień, notyfikacji o statusie płatności. Gdy płatność zostanie zakończona, otrzymasz dane transakcji wraz z jej statusem.

Wyświetl wynik transakcji

Poinformujemy Ciebie o statusie transakcji za pośrednictwem notyfikacji po zaksięgowaniu transakcji.

Uwaga

Jeśli chcesz obsłużyć płatności rekurencyjne za pomocą kart płatniczych przejdź do Tokenizacji.