Connect FOSSBilling

The Payfim adapter adds a Pay with Crypto option to FOSSBilling invoices. Payments are verified with your own Payfim Gateway and the invoice is marked paid automatically.

Before you start, install your Payfim Gateway and add your wallets (see Install the gateway and Add wallets). Compatibility: FOSSBilling 0.6 – 0.8 · PHP 8.1 – 8.4.

1. Upload the adapter.

   Unzip payfim-fossbilling.zip and upload the contents of the upload/ folder to your FOSSBilling root. This adds library/Payment/Adapter/Payfim.php and its logo.

   In the admin area open System → Payment Gateways, click New Payment Gateway and click the gear icon next to Payfim to install it.

   

2. Enter your gateway details.

   Open the new gateway. Set the Payment Gateway Title (e.g. Pay with Crypto), paste your Payfim Gateway URL and API key from Payfim dashboard → Integrations, tick Enabled and Allow One Time Payments, then click Update Gateway.

   

   Tip: On FOSSBilling 0.8.2 and newer, when you save the gateway as Enabled, FOSSBilling runs a connection test against your Payfim gateway. A wrong URL or key is reported right away and nothing is saved.

3. What your clients see.

   On an unpaid invoice the client picks the Payfim logo, clicks Pay Now and is sent to your secure crypto checkout. The Payfim invoice is created on the server from the invoice total, so the amount can't be changed in the browser.

   

4. Automatic payment confirmation.

   When the payment is confirmed on the blockchain, Payfim sends a signed webhook to ipn.php. The adapter verifies the signature, re-checks the invoice with your gateway, adds the funds and marks the invoice Paid. The transaction ID is the blockchain transaction hash, so a payment is never recorded twice.

   Underpaid payments are stored as a transaction with the note Only X of Y received and the invoice stays unpaid for you to review.

   

Troubleshooting

Save shows "Payfim connection test failed"

Check the Gateway URL (no trailing path) and that the API key starts with pf_live_. The FOSSBilling server must be able to reach the gateway.

Payfim is not listed under Available Adapters

Make sure Payfim.php is in library/Payment/Adapter/ (case-sensitive).

Webhook never arrives / invoice stays unpaid

Your billing site must be reachable from the Payfim gateway server over HTTPS. Check Webhooks in the Payfim dashboard for the delivery log and HTTP status; failed deliveries are retried automatically for 24 hours.

Get the FOSSBilling Crypto Payment Gateway - the download includes an illustrated PDF version of this guide.