Custom Payment Gateway

The Custom payment gateway is for manual payment methods where FOSSBilling cannot confirm the payment automatically. Common examples include bank transfers, checks, cash payments, and other offline payment workflows.

Use this gateway when clients need payment instructions and an administrator will confirm the payment manually after it is received.

Note

If you want to integrate an external payment processor with automated callbacks, see Creating a Payment Gateway instead.

How it works

1. A client selects the Custom gateway during checkout or invoice payment.
2. FOSSBilling displays the payment instructions configured for the gateway.
3. The client completes the payment outside FOSSBilling.
4. An administrator verifies the payment.
5. The administrator marks the invoice as paid and enters a transaction ID.

When the invoice is marked as paid through the Custom gateway, FOSSBilling creates and processes a transaction from the admin action.

Configure the gateway

Go to Payment Gateways in the admin area and open the Custom gateway.

The Custom gateway provides two instruction fields:

Field	Purpose
Single payment information	Instructions shown for one-time invoice payments.
Subscription information	Instructions shown for recurring or subscription payments.

You can also configure the gateway title, accepted currencies, whether one-time and subscription payments are allowed, and whether the gateway is enabled.

Template variables

Custom gateway instructions are rendered as sandboxed Twig templates. The adapter currently passes one variable:

Variable	Type	Description
invoice	object/array	Invoice details, including totals, currency, line items, and client-facing invoice information.

HTML is supported, but the rendered output is sanitized before being shown to clients.

Caution

Only trusted administrators should edit Custom gateway templates. Do not paste scripts or code from unknown sources. The template renderer is sandboxed, and unsupported Twig syntax will be rejected.

Example: Bank transfer instructions

<div>
  <h3>Bank Transfer Instructions</h3>
  <p>Please transfer the invoice total 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 after we confirm the transfer.</p>
</div>

Example: Different instructions by currency

{ percent if invoice.currency == 'EUR' percent }
  <p>Transfer to IBAN: DE00 0000 0000 0000 0000 00</p>
{ percent elseif invoice.currency == 'USD' percent }
  <p>Transfer to account 1234567890, routing 021000021.</p>
{ percent else percent }
  <p>Contact support for {{ invoice.currency }} payment instructions.</p>
{ percent endif percent }

Replace { percent with {% and percent } with %} when adding the template in FOSSBilling.

Supported template syntax

Custom gateway templates use a restricted Twig environment. Basic output, conditionals, loops, simple variables, and common formatting filters are supported.

Do not use advanced Twig features such as importing templates, including templates, calling API globals, or debugging helpers like dump(). If a template contains unsupported syntax, FOSSBilling will show a configuration or rendering error instead of rendering unsafe output.

Mark an invoice as paid

After confirming the payment:

1. Go to Invoicing → Invoices.
2. Open the relevant invoice.
3. Use Mark as paid.
4. Select the Custom gateway if needed.
5. Enter a transaction ID or payment reference.
6. Choose whether FOSSBilling should execute the related invoice tasks.

The transaction ID is required when marking an invoice as paid through the Custom gateway.

Troubleshooting

If the payment instructions do not render:

• Check that the Custom gateway is enabled.
• Confirm the gateway allows the payment type being attempted.
• Check that the invoice currency is accepted by the gateway, or leave accepted currencies empty to allow all currencies.
• Review the template for unsupported Twig syntax.
• Avoid dump(), API globals, template imports, includes, and other advanced Twig features.