CashBill — jak działa: integracje i zwroty

CashBill API pozwala wdrożyć płatności bezpośrednio w serwisie, również w modelu white-label – pod własną marką.¹ W tym poradniku wyjaśniamy, kiedy wybrać API zamiast integracji z platformą sklepową. Omawiamy też statusy płatności, zwroty i błędy, które trzeba obsłużyć po wdrożeniu.

Czym jest CashBill i jak działa jego API?

CashBill API umożliwia komunikację serwisu z rozwiązaniami operatora. CashBill udostępnia dokumentację ich wdrożenia oraz API do obsługi kodów dostępowych w usłudze SMS Kod Automatyczny.¹ Płatności i kody obsługuje się oddzielnie. W obu procesach serwis musi przypisać odpowiedź API do właściwej operacji.

W modelu white-label klient widzi usługę pod marką firmy, która ją wdrożyła. Ta firma odpowiada za wygląd ścieżki użytkownika. Integracja przekazuje żądania do CashBill i obsługuje odpowiedzi operatora. Łatwiej dzięki temu rozdzielić prace nad interfejsem od prac nad połączeniem z API.

Jakie dane i sposoby uwierzytelniania są potrzebne w API CashBill?

Integrator powinien oddzielić dane identyfikujące operację od danych autoryzujących żądanie. Pola i sposób uwierzytelniania zależą od usługi, więc płatności i kody dostępowe potrzebują osobnych konfiguracji. Błędny podpis żądania może spowodować odpowiedź HTTP 401 Unauthorized.

• Dane operacji wskazują, którego żądania dotyczy odpowiedź API CashBill. Integrator wiąże ją z właściwą operacją w swoim systemie.
• Dane uwierzytelniające służą do autoryzacji komunikacji z API CashBill. Należy przechowywać je na serwerze, poza kodem dostępnym w przeglądarce.
• Konfiguracja usługi rozdziela płatności od kodów dostępowych SMS Kod Automatyczny. Każdy proces wymaga właściwych dla niego parametrów.

Co powoduje błędy komunikacji z API CashBill?

Błędy komunikacji z API CashBill mogą wynikać z wadliwego żądania, nieudanego uwierzytelnienia lub zerwania połączenia HTTP między serwerami. Przy diagnozowaniu problemu warto zestawić wysłane parametry z odpowiedzią serwera i zapisem błędu w serwisie. Samo zerwanie połączenia nie mówi, czy operacja się powiodła. Nie powinno więc zmieniać statusu płatności ani powodować wydania kodu dostępowego. Nieprawidłowy podpis żądania skutkuje odpowiedzią HTTP 401 Unauthorized².

Co oznacza dla CashBill status Krajowej Instytucji Płatniczej?

Status Krajowej Instytucji Płatniczej oznacza, że operator działa jako instytucja płatnicza pod nadzorem Komisji Nadzoru Finansowego. Dotyczy to operatora usług płatniczych, a nie sposobu uwierzytelniania żądań API. Integrator nadal odpowiada za poprawną autoryzację, obsługę odpowiedzi HTTP 401 i reakcję na błędy².

Jak zintegrować API CashBill i obsługiwać płatności?

CashBill API służy do indywidualnego połączenia z płatnościami. Sklepy działające na platformach e-commerce mogą też korzystać z gotowych wtyczek.³ Orientacyjny czas rejestracji w CashBill wynosi 5 minut.³ Rejestracja nie kończy jednak wdrożenia: serwis musi utworzyć płatność, zapisać jej identyfikator i powiązać wynik z zamówieniem.

• Utworzenie płatności rozpoczyna jej obsługę w serwisie. System zapisuje identyfikator, który pozwoli później odczytać wynik.
• Odczyt danych płatności pozwala przypisać wynik do zamówienia. System aktualizuje zamówienie na podstawie danych dotyczących tej samej transakcji.
• Obsługa błędu oddziela problem z komunikacją od wyniku płatności. Samo wysłanie żądania nie wystarcza, by oznaczyć zamówienie jako opłacone.

