Przejdź do głównej zawartości

Szybki start

Ten przewodnik przeprowadzi Cię od zera do pierwszej opłaconej transakcji w mniej niż 15 minut. Zakładamy, że masz już konto w panelu Paymentic — jeśli nie, załóż je tutaj.

wskazówka

Cały przewodnik wykonuj w środowisku Sandbox (https://api.sandbox.paymentic.com). Nie wiąże się ono z rzeczywistymi płatnościami i jest stworzone właśnie do testów.

Krok 1. Pobierz token API​

  1. Zaloguj się do panelu Paymentic.
  2. Przejdź do Integracja → Dostęp do API.
  3. Skopiuj swój API Token oraz Point ID (identyfikator punktu płatności).

Token wygląda mniej więcej tak: xWwPtTQ8SYA2xWbeuiDe8z8V71vRVO0a6srH3

ostrzeżenie

Token API traktuj jak hasło. Nigdy nie umieszczaj go w kodzie frontendowym, repozytorium Git ani logach. Trzymaj go w zmiennych środowiskowych (np. .env) lub menedżerze sekretów.

Krok 2. Utwórz pierwszą transakcję​

Wyślij zapytanie POST do endpointu /v1_2/payment/points/{pointId}/transactions, podstawiając swój pointId i token:

curl -X POST "https://api.sandbox.paymentic.com/v1_2/payment/points/{pointId}/transactions" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "19.99",
    "currency": "PLN",
    "title": "Moje pierwsze zamówienie"
  }'

W odpowiedzi otrzymasz identyfikator transakcji i redirectUrl do strony płatności:

{
  "data": {
    "id": "ABCD-123-XYZ-9876",
    "redirectUrl": "https://pay.sandbox.paymentic.com/ABCD-123-XYZ-9876?token=...",
    "whitelabel": null
  }
}
informacja

Zapamiętaj wartość data.id — to identyfikator transakcji, do którego będziesz się później odwoływać (w webhookach, statusach, zwrotach itd.).

Krok 3. Przekieruj klienta na stronę płatności​

W prawdziwej integracji na tym etapie przekierowujesz klienta na adres data.redirectUrl. Na czas testów po prostu otwórz ten link w przeglądarce i przejdź przez proces płatności (wybierz metodę, np. BLIK, i użyj kodu testowego 777256).

Krok 4. Skonfiguruj webhook​

Paymentic poinformuje Twój system o zmianie statusu transakcji wysyłając webhook (notyfikację HTTP POST) na Twój endpoint.

  1. W panelu, w Integracja → Notyfikacje, podaj publiczny URL swojego endpointu (np. https://twojsklep.pl/webhooks/paymentic).
  2. Skopiuj klucz podpisu sygnatury — będzie potrzebny do weryfikacji autentyczności webhooków.
  3. Upewnij się, że endpoint odpowiada HTTP 200 OK (z treścią OK) lub HTTP 202 (bez body).

Szczegóły formatu notyfikacji: Struktura webhooka. Szczegóły weryfikacji sygnatury: Sygnatura.

Krok 5. Odbierz webhook o zmianie statusu​

Po opłaceniu transakcji Paymentic wyśle na Twój endpoint zdarzenie PAYMENT.TRANSACTION_STATUS_CHANGED:

POST /webhooks/paymentic HTTP/1.1
Host: twojsklep.pl
Content-Type: application/json
X-Paymentic-Event: PAYMENT.TRANSACTION_STATUS_CHANGED
X-Paymentic-Notification-Id: 01j96yn02bhbv8j1jjtk36zn2t
X-Paymentic-Time: 2026-04-19T09:48:03+02:00
X-Paymentic-Signature: 5Fil+PMpabLxsKwo3rWj9+o6gAi4ub93fismBewbYz46mHt7pjPHcHELUVw8McZ5nUb3feMVVBl+dPzXq2XgLQ==

{
  "transactionId": "ABCD-123-XYZ-9876",
  "pointId": "000cb241",
  "status": "PAID",
  "amount": "19.99",
  "currency": "PLN",
  "commission": "0.39",
  "externalReferenceId": null,
  "paymentMethod": "BLIK",
  "paymentChannel": "blik-level0"
}

Twój endpoint powinien:

  1. Zweryfikować sygnaturę w nagłówku X-Paymentic-Signature (zob. Sygnatura).
  2. Zaktualizować status zamówienia w swoim systemie na podstawie pola status.
  3. Zwrócić HTTP 200 z treścią OK — inaczej Paymentic ponowi wysyłkę (zob. Ponawianie notyfikacji).

Minimalna checklista przed wejściem na produkcję​

  • Token produkcyjny jest w zmiennej środowiskowej, nie w kodzie.
  • Endpoint webhooka jest publicznie dostępny po HTTPS.
  • Sygnatura webhooka jest weryfikowana przed zaufaniem treści.
  • Obsługa webhooka jest idempotentna (ten sam X-Paymentic-Notification-Id nie powinien dwukrotnie zmieniać stanu zamówienia).
  • Endpoint odpowiada 200 OK szybko (pod 10 s) — ciężkie operacje przerzuć na kolejkę.
  • Testy obejmują scenariusze: PAID, FAILED, EXPIRED, CANCELED.
  • Logujesz wszystkie otrzymane webhooki (przydatne przy debugowaniu).

Co dalej?​