Merchant API Volet: jak zintegrować płatności w sklepie?
Merchant API Volet pozwala budować własny przepływ płatności krypto i sprawdzać status faktury z backendu. Jeśli chcesz szybciej uruchomić płatności w sklepie, Hosted Checkout przenosi klienta na stronę płatniczą Volet i obsługuje także płatność z konta Volet. Dla WordPressa lub WooCommerce może wystarczyć gotowa wtyczka. Wybór zależy od tego, czy potrzebujesz własnego interfejsu, płatności z salda Volet, czy po prostu działającego checkoutu bez pisania integracji od zera.
Wybierz metodę przed rozpoczęciem integracji
- ✓Hosted Checkout — gotowa strona Volet; obsługuje płatność użytkownika Volet i krypto. Powiadomienia Status URL służą do aktualizacji zamówienia.
- ✓Merchant API — własny checkout dla płatności krypto; backend tworzy fakturę i odpytuje API o status.
- ✓Wtyczka CMS — najprostsza droga dla wspieranych sklepów, m.in. WooCommerce/WordPress i OpenCart; działanie opiera się o Hosted Checkout.
- ✓Smart Contract Integration — ścieżka non-custodial dla aplikacji Web3; wymaga innej architektury niż typowy sklep internetowy.
- ✓Nigdy nie oznaczaj zamówienia jako opłaconego tylko na podstawie URL powrotnego. Waliduj podpis powiadomienia lub sprawdzaj status przez API.
Spis treści
Hosted Checkout czy Merchant API?
„Merchant API Volet” bywa używane jako zbiorcza nazwa narzędzi dla sprzedawców, ale integracje mają różny zakres. Według aktualnej dokumentacji Hosted Checkout jest gotową stroną płatności i wspiera płatności z kont Volet oraz krypto. API do akceptacji płatności służy do tworzenia faktur krypto i odczytu ich statusu. Jeśli klient ma płacić ze swojego salda Volet, użyj Hosted Checkout (albo wtyczki, która go wykorzystuje).
| Metoda | Interfejs płatności | Metody wskazywane w dokumentacji | Najlepsze zastosowanie |
|---|---|---|---|
| Hosted Checkout | Strona płatności hostowana przez Volet | Konto Volet i obsługiwane kryptowaluty | Szybsze wdrożenie, mniej własnego kodu checkoutu |
| Merchant API | Budujesz własny ekran płatności | Faktury/płatności krypto z zewnętrznych portfeli | Własny UX, aplikacja, sklep z backendem |
| API + Hosted Checkout | Strona Volet, statusy i uzgadnianie w Twoim backendzie | Hosted Checkout dla klienta, API do sprawdzania zamówienia | Własny obieg zamówień z gotowym checkoutem |
| Plugin CMS | Hosted Checkout | Zależnie od ustawień bramki | WooCommerce/WordPress lub wspierany CMS |
| Smart contract | Budujesz własny przepływ Web3 | Płatność on-chain non-custodial | Projekty Web3 z własnym zapleczem blockchain |
Co przygotować przed integracją?
- Konto i weryfikacja: do korzystania z custodial gateway wymagane jest zweryfikowane konto Volet. Dostępność i wymagania zależą od kraju, rodzaju konta i działalności.
- Gateway płatniczy: w panelu przejdź do Payment Tools i utwórz Hosted Checkout albo API gateway. Skonfiguruj metody, walutę rozliczenia, nazwę i adres witryny.
- Akceptacja gatewaya: nowe custodial gatewaye wymagają zatwierdzenia przed przyjmowaniem płatności produkcyjnych. Możesz wykorzystać ten czas na development i testowanie.
- Backend sklepu: przygotuj unikalny order ID, statusy zamówienia (oczekujące, opłacone, nieudane/wygasłe) i sposób uzgadniania wpłaty.
- Adresy serwerowe: dla Hosted Checkout ustaw Status URL, Success URL i Failed URL; dla API-only przygotuj serwerowe odpytywanie stanu faktury.
- Sekrety: wygeneruj osobne hasło/poufne dane do gatewaya, trzymaj je po stronie serwera i ogranicz dostęp do nich.
W ustawieniach Hosted Checkout możesz zdecydować, kto ponosi opłatę processingową, a także czy gateway przyjmuje niedopłatę lub nadpłatę. Te opcje wpływają na obsługę zamówień: ustal wcześniej, kiedy automatycznie uznajesz płatność, kiedy prosisz o dopłatę, a kiedy wymagana jest ręczna kontrola.
Hosted Checkout: integracja krok po kroku
Krok 1. Utwórz Hosted Checkout
W panelu Volet otwórz Payment Tools → Hosted Checkout → Create. Włącz metody, które chcesz oferować, ustaw walutę rozliczenia i konfigurację. Podaj URL sklepu, ustaw hasło Hosted Checkout i skonfiguruj Status URL, Success URL oraz Failed URL. Jeśli sklep ma działać produkcyjnie, włącz cyfrowy podpis żądań i powiadomień.
Krok 2. Utwórz zamówienie u siebie i wygeneruj podpis na serwerze
Każde żądanie musi zawierać unikalny identyfikator zamówienia. Podstawowe pola formularza POST to adres e-mail konta Volet, nazwa Hosted Checkout, kwota, waluta, order ID i podpis. Podpis `ac_sign` to SHA-256 ze skonkatenowanego ciągu w kolejności: e-mail konta, nazwa checkoutu, kwota, waluta, hasło gatewaya, order ID — pola rozdzielone dwukropkami. Oblicz go na backendzie. Nie umieszczaj hasła w HTML ani JavaScript klienta.
Przykładowy formularz — wartości podpisu generuje backend
<form method="POST" action="https://account.volet.com/api/public/payment-gateway">
<input type="hidden" name="ac_account_email" value="MERCHANT_EMAIL">
<input type="hidden" name="ac_sci_name" value="NAZWA_CHECKOUTU">
<input type="hidden" name="ac_amount" value="49.90">
<input type="hidden" name="ac_currency" value="EUR">
<input type="hidden" name="ac_order_id" value="UNIKALNY_ORDER_ID">
<input type="hidden" name="ac_sign" value="PODPIS_SHA256_Z_BACKENDU">
<button type="submit">Zapłać przez Volet</button>
</form>Nie ufaj kwocie przesłanej przez przeglądarkę. Backend powinien pobrać kwotę i walutę z własnego, zapisanego zamówienia, a potem zbudować podpis. W przeciwnym razie klient może próbować zmienić kwotę lub order ID.
Krok 3. Obsłuż Status URL
Po zmianie statusu Volet wysyła powiadomienie na serwerowy Status URL metodą GET albo POST, zależnie od konfiguracji. Powiadomienie zawiera m.in. ID transakcji, status, order ID, kwotę klienta oraz kwotę i walutę zaksięgowaną u sprzedawcy, a także `ac_hash`. Backend powinien odszukać istniejące zamówienie, odrzucić nieprawidłowy podpis, sprawdzić kwotę/walutę i wykonać idempotentną zmianę statusu.
Krok 4. Wróć klienta do sklepu
Success URL i Failed URL służą do pokazania klientowi odpowiedniego ekranu po płatności. Nie są dowodem zapłaty: klient może zamknąć przeglądarkę, a sam adres powrotu może być wywołany ręcznie. Ostateczny status zamówienia aktualizuj po zweryfikowanym Status URL, ewentualnie sprawdzając stan przez API.
Własny checkout krypto przez Merchant API
Wybierz API-only wtedy, gdy chcesz samemu zbudować ekran płatności i pokazać klientowi instrukcję transferu. Typowy przepływ to: utworzenie zamówienia, utworzenie faktury krypto przez backend, wyświetlenie dokładnego adresu i parametrów faktury, a następnie odpytywanie endpointu statusu. API + Hosted Checkout łączy tworzenie/uzgadnianie płatności po stronie backendu z gotową stroną klienta.
Żądania Merchant API wymagają nagłówków `Api-Name`, `Account-Email` i `Authentication-Token`. Token uwierzytelniający jest generowany z sekretu API. Sekret i token trzymaj na backendzie; nie ujawniaj ich w kodzie frontendu, aplikacji mobilnej ani publicznym repozytorium. Przy konfiguracji gatewaya nadaj wyłącznie wymagane uprawnienia, np. akceptację płatności krypto oraz Find transaction do odczytu statusu.
Dla API-only integracja nie korzysta z callbacków Hosted Checkout. Backend odpytuje Volet o status faktury. Status `CREATED` albo `PROCESSING` nie oznacza, że zamówienie jest opłacone. Dokumentacja wskazuje `COMPLETED` jako status do oznaczenia płatności jako zakończonej; przy `FAILED` lub wygasłej fakturze nie wydawaj produktu.
Podpisy, statusy i zabezpieczenia — nie pomijaj tego
- ✓Używaj nowego, niepowtarzalnego order ID dla każdego checkoutu; przechowuj mapowanie ID sklepu i transakcji Volet.
- ✓Weryfikuj `ac_hash` powiadomienia przed aktualizacją zamówienia. Dokumentacja określa skład podpisu w kolejności: transfer ID, czas, nazwa checkoutu, portfel źródłowy, portfel docelowy, order ID, kwota, waluta sprzedawcy i hasło gatewaya — rozdzielone dwukropkami, SHA-256.
- ✓Sprawdź zgodność kwoty, waluty i order ID z oczekiwanym zamówieniem, a obsługę powiadomień zaprojektuj jako idempotentną.
- ✓W Hosted Checkout nie polegaj na przekierowaniu przeglądarki; w API-only odpytywanie statusu realizuj po stronie serwera.
- ✓Ogranicz IP API, jeśli możesz, używaj HTTPS, rotuj sekrety i rejestruj błędy bez logowania haseł/tokenów.
Powiadomienia mogą być ponawiane, a ruch sieciowy może być opóźniony. Zapisuj event/transaction ID i status przetworzenia. Jeśli nie możesz bezpiecznie przetworzyć callbacka, nie oznaczaj zamówienia jako opłaconego — wykonaj ponowną weryfikację przez API lub zgodnie z procedurą supportu.
Testy przed uruchomieniem płatności
Volet wymaga zatwierdzenia gatewaya przed obsługą produkcyjnych transakcji. Zanim włączysz metodę klientom, przetestuj całą ścieżkę dla sukcesu, błędu i anulowania. Dokumentuj przypadki testowe i używaj niewielkich kwot, jeśli test wymaga prawdziwej płatności.
| Test | Co potwierdzić |
|---|---|
| Tworzenie zamówienia | Kwota, waluta i order ID pochodzą z backendu i są unikalne. |
| Podpis żądania | Volet akceptuje poprawny podpis; błędne dane nie tworzą płatności. |
| Przejście checkoutu | Klient widzi właściwą nazwę sklepu, kwotę, metodę i walutę. |
| Status URL | Serwer odbiera GET/POST, waliduje podpis i obsługuje ponowne powiadomienie bez podwójnego wydania. |
| API-only invoice | Adres, sieć, kwota, tag/memo i data ważności są pokazane dokładnie jak zwrócone. |
| Statusy | `CREATED`/`PROCESSING` pozostają oczekujące; produkt jest wydany dopiero przy `COMPLETED`. |
| Błędy i retry | Nie powstaje podwójne zamówienie; nieudana lub wygasła faktura ma czytelną ścieżkę ponowienia. |
| Powrót przeglądarki | Success/Failed URL nie zmieniają statusu płatności po stronie serwera. |
Dla WordPressa/WooCommerce sprawdź, czy oficjalna wtyczka jest dostępna w panelu lub katalogu Volet, czy odpowiada Twojej wersji sklepu, i wykonaj testy także po aktualizacji WordPressa, motywu oraz bramki. Jeśli wtyczka używa Hosted Checkout, nadal upewnij się, że webhook/status URL aktualizuje zamówienie poprawnie.
Opłaty, waluta rozliczenia i księgowość
W kosztach uwzględnij processing fee, ewentualną konwersję i różnicę między kwotą klienta a kwotą księgowaną na saldo sklepu. W Hosted Checkout można konfigurować, czy opłatę ponosi kupujący, czy sprzedawca — sprawdź wpływ na prezentację ceny i dokumenty sprzedażowe. Dla kryptopłatności uwzględnij też sieć, kwotę faktycznie otrzymaną i politykę obsługi niedopłaty/nadpłaty.
Wybierz settlement currency, jeśli ta opcja jest dostępna dla gatewaya, i sprawdź kwotę netto pokazywaną przed zatwierdzeniem transakcji. Cennik zależy od kraju, metody, aktywa, waluty i konfiguracji konta. Nie deklaruj klientom jednej stawki lub gwarantowanego kursu, jeśli nie wynika to z aktualnej taryfy i ustawień Twojego gatewaya.
FAQ — Merchant API Volet
Czy Merchant API Volet przyjmuje płatności kartą?
Sprawdzona dokumentacja dla integracji sklepowej opisuje API do faktur kryptowalutowych oraz Hosted Checkout dla płatności krypto i z konta Volet. Nie zakładaj automatycznie akceptacji kart Visa/Mastercard — sprawdź metody w panelu swojego gatewaya.
Czy mogę zintegrować Volet bez własnego checkoutu?
Tak. Hosted Checkout to gotowa strona płatności Volet, a dla wspieranych platform dostępne są pluginy CMS wykorzystujące tę ścieżkę. Własny Merchant API checkout jest potrzebny, gdy chcesz budować interfejs płatności samodzielnie.
Czym różni się Hosted Checkout od Merchant API?
Hosted Checkout obsługuje stronę płatniczą i przekierowanie klienta; według dokumentacji obsługuje płatności użytkowników Volet i krypto. Merchant API pozwala budować własną płatność krypto, tworzyć faktury oraz odpytywać ich status.
Czy potrzebuję konta firmowego?
Do custodial gateway wymaga się zweryfikowanego konta Volet. Zakres funkcji oraz dokumenty zależą od typu konta, kraju i działalności; przed wdrożeniem sprawdź wymagania KYB w panelu.
Jak sprawdzić, że klient zapłacił?
Hosted Checkout: odbierz Status URL, zweryfikuj podpis i w razie potrzeby uzgodnij status przez API. API-only: backend odpytuje status faktury. Nie uznawaj za zapłacone na podstawie samego powrotu klienta na Success URL.
Kiedy zamówienie można oznaczyć jako opłacone?
Dopiero gdy zweryfikowany status płatności jest `COMPLETED` i dane transakcji pasują do oczekiwanego zamówienia. Statusy `CREATED` i `PROCESSING` pozostawiają zamówienie oczekujące.
Gdzie trzymać hasło API i Hosted Checkout?
Wyłącznie po stronie serwera, w bezpiecznej konfiguracji lub menedżerze sekretów. Nie umieszczaj sekretów w kodzie strony, JavaScript, aplikacji mobilnej ani publicznym repozytorium.
Czy WooCommerce można zintegrować wtyczką?
Volet wymienia WordPress/WooCommerce wśród obsługiwanych platform CMS. Sprawdź dostępność, wersję i zgodność wtyczki oraz przetestuj powiadomienia i statusy zamówień przed uruchomieniem.
Czy API wysyła callbacki o zmianie statusu?
W dokumentacji integracji API-only status jest sprawdzany przez API, a callbacki Status URL dotyczą Hosted Checkout. Nie mieszaj tych trybów; zaprojektuj polling dla API-only albo walidację powiadomień dla Hosted Checkout.
Podsumowanie: najpierw metoda, potem kod
Dla szybkiego wdrożenia sklepowego zacznij od Hosted Checkout lub wspieranej wtyczki. Wybierz Merchant API, jeśli chcesz własny przepływ płatności krypto i masz backend, który potrafi bezpiecznie tworzyć faktury oraz śledzić statusy. Niezależnie od wariantu przygotuj unikalne order ID, trzymaj sekrety na serwerze, weryfikuj podpisy i nie oznaczaj zamówienia jako zapłaconego na podstawie przeglądarkowego przekierowania.
Link partnerski. Dostępne metody, akceptację gatewaya i opłaty potwierdź w panelu Volet dla swojego kraju i rodzaju działalności.
Źródła i metodologia
Artykuł przygotowano 3 października 2026 r. na podstawie aktualnej dokumentacji Volet dla sprzedawców. Rozróżnia Hosted Checkout od API-only i nie zakłada obsługi kart płatniczych ani metod niewskazanych w dokumentach integracyjnych. Przed wdrożeniem sprawdź bieżącą listę obsługiwanych krajów, walut, opłat i wtyczek w koncie.
- Volet — porównanie Hosted Checkout, API, wtyczek CMS i smart contracts
- Volet — Hosted Checkout: formularz, podpis i Status URL
- Volet — Merchant API: faktury krypto, uwierzytelnianie i statusy
- Volet — tworzenie gatewaya, metody, opłaty, callbacki i zatwierdzanie
- Volet — zasady opłat i wyceny przed transakcją
- Volet — przegląd gatewayów płatniczych