Jak sprawdzić przez API CashBill, czy transakcja została opłacona?

Wynik płatności można sprawdzić przez API: pobrać jej dane i porównać identyfikator z zapisanym przy zamówieniu. Nieoficjalna biblioteka Legible Cashbill to nakładka na REST API CashBill, napisana w TypeScript dla środowiska Node.js.⁴ Jej przykłady obejmują tworzenie płatności, pobieranie ich danych i obsługę powiadomień.⁴ Dane płatności pobiera się żądaniem GET z identyfikatorem punktu płatności oraz transakcji⁵.

• Identyfikator płatności łączy odpowiedź API z zamówieniem. Zapisz go podczas tworzenia płatności.
• Informacja o płatności stanowi podstawę aktualizacji zamówienia. Pobierz ją dla zapisanego identyfikatora i odczytaj wynik operacji.
• Status zamówienia powinien odpowiadać wynikowi płatności. Zmień go dopiero po dopasowaniu odpowiedzi do właściwego zamówienia.

Jak przetestować integrację przed uruchomieniem płatności na żywo?

Test integracji CashBill powinien objąć drogę od utworzenia płatności do aktualizacji zamówienia. Sprawdź wynik opłacony, nieopłacony oraz błąd komunikacji. Dla zamówienia testowego zapisz identyfikator płatności, pobierz jej dane i porównaj wynik ze statusem zamówienia. Odczytaj tę samą płatność ponownie, by upewnić się, że serwis nie zapisze sprzecznego wyniku. Dokumentacja API wymienia osiem statusów transakcji, które warto uwzględnić w scenariuszach testowych⁶.

Czy CashBill można podłączyć do WooCommerce, PrestaShop, Shopify i innych platform?

CashBill można podłączyć przez wtyczkę sklepową albo własną integrację z API. W przypadku WooCommerce, PrestaShop, Shopify i Magento wybór zależy od sposobu obsługi zamówień oraz możliwości utrzymania własnego kodu. Spośród czterech wymienionych platform CashBill przedstawia gotowe integracje dla trzech: WooCommerce, PrestaShop i Magento⁷.

Tabela porównuje wtyczkę z indywidualną integracją API pod kątem prac, które musi wykonać sklep.

Dane w tabeli: 8

Wtyczka CashBill pasuje do sklepu, który woli gotowy moduł, jeśli obsługuje on potrzebny zakres zamówień.

Indywidualna integracja API pasuje do sklepu z własnym procesem zamówień i możliwością utrzymania kodu połączenia. Według opisu wtyczki moduł CashBill przetestowano z WooCommerce 7.0 i nowszymi wersjami⁸.

Powiadomienia zwrotne CashBill: konfiguracja i obsługa statusów płatności

CashBill automatycznie przekazuje sprzedawcy informacje o transakcjach; serwis powinien przypisać każdą z nich do właściwego zamówienia.³ Powiadomienie zwrotne przekazuje systemowi sklepu wynik operacji. Sam powrót klienta na stronę sklepu nie zastępuje odbioru tego komunikatu.

Do obsługi powiadomień CashBill serwis potrzebuje adresu odbiorczego, identyfikatora płatności przy zamówieniu i reguły zmiany statusu. Komunikat powinien trafić do kodu działającego na serwerze, a nie opierać się na danych widocznych w przeglądarce klienta. Odbiór potwierdza odpowiedź HTTP 200 OK, której treść stanowią dwa bajty „OK”⁹.

• Adres odbiorczy CashBill kieruje powiadomienie do systemu sklepu. Skonfiguruj go według dokumentacji używanej integracji.
• Identyfikator transakcji łączy komunikat z zamówieniem. Znajdź po nim zamówienie przed zmianą statusu.
• Weryfikacja komunikatu zapobiega zmianie statusu na podstawie nieuprawnionego żądania. Zastosuj sposób weryfikacji właściwy dla używanego interfejsu CashBill.
• Aktualizacja statusu zapisuje wynik przy odpowiednim zamówieniu. Jeśli ten sam komunikat nadejdzie ponownie, nie powtarzaj czynności zależnych od płatności.

