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.
description *	Opis transakcji widoczny dla płatnika.
payer.email	Adres e-mail płatnika.
payer.name	Imię i nazwisko płatnika.
callbacks.notification.url	Adres URL, na który zostaną wysłane powiadomienia o płatności.
callbacks.payerUrls.success	Strona powrotu dla udanej płatności.
callbacks.payerUrls.error	Strona powrotu dla nieudanej płatności.

* Pola obowiązkowe.

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

{
  "amount": 0.1,
  "description": "Test transaction",
  "payer": {
    "email": "[email protected]",
    "name": "Jan Nowak"
  },
  "callbacks": {
    "notification": {
      "url": "https://example.shop/payment_notification"
    },
    "payerUrls": {
      "success": "https://example.shop/success",
      "error": "https://example.shop/error"
    }
  }
}

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"
   },
   "callbacks": {
      "notification": {
         "url": "https://example.shop/payment_notification"
      },
      "payerUrls": {
         "success": "https://example.shop/success",
         "error": "https://example.shop/error"
      }
   }
}'

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.

* Pola, które zawsze znajdą się w treści odpowiedzi.

Przykładowa odpowiedź:

{
  "result": "success",
  "requestId": "d3a9826d92c48cb8c185",
  "transactionId": "01K5BK4HEPB0WBCGT51FMTYSYJ",
  "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 wskazaną przy tworzeniu płatności stronę sukcesu callbacks.payerUrls.success lub stronę porażki callbacks.payerUrls.error w zależności od tego, czy transakcja się udała.

Uwaga

Przejście przez klienta na stronę sukcesu oznacza, że poprawnie przyjęliśmy od niego zlecenie płatności, ale nie oznacza jeszcze, że środki zostały przekazane. Informacja o poprawnym rozliczeniu zostanie przekazana w osobnym powiadomieniu wysłanym do Twojego systemu.

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/01K5BK4HEPB0WBCGT51FMTYSYJ

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

Przykład:

curl --location 'https://api.tpay.com/transactions/01K5BK4HEPB0WBCGT51FMTYSYJ' \
--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.