Przejdź do głównej zawartości

BoxBilling

Oficjalny moduł płatności dpay.pl dla systemu BoxBilling (kompatybilny również z FOSSBilling). Umożliwia przyjmowanie płatności online za faktury. Obsługuje BLIK Level 0 (inline), karty płatnicze (inline), Apple Pay, Google Pay, PayPal, Paysafecard, raty oraz zwroty online.

Wymagania​

  • BoxBilling 4.x lub FOSSBilling
  • PHP 7.4 lub nowszy
  • Aktywne konto w Panelu dpay.pl z utworzonym Punktem Płatności

Obsługiwane metody płatności​

  • BLIK (w tym BLIK Level 0 - inline)
  • Przelewy bankowe (pay-by-link)
  • Karty płatnicze (w tym tryb inline)
  • Apple Pay
  • Google Pay
  • PayPal
  • Paysafecard
  • Raty

Obsługiwana waluta: PLN.

Instalacja​

  1. Pobierz pliki modułu ze strony dpay.pl lub z GitHuba.
  2. Skopiuj pliki do katalogu BoxBilling, zachowując strukturę katalogów: 
    bb-library/Payment/Adapter/Dpay.php
    bb-library/Payment/Adapter/Dpay/lib/dpay-sdk/
    bb-library/Payment/Adapter/Dpay/translations/
    Główne elementy:
    • Dpay.php - główny plik adaptera płatności
    • Dpay/lib/dpay-sdk/ - biblioteka SDK dpay.pl
    • Dpay/translations/ - pliki tłumaczeń (pl, en)
  3. Zaloguj się do panelu administracyjnego BoxBilling.
  4. Przejdź do Configuration > Payment gateways.
  5. Znajdź dpay.pl na liście dostępnych bramek i kliknij Install.

Konfiguracja​

Krok 1 - Przygotowanie danych w Panelu dpay.pl​

  1. Zaloguj się do Panelu dpay.pl.
  2. Przejdź do sekcji Punkty Płatności.
  3. Utwórz nowy Punkt Płatności lub wybierz istniejący.
  4. Zanotuj:
    • Nazwa serwisu (service_name) - unikalna nazwa Twojego Punktu Płatności
    • Tajny hash (secret_hash) - klucz używany do podpisywania żądań
  5. W ustawieniach Punktu Płatności ustaw adres IPN na: 
    https://twoj-boxbilling.pl/bb-ipn.php?bb_gateway_id=<ID_BRAMKI>
Ważne

Tajny hash powinien być traktowany jak hasło. Nigdy nie udostępniaj go publicznie ani nie umieszczaj w kodzie frontendowym.

Krok 2 - Konfiguracja modułu​

  1. Przejdź do Configuration > Payment gateways w panelu BoxBilling.
  2. Kliknij na bramkę dpay.pl, aby otworzyć ustawienia.
  3. Wypełnij formularz konfiguracyjny:
PoleOpis
Payment Point name (service_name)Nazwa serwisu z Panelu dpay.pl
Secret hash key (hash_key)Tajny hash z Panelu dpay.pl
Enable PayPalWłącz/wyłącz płatności PayPal
Enable credit cardsWłącz/wyłącz płatności kartą
Enable PaysafecardWłącz/wyłącz płatności Paysafecard
Enable installmentsWłącz/wyłącz płatności ratalne
Hide bank listUkryj listę banków na stronie płatności
Enable BLIK ZeroWłącz płatności BLIK Level 0 (inline, bez przekierowania)
Enable Apple PayWłącz płatności Apple Pay (SDK)
Enable Google PayWłącz płatności Google Pay (SDK)
Enable inline card paymentWłącz płatności kartą inline (SDK)
  1. Zapisz zmiany.

Krok 3 - Weryfikacja​

  1. Przejdź na stronę klienta lub utwórz testową fakturę w walucie PLN.
  2. Wybierz dpay.pl jako metodę płatności.
  3. Sprawdź, czy następuje poprawne przekierowanie na stronę płatności. Jeśli BLIK Zero lub metody SDK są włączone, powinien wyświetlić się formularz z odpowiednimi opcjami.
  4. Po dokonaniu płatności sprawdź, czy faktura w BoxBilling zmieniła status na opłaconą.

Zwroty​

Moduł obsługuje zwroty online przez API dpay.pl:

  1. Wywołaj metodę zwrotu z poziomu panelu administracyjnego lub API BoxBilling.
  2. Podaj identyfikator transakcji (transaction_id) oraz opcjonalnie kwotę zwrotu.

Obsługiwane są zarówno zwroty pełne (bez podania kwoty), jak i częściowe (z podaniem konkretnej kwoty).

Mapowanie statusów​

Status dpay.plStatus BoxBilling
Nowa transakcjaPending
completed (IPN)Complete (txn_status: complete)
Błąd podpisuOdrzucone (BAD SIGNATURE)

Rozwiązywanie problemów​

Faktury nie zmieniają statusu po płatności​

  • Sprawdź, czy adres IPN (/bb-ipn.php?bb_gateway_id=<ID>) jest prawidłowo ustawiony w Panelu dpay.pl.
  • Upewnij się, że plik bb-ipn.php jest dostępny publicznie i nie jest blokowany przez firewall lub reguły .htaccess.

Błąd waluty​

  • Moduł obsługuje wyłącznie walutę PLN. Upewnij się, że waluta faktury jest ustawiona na PLN. Przy innej walucie wyświetli się komunikat o braku obsługi.

Błąd "Service name is not configured"​

  • Upewnij się, że pole Payment Point name w konfiguracji bramki jest uzupełnione prawidłową nazwą Punktu Płatności z Panelu dpay.pl.

Płatności SDK (Apple Pay, Google Pay, karta inline) nie działają​

  • Sprawdź, czy odpowiednie opcje są ustawione na Yes w konfiguracji bramki.
  • Upewnij się, że przeglądarka klienta obsługuje wybraną metodę (Apple Pay wymaga Safari/iOS, Google Pay wymaga Chrome).
  • Skrypt SDK (dpay-iframe-sdk.js) musi być dostępny - sprawdź, czy nie jest blokowany przez Content Security Policy.

Więcej informacji​