Quick Start integracji

Klucz API tworzysz w Zevio: Deweloperzy → REST API → sekcja kluczy. Skopiuj go przy utworzeniu i schowaj w bezpiecznym miejscu (menedżer haseł lub sekrety w infrastrukturze). Nie wklejaj go do aplikacji mobilnej dla klientów ani do publicznego repozytorium.

Każde wywołanie idzie na host API Twojego środowiska ze ścieżkami od /api/v1/. Pełny adres bazowy jest widoczny na stronie dokumentacji REST obok kluczy API. Klucz podajesz w nagłówku Authorization jako Bearer <twój klucz> (działa też sam klucz bez słowa Bearer).

Test i produkcja to osobne światy: osobne klucze i osobne dane - trzymaj zgodność z przełącznikiem Sandbox / Production w aplikacji.

„Oferta” to produkt lub usługa z ceną, walutą, opcjonalnym rozliczeniem cyklicznym, adresami powrotu po płatności/anulowaniu oraz dozwolonymi metodami płatności.

Najprościej: zakładka Oferty w panelu. Możesz też tworzyć i zmieniać oferty przez REST (/api/v1/qr…) - parametry i odpowiedzi są w interaktywnej dokumentacji REST.

Każda oferta ma stały identyfikator (qrId). Posłuży Ci przy linkach płatności, Checkout Session „z oferty” oraz przy łączeniu webhooków z konkretną sprzedażą. Własny numer zamówienia trzymaj w metadanych, jeśli zestawiasz to z ERP lub sklepem.

Najczęściej stosuje się jedno z dwóch podejść: hostowaną stronę Zevio (klient przechodzi pod adres wygenerowany przez API) albo osadzony checkout (klient zostaje na Twojej witrynie w iframe).

Hostowana strona - wywołaj POST /api/v1/payments/{qrId} z kluczem API. W odpowiedzi są link i destinationLink: link to pojedynczy adres do przekazania klientowi (prowadzi do płatności i jest zliczany); destinationLink to pełny URL docelowej strony płatności (np. {adres frontu Zevio}/pay/...).

Osadzenie - utwórz sesję przez POST /api/v1/checkout-sessions lub POST /api/v1/checkout-sessions/from-qr/{qrId}. W odpowiedzi dostajesz embedUrl do wczytania w iframe (typowo {front Zevio}/checkout/{sessionId}) oraz destinationEmbedUrl - bezpośredni adres widoku checkout pod iframe. Jak domknąć płatność po stronie Twojej witryny i jakie są sygnały zwrotne, opisuje dokumentacja REST w sekcji Checkout.

Zevio utrzymuje klientów w kontekście organizacji i dla każdego nadaje stabilny identyfikator (customerId). Powiąż go ze swoim kontem użytkownika lub rekordem w CRM - wtedy płatności, subskrypcje i webhooki konsekwentnie opisują tę samą osobę.

Przy wywołaniu linku płatności możesz podać customerId albo obiekt customer z adresem e-mail (oraz opcjonalnie imię, nazwisko, język). Bez znanego customerId system dopasowuje lub zakłada klienta po e-mailu w obrębie organizacji - przy udanym powiązaniu odpowiedź zawiera customer z customerId; zapisz go pod kolejne wywołania. Przy tworzeniu sesji checkout ten sam blok customer trafia do metadanych sesji i wraca w pierwszej odpowiedzi w metadata; stały customerId często pojawia się dopiero po udanej płatności - weź go z webhooka payment.success lub z API szczegółów płatności. Do obu ścieżek możesz dołożyć metadata z własnym numerem zamówienia lub koszyka, żeby szło dalej do eksportów i zdarzeń.

Jawne tworzenie rekordu z backendu (poza powyższymi ścieżkami) to POST /api/v1/customers - pola i reguły są w dokumentacji REST.

Portal klienta (samoobsługa przy hostowanych ekranach Zevio) uruchamiasz przez POST /api/v1/customer-portal-sessions; szczegóły żądania i odpowiedzi są przy tym endpoincie w dokumentacji REST.

Zamiast co chwilę odpytywać API „czy już zapłacono”, Zevio może wysłać na Twój HTTPS mały pakiet JSON, gdy dzieje się coś ważnego (np. sukces płatności, anulowanie subskrypcji).

Zarejestruj adres HTTPS pod Deweloperzy → Webhooki i wybierz zdarzenia. Konfiguracja URL-i i sekretów jest opisana w dokumentacji Webhooki w panelu.

Każde żądanie ma nagłówki x-zevio-event i x-zevio-signature oraz JSON z polami event, data i timestamp. Potwierdzaj autentyczność sekretem endpointu i surowym body - szczegóły podpisu i przykłady są w dokumentacji Webhooki. Dostawy mogą się powtarzać; pilnuj data.id, żeby każde zdarzenie biznesowe obsłużyć raz.

Spięcie integracji. W data masz kontekst operacji (obok wygenerowanego id dostawy).

Płatności. Przy payment.success backend zwykle przekazuje m.in. paymentId, qrId, customerId, kwoty i walutę; przy płatności w ramach cyklu często jest też subscriptionId. Jeśli przy tworzeniu linku lub sesji checkout dołożyłeś metadata, wraca ono tutaj - podpinaj pod nim numer zamówienia lub koszyk z ERP albo sklepu. Zaksięguj sukces idempotentnie (np. po paymentId albo kluczu z metadata) i utrwal customerId lub blok customer u siebie. payment.failed, payment.cancelled i payment.pending pozwalają odzwierciedlić niepowodzenie, rezygnację lub stan oczekiwania bez sondującego odpytywania API.

Subskrypcje. subscription.created niesie m.in. subscriptionId, qrId, customerId, powiązany paymentId startowy oraz kontekst oferty - to moment, by zapisać umowę cykliczną obok użytkownika po customerId. Gdy oferta ma włączoną promocyjną cenę próbną, pole data.status może być TRIAL do końca okna próbnego, potem ACTIVE. subscription.updated sygnalizuje kolejne płatności cykliczne i inne zmiany cyklu życia (w tym TRIAL→ACTIVE, anulowanie na koniec okresu, wznowienie). Zdarzenia subscription.canceled, subscription.expired i subscription.completed oznaczają zamknięcie lub koniec cyklu - dopasuj dostęp do produktu lub rozliczenia do status i dat w payloadzie.

Checkout w iframe. checkout_session.created i checkout_session.completed uzupełniają scenariusz osadzenia: masz identyfikatory sesji i płatności oraz echo metadata - wygodne obok payment.success, jeśli zamykasz koszyk po obu kanałach (link hostowany vs iframe).

Automatyzacja czasem zawiedzie lub spóźni się webhook. Traktuj aplikację jako kontrolę człowieka:

• Analityka - trendy i sumy.
• Subskrypcje i płatności → Płatności - pojedyncze próby i statusy.
• Subskrypcje i płatności → Subskrypcje - cykle i zgodność z webhookami.

Po zmianie kodu lub kluczy zajrzyj tu przed pełnym poleganiu na środowisku produkcyjnym.

Przejdź cały scenariusz przy włączonym Sandboxie: inne dane, inny klucz, ta sama logika co na produkcji. Zasady kart, BLIK i kwot testowych są w instrukcji Sandbox w aplikacji - zmieniają się częściej niż ten tekst.

Ten Quick Start to mapa. Eksplorator REST w panelu podaje każdy parametr i przykład odpowiedzi. Zakładka Webhooki - nazwy zdarzeń i przykładowe treści. Przy codziennej pracy trzymaj pod ręką Subskrypcje i płatności (widoki Płatności i Subskrypcje) oraz Analitykę.