Pierwsza transakcja

Poniżej opisano podstawowy proces zakładania i realizacji transakcji w naszym systemie.

Stwórz transakcje

Aby utworzyć transakcję, 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.

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

{
  "amount": 0.1,
  "description": "Test transaction",
  "payer": {
    "email": "[email protected]",
    "name": "Jan Nowak"
  }
}

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": "Test transaction",
   "payer": {
      "email": "[email protected]",
      "name": "Jan Nowak"
   }
}'

Najważniejsze parametry odpowiedzi:

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

Przykładowa odpowiedź:

{
  "result": "success",
  "requestId": "d3a9826d92c48cb8c185",
  "transactionId": "ta_bKvkJX9Knk9Ol4od",
  "title": "TR-CWM-CS7LW1X",
  "posId": "ps_e4dkPVDEm4Jg726q",
  "status": "pending",
  "date": {
    "creation": "2024-06-12 21:29:35",
    "realization": null
  },
  "amount": 0.1,
  "currency": "PLN",
  "description": "Test transaction",
  "hiddenDescription": "",
  "payer": {
    "payerId": "py_a9rjlZWxRLdG1bqY",
    "email": "[email protected]",
    "name": "Jan Nowak",
    "phone": "",
    "address": "",
    "city": "",
    "country": "PL",
    "postalCode": ""
  },
  "payments": {
    "status": "pending",
    "method": null,
    "amountPaid": 0,
    "date": {
      "realization": null
    }
  },
  "transactionPaymentUrl": "https://secure.tpay.com/"
}

Przekieruj płatnika na Panel Transakcyjny

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

Następnie płatnik na Panelu Transakcyjnym wybiera formę, w jakiej chce opłacić transakcję i ją realizuje.

Autoryzacja płatności

W niektórych formach płatności występują dodatkowe autoryzacje, które płatnik musi zatwierdzić lub zrealizować, takie jak:

Autoryzacja kodu BLIK
Autoryzacja 3D Secure
Autoryzacja Visa Mobile

Więcej informacji znajdziesz w dokumentacji poszczególnych metod płatności.

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.

Oczekuj notyfikacji o udanej transakcji

Płatność w naszym systemie odbywa się w pełni procesem asynchronicznym.

Asynchroniczność oznacza, że proces płatności nie jest wykonywany natychmiastowo ani w jednej linii czasu, ale działa niezależnie. Dlatego status transakcji może zmienić się w każdej chwili.

Gdy status transakcji zmieni się na opłaconą, poinformujemy Twój system o udanej płatności za pomocą notyfikacji. Po otrzymaniu notyfikacji obsłuż ją odpowiednio w swoim systemie, np. zaktualizuj status zamówienia, wyślij potwierdzenie do klienta, zrealizuj usługę. Więcej informacji o webhookach transakcji znajdziesz tutaj.

Pobranie statusu transakcji

Uwaga

Nie używaj tego endpointu do sprawdzania statusu każdej transakcji. Zamiast tego, zaimplementuj odbieranie notyfikacji o udanej transakcji. Zalecamy, byś wykorzystywał to rozwiązanie jedynie jako zapasowe (fallback).

Aby sprawdzić aktualny status transakcji, wyślij żądanie GET na endpoint:

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

Zastąp {transactionId} identyfikatorem transakcji, dla której chcesz uzyskać status:

https://api.tpay.com/transactions/ta_jrkNGj5L29pnlbqw

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

Przykład:

curl --location 'https://api.tpay.com/transactions/ta_jrkNGj5L29pnlbqw' \
--header 'Authorization: Bearer <access_token>

Po wysłaniu żądania otrzymasz w odpowiedzi schemat GET /transactions.

Identyfikator płatności

Podstawowym identyfikatorem płatności jest parametr transactionId.

Wskazówki dotyczące przechowywania transactionId:

Podczas tworzenia transakcji: Upewnij się, że zapisujesz parametr transactionId w swoim systemie.
Długoterminowe przechowywanie: Przechowuj transactionId długoterminowo, aby móc analizować problemy, obsługiwać zgłoszenia i prowadzić dochodzenia w przypadku wystąpienia problemów.
Wsparcie BOK: Dzięki temu parametrowi, nasz zespół Obsługi Klienta będzie w stanie udzielić Ci pomocy w razie jakichkolwiek problemów.

Zapewnienie, że transactionId jest przechowywane i dostępne w Twoim systemie, jest kluczowe dla skutecznej obsługi płatności i wsparcia technicznego.