Legible Cashbill może pomóc aplikacji Node.js odebrać powiadomienie. Kod aplikacji nadal musi jednak powiązać je z zamówieniem i zapisać wynik. Test odbioru powinien objąć poprawny komunikat, komunikat bez przypisanego zamówienia i ponowne dostarczenie tego samego wyniku⁴.

Status zamówienia należy zmienić dopiero po weryfikacji powiadomienia i dopasowaniu transakcji. Potwierdzonemu przekazaniu środków odpowiada końcowy status transakcji „PositiveFinish”⁶.

Metody płatności CashBill, koszty i bezpieczeństwo

Metody płatności CashBill mają różne prowizje, a koszt zależy także od warunków rejestracji. Standardowa prowizja od transakcji online wynosi 1,5%.³ Poniższa tabela pokazuje inne stawki: dotyczą rejestracji przez link CashFix.

Tabela zestawia prowizje metod płatności CashBill przy rejestracji przez link CashFix. W tych warunkach prowizja za BLIK wynosi 1,2%³.

Dane w tabeli: 3

Przelew natychmiastowy i BLIK pozwalają opłacić pojedynczy zakup, a płatności cykliczne BLIK dotyczą powtarzających się należności. Paysafecard to osobna metoda, której prowizję trzeba uwzględnić w kosztach sprzedaży. Wybór metod powinien wynikać ze sposobu płacenia klientów i charakteru zakupów. W cenniku CashFix prowizja Paysafecard wynosi 14%: to o 12,8 punktu procentowego więcej niż prowizja BLIK wynosząca 1,2%³.

Jakie są zalety i ograniczenia szybkich płatności CashBill?

Szybkie płatności CashBill obejmują przelewy natychmiastowe i BLIK. Szybkie opłacenie zakupu nie oznacza jednak, że sprzedawca dostanie środki w tej samej chwili. Typowy termin wypłaty po jej zleceniu to następny dzień roboczy.³ CashBill nie pobiera opłat za wypłaty ani zwroty środków: w obu przypadkach opłata wynosi 0 zł.^3,10

Zwrot pieniędzy przez CashBill to nie to samo co zwrot towaru. Opłata operatora wynosząca 0 zł za zwrot środków nie przesądza o zasadach przyjęcia zwrotu zamówienia. Sprzedawca musi powiązać zwracaną płatność z właściwą transakcją i zamówieniem.

Czy CashBill oferuje płatności odroczone?

W podanych stawkach CashBill uwzględnia PayPo, BLIK Płacę Później i Twisto. Płatność odroczona pozwala klientowi zapłacić za zakup później. Sprzedawca powinien przy tym porównać nie tylko prowizję procentową, ale też ewentualną opłatę za każdą transakcję.

Tabela porównuje prowizję i dodatkową opłatę 3 metod płatności odroczonych CashBill przy rejestracji przez link CashFix.

Dane w tabeli: 3

Znak „ – ” oznacza, że w podanych stawkach nie określono dodatkowej opłaty za transakcję dla danej metody.

Przy PayPo do prowizji procentowej dochodzi opłata kwotowa za każdą transakcję. Porównanie samych prowizji nie pokaże więc pełnej różnicy kosztów.

PayPo nie pasuje do sprzedawcy, który chce oceniać koszt wyłącznie według prowizji procentowej.

BLIK Płacę Później pasuje do sklepu, którego klienci wybierają odroczoną płatność BLIK.

Twisto warto rozważyć dla klientów korzystających z tej usługi, lecz nie jako zamiennik każdej metody odroczonej.

Metody CashBill najlepiej dobierać do sposobu płacenia klientów i pełnego kosztu obsługi transakcji.

Ceny i warunki sprawdzone u źródeł: październik 2026.