The “Custom” payment gateway

The “Custom” payment gateway is a built-in adapter in FOSSBilling that acts as a generic, manually-processed payment method. Unlike external gateways such as Stripe or PayPal, the Custom gateway does not connect to any payment processor. Instead, it displays configurable instructions to your client so you can handle transactions manually (e.g., bank transfers, cash payments, or other offline methods).

If you are looking to build your own payment gateway that integrates with an external payment provider, see the Creating a Payment Gateway guide instead.

How It Works

When a client selects the Custom payment gateway to pay an invoice, FOSSBilling renders the text you have configured in the admin panel. This text can contain:

• Payment instructions (e.g., bank account details, payment reference numbers)
• Invoice data rendered dynamically using Twig template syntax
• HTML and JavaScript for custom formatting or behavior

After the client follows your instructions and you confirm the payment, an admin can manually mark the invoice as paid from the admin panel.

Configuration

Navigate to Configuration > Payment gateways and click on the Custom gateway. You will see two text fields:

• Single payment information — Displayed when the client is making a one-time payment.
• Subscription information — Displayed when the client is setting up a recurring payment.

Both fields support Twig templates and HTML.

Templates

The Custom gateway templates are rendered using Twig and have access to the same filters and functions available throughout FOSSBilling.

Available Variables

The following variables are available in your Custom gateway templates:

Example: Display Payment Instructions with Invoice Details

<div style="padding: 20px; border: 1px solid #ddd; border-radius: 8px;">
    <h3>Bank Transfer Instructions</h3>
    <p>Please transfer the following amount to our bank account:</p>
    <ul>
        <li><strong>Amount:</strong> {{ invoice.total }} {{ invoice.currency }}</li>
        <li><strong>Reference:</strong> {{ invoice.serie_nr }}</li>
        <li><strong>Bank:</strong> Example Bank</li>
        <li><strong>IBAN:</strong> GB00 XXXX 0000 0000 0000 00</li>
        <li><strong>BIC/SWIFT:</strong> EXAMPLEXX</li>
    </ul>
    <p>Your invoice will be marked as paid once we confirm the transfer. This may take 1-3 business days.</p>
</div>

Debugging: Inspecting Available Data

To see all the data available in the invoice variable, temporarily enable Twig debug mode in your config.php file and add the following to your template:

<pre>
    {{ dump(invoice) }}
</pre>

This will print the full invoice data structure, showing all available fields you can use in your template. Be sure to disable Twig debug mode when you are done.

Example: Display a Different Message Based on Currency

{% if invoice.currency == 'EUR' %}
    <p>Please transfer to our European bank account: DE00 0000 0000 0000 0000 00</p>
{% elseif invoice.currency == 'USD' %}
    <p>Please transfer to our US bank account: 1234567890 (Routing: 021000021)</p>
{% else %}
    <p>Please contact support for payment instructions in {{ invoice.currency }}.</p>
{% endif %}

Marking Invoices as Paid

After a client follows the payment instructions and you confirm receipt of the funds:

1. Navigate to Invoicing > Invoices in the admin panel.
2. Find the relevant invoice and open it.
3. Click “Mark as paid” to complete the transaction.

This will update the invoice status, activate any associated services (like hosting accounts), and send a payment confirmation email to the client.

Source Code

The Custom adapter source code is located at src/library/Payment/Adapter/Custom.php. It is one of the simplest adapters in the codebase and serves as a good starting point if you want to understand how payment adapters work before building your own.