Skip to main content

BoxBilling

Official dpay.pl payment module for BoxBilling (also compatible with FOSSBilling). Enables online payment acceptance for invoices. Supports BLIK Level 0 (inline), credit/debit cards (inline), Apple Pay, Google Pay, PayPal, Paysafecard, installments, and online refunds.

Requirements​

  • BoxBilling 4.x or FOSSBilling
  • PHP 7.4 or newer
  • An active account in the dpay.pl Dashboard with a configured Payment Point

Supported Payment Methods​

  • BLIK (including BLIK Level 0 - inline)
  • Bank transfers (pay-by-link)
  • Credit/debit cards (including inline mode)
  • Apple Pay
  • Google Pay
  • PayPal
  • Paysafecard
  • Installments

Supported currency: PLN.

Installation​

  1. Download the module files from dpay.pl or GitHub.
  2. Copy the files to the BoxBilling directory, preserving the directory structure: 
    bb-library/Payment/Adapter/Dpay.php
    bb-library/Payment/Adapter/Dpay/lib/dpay-sdk/
    bb-library/Payment/Adapter/Dpay/translations/
    Main components:
    • Dpay.php - main payment adapter file
    • Dpay/lib/dpay-sdk/ - dpay.pl SDK library
    • Dpay/translations/ - translation files (pl, en)
  3. Log in to the BoxBilling admin panel.
  4. Go to Configuration > Payment gateways.
  5. Find dpay.pl on the list of available gateways and click Install.

Configuration​

Step 1 - Prepare credentials in the dpay.pl Dashboard​

  1. Log in to the dpay.pl Dashboard.
  2. Go to the Payment Points section.
  3. Create a new Payment Point or select an existing one.
  4. Note down:
    • Service name (service_name) - the unique name of your Payment Point
    • Secret hash (secret_hash) - the key used to sign requests
  5. In the Payment Point settings, set the IPN URL to: 
    https://your-boxbilling.com/bb-ipn.php?bb_gateway_id=<GATEWAY_ID>
Important

The secret hash should be treated like a password. Never share it publicly or include it in frontend code.

Step 2 - Configure the module​

  1. Go to Configuration > Payment gateways in the BoxBilling admin panel.
  2. Click on the dpay.pl gateway to open its settings.
  3. Fill in the configuration form:
FieldDescription
Payment Point name (service_name)Service name from the dpay.pl Dashboard
Secret hash key (hash_key)Secret hash from the dpay.pl Dashboard
Enable PayPalEnable/disable PayPal payments
Enable credit cardsEnable/disable card payments
Enable PaysafecardEnable/disable Paysafecard payments
Enable installmentsEnable/disable installment payments
Hide bank listHide the bank list on the payment page
Enable BLIK ZeroEnable BLIK Level 0 payments (inline, no redirect)
Enable Apple PayEnable Apple Pay payments (SDK)
Enable Google PayEnable Google Pay payments (SDK)
Enable inline card paymentEnable inline card payments (SDK)
  1. Save the changes.

Step 3 - Verification​

  1. Go to the client area or create a test invoice in PLN currency.
  2. Select dpay.pl as the payment method.
  3. Verify that you are correctly redirected to the payment page. If BLIK Zero or SDK methods are enabled, a form with the appropriate options should be displayed.
  4. After completing the payment, verify that the invoice in BoxBilling has changed to paid status.

Refunds​

The module supports online refunds via the dpay.pl API:

  1. Trigger the refund method from the admin panel or the BoxBilling API.
  2. Provide the transaction identifier (transaction_id) and optionally the refund amount.

Both full refunds (without specifying an amount) and partial refunds (with a specific amount) are supported.

Status Mapping​

dpay.pl StatusBoxBilling Status
New transactionPending
completed (IPN)Complete (txn_status: complete)
Signature errorRejected (BAD SIGNATURE)

Troubleshooting​

Invoices do not change status after payment​

  • Verify that the IPN URL (/bb-ipn.php?bb_gateway_id=<ID>) is correctly configured in the dpay.pl Dashboard.
  • Make sure the bb-ipn.php file is publicly accessible and not blocked by a firewall or .htaccess rules.

Currency error​

  • The module supports PLN currency only. Make sure the invoice currency is set to PLN. A different currency will display an unsupported currency message.

Error "Service name is not configured"​

  • Make sure the Payment Point name field in the gateway configuration contains a valid Payment Point name from the dpay.pl Dashboard.

SDK payments (Apple Pay, Google Pay, inline card) do not work​

  • Verify that the corresponding options are set to Yes in the gateway configuration.
  • Make sure the customer's browser supports the selected method (Apple Pay requires Safari/iOS, Google Pay requires Chrome).
  • The SDK script (dpay-iframe-sdk.js) must be accessible - check that it is not blocked by Content Security Policy.

More Information​