Quick Start integracji (panel)

W panelu Deweloperzy → Quick Start znajduje się interaktywny przewodnik integracji: linki do operacji REST API, przykłady żądań i odpowiedzi oraz skróty do Kluczy API, Webhooków i Sesji checkout. Pełna wersja statyczna: Quick Start integracji w dokumentacji. Dostęp: plan Basic+ dla sekcji Deweloperzy; interaktywny Quick Start w panelu - od Enterprise (lub rola ADMIN/OWNER według konfiguracji produktu).

Typowy przepływ integracji

  • 1. Klucz API - utwórz w Klucze API, zapisz secret, używaj Authorization: Bearer.
  • 2. Oferta (qrId) - utwórz w panelu lub POST /api/v1/qr.
  • 3. Płatność klienta - link hostowany (POST /payments) albo sesja checkout (POST /checkout-sessions/{qrId}) z embedLink.
  • 4. Webhooki - zarejestruj URL, weryfikuj podpis, obsługuj payment.succeeded, payment.failed, refund.*, zdarzenia subskrypcji.
  • 5. Sandbox → Produkcja - osobne klucze, oferty i webhooki; przetestuj pełny cykl przed go-live.

Co znajdziesz w panelu Quick Start

  • Lista kroków z linkami do dokumentacji operacji w REST API.
  • Przykładowe payloady tworzenia płatności i sesji checkout.
  • Informacja o postMessage (CHECKOUT_*) przy osadzaniu iframe.
  • Odnośniki do Kody błędów i Stripe (gdy włączony).

Sandbox a produkcja

Każde środowisko ma własny host API, klucze i dane. Przełącznik w nagłówku panelu nie kopiuje konfiguracji - przenosisz ją ręcznie. Szczegóły: Środowiska i Przełączanie środowisk.

Członek zespołu (MEMBER) nie widzi sekcji Deweloperzy. Integrację konfigurują właściciel lub administrator organizacji.

Minimalny przykład sesji checkout

POST /api/v1/checkout-sessions/{qrId} z body: embedLink (HTTPS strony rodzica), opcjonalnie successUrl, cancelUrl, expiresInMinutes, lineItems, metadata. Odpowiedź: sessionId, embedUrl, expiresAt.

Minimalny webhook handler

  • Odbierz POST JSON.
  • Zweryfikuj podpis HMAC nagłówkiem z panelu Webhooki.
  • Obsłuż idempotentnie po paymentId / eventId.
  • Zwróć 2xx szybko; ciężką logikę wrzuć do kolejki.

Test w Sandbox

Użyj klucza Sandbox, utwórz testową ofertę 1 PLN, wywołaj complete z testowym BLIK (patrz dokumentacja Tpay sandbox). Obserwuj webhook w logach Deweloperzy → Webhooki.

Typowe błędy integracji

  • 401 - zły klucz lub środowisko.
  • 403 - plan Free lub brak uprawnień.
  • 409 - duplikat idempotency / sesja już COMPLETED.
  • CSP - brak embedLink w allowlist frame-ancestors.
Quick Start integracji (panel) | Zevio