FOSSBilling

https://fossbilling.org/docs
Admin
FOSSBilling is a free and open-source billing and client management solution that helps digital...
Tokens:41,599
Snippets:369
Trust Score:9.2
Update:6 months ago
Show doc for...
Tokens:
Raw
### Configure NGINX for FOSSBilling

Source: https://fossbilling.org/docs/getting-started/installation

An example NGINX server block configuration for FOSSBilling. It includes SSL settings, security rules to block access to sensitive files, and PHP-FPM integration.

```nginx
server {
	listen 80;
	server_name %%DOMAIN%%
	return 301 https://%%DOMAIN%%/request_uri/;
}

server {
	listen 443 ssl http2;
	ssl_certificate      /path/to/ssl/certicate.crt;
	ssl_certificate_key  /path/to/ssl/certicate.key;
	ssl_stapling on;
	ssl_stapling_verify on;

	set $root_path '%%SOURCE_PATH%%';
	server_name %%DOMAIN%%;

	index index.php;
	root $root_path;
	try_files $uri $uri/ @rewrite;
	sendfile off;
	include /etc/nginx/mime.types;

	# Block access to sensitive files
	location ~* .(ini|sh|inc|bak|twig|sql)$ {
		return 403;
	}

	# Block /vendor completely
	location ^~ /vendor/ {
		return 403;
	}
	
	# Block direct access to config.php
	location = /config.php {
		return 403;
	}

	# Block access to hidden files except .well-known
	location ~ /\.(?!well-known\/) {
		return 403;
	}

	# Disable PHP execution in /uploads
	location ~* /uploads/.*\.php$ {
		return 403;
	}

	# Deny access to /data, except /assets/gateways
	location ~* /data/(?!(assets/gateways/)) {
		return 403;
	}

	location @rewrite {
		rewrite ^/page/(.*)$ /index.php?_url=/custompages/$1;
		rewrite ^/(.*)$ /index.php?_url=/$1;
	}

	location ~ \.php {
		fastcgi_split_path_info ^(.+\.php)(/.+)$;
		fastcgi_pass unix:/run/php/phpx.x-fpm.sock;
		fastcgi_param PATH_INFO       $fastcgi_path_info;
		fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
		fastcgi_intercept_errors on;
		include fastcgi_params;
	}

	location ~* ^/(css|img|js|flv|swf|download)/(.+)$ {
		root $root_path;
		expires off;
	}
}
```

--------------------------------

### Build Front-End Assets for FOSSBilling

Source: https://fossbilling.org/docs/getting-started/building

Compiles and builds the front-end assets (like CSS, JavaScript) for FOSSBilling using NPM scripts. This command should be run after installing NPM dependencies.

```bash
npm run build
```

--------------------------------

### Display Payment Instructions with Invoice Details

Source: https://fossbilling.org/docs/developing-fossbilling/guides/custom-gateway

An example of using HTML and Twig variables to present bank transfer details and invoice information to the client.

```html
<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>
```

--------------------------------

### Install NPM Dependencies for FOSSBilling

Source: https://fossbilling.org/docs/getting-started/building

Installs the necessary Node Package Manager (NPM) dependencies required for building the front-end assets of FOSSBilling. Ensure Node.js and NPM are installed and up-to-date.

```bash
npm i
```

--------------------------------

### Install Composer Dependencies for FOSSBilling

Source: https://fossbilling.org/docs/getting-started/building

Installs the PHP dependencies managed by Composer for the FOSSBilling project. This step requires Composer to be installed on your system.

```bash
composer install
```

--------------------------------

### API Call with CSRF Token

Source: https://fossbilling.org/docs/developing-fossbilling/guides/creating-a-theme

This example shows how to append the CSRF token to an API call URL, supporting both GET and POST methods. The token is crucial for authenticated API interactions.

```html
href="{{ 'api/admin/client/group_delete'|link({ 'id': group.id, 'CSRFToken': CSRFToken }) }}"
```

--------------------------------

### Run FOSSBilling Standalone Container

Source: https://fossbilling.org/docs/getting-started/docker

Deploys a single FOSSBilling container with a persistent volume. This method requires an external database connection during the web installer phase.

```bash
docker run -d -p 80:80 -v=fossbilling:/var/www/html --restart=always fossbilling/fossbilling:latest
```

--------------------------------

### Implement Cron Hooks in FOSSBilling Module

Source: https://fossbilling.org/docs/developing-fossbilling/guides/creating-a-module

Demonstrates how to hook into the FOSSBilling cron process to execute custom logic. This example logs a message whenever the 'onBeforeAdminCronRun' event is triggered.

```PHP
public static function onBeforeAdminCronRun(\Box_Event $event): void
{
    error_log('Cron was called!');
}
```

--------------------------------

### Admin: Get Available License Plugins

Source: https://fossbilling.org/docs/product-types/license

Retrieves a list of all available license validation plugins that can be used with the license product type.

```APIDOC
## GET /admin/servicelicense/plugin_get_pairs

### Description
Returns a list of available license plugins for administrators.

### Method
GET

### Endpoint
/admin/servicelicense/plugin_get_pairs

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **result** (object) - An object where keys are plugin names and values are their display names.
- **error** (null) - Indicates no error occurred.

#### Response Example
```json
{
    "result": {
        "Simple": "Simple",
        "PluginB": "PluginB"
    },
    "error": null
}
```
```

--------------------------------

### Making API Requests with the Wrapper

Source: https://fossbilling.org/docs/developing-fossbilling/javascript

Demonstrates how to perform GET and POST requests using the API wrapper. It supports endpoint types (admin, client, guest) and includes parameters for success and error handling.

```javascript
// GET request example
API.guest.get("system/version", {}, function(response) {
  // handle successful response
}, function(error) {
  // handle error response
});

// POST request example
API.admin.post("client/get_list", {}, function(response) {
  // handle successful response
}, function(error) {
  // handle error response
});
```

--------------------------------

### GET /guest/serviceapikey/get_info

Source: https://fossbilling.org/docs/product-types/apikeys

Retrieves information about an API key, including its validity and any associated custom parameters.

```APIDOC
## GET /guest/serviceapikey/get_info

### Description
Returns the validity status and custom parameters associated with a specific API key.

### Method
GET

### Endpoint
/guest/serviceapikey/get_info

### Parameters
#### Query Parameters
- **api_key** (string) - Required - The API key to query.

### Response
#### Success Response (200)
- **valid** (boolean) - Whether the key is active.
- **custom_parameters** (object) - Key-value pairs defined for this specific API key.
```

--------------------------------

### Accessing Client API Endpoint in Twig

Source: https://fossbilling.org/docs/developing-fossbilling/guides/creating-a-theme

This example shows how to retrieve a list of invoices for the currently authenticated client using the 'client' function in a Twig template. This is available only for authenticated client users.

```twig
{{ client.invoice_get_list }}
```

--------------------------------

### Deploy FOSSBilling with Docker Compose

Source: https://fossbilling.org/docs/getting-started/docker

Orchestrates FOSSBilling and a MySQL database container using a YAML configuration. This approach provides a ready-to-use environment with pre-configured database settings.

```yaml
version: "3.9"
services:
  fossbilling:
    image: fossbilling/fossbilling:latest
    restart: always
    ports:
      - 80:80
    volumes:
      - fossbilling:/var/www/html
  mysql:
    image: mysql:8.2
    restart: always
    environment:
      MYSQL_DATABASE: fossbilling
      MYSQL_USER: fossbilling
      MYSQL_PASSWORD: fossbilling
      MYSQL_RANDOM_ROOT_PASSWORD: '1'
    volumes:
      - mysql:/var/lib/mysql
volumes:
  fossbilling:
  mysql:
```

--------------------------------

### Passing Parameters to Admin API via Twig

Source: https://fossbilling.org/docs/developing-fossbilling/guides/creating-a-theme

This example shows how to pass parameters to an admin API endpoint using an array in Twig. It retrieves the configuration for the 'mod_seo' extension.

```twig
{{ admin.extension_config_get({ "ext": "mod_seo" }) }}
```

--------------------------------

### Get Available License Plugins (FOSSBilling API)

Source: https://fossbilling.org/docs/product-types/license

Retrieves a list of available license validation plugins from the FOSSBilling system. This is useful for administrators to see which licensing strategies can be applied.

```json
{
    "result": {
        "Simple": "Simple",
        "PluginB": "PluginB"
    },
    "error": null
}
```

--------------------------------

### ExamplePay Payment Adapter Implementation in PHP

Source: https://fossbilling.org/docs/developing-fossbilling/guides/creating-a-payment-gateway

This PHP class implements the FOSSBilling payment adapter interface for ExamplePay. It handles configuration validation, setting up dependency injection, and defining gateway capabilities. The adapter supports one-time payments and generates a redirect form for the client to complete the payment process. It requires merchant credentials and supports both live and test modes.

```php
<?php

/**
 * ExamplePay payment adapter for FOSSBilling.
 *
 * This is a fictional example demonstrating all the required methods
 * and best practices for building a payment gateway adapter.
 */
class Payment_Adapter_ExamplePay implements FOSSBilling\InjectionAwareInterface
{
    protected ?Pimple\Container $di = null;

    public function __construct(private $config)
    {
        // Validate configuration based on test mode
        if ($this->config['test_mode']) {
            if (empty($this->config['test_merchant_id'])) {
                throw new Payment_Exception(
                    'The ":pay_gateway" payment gateway is not fully configured. Please configure the :missing',
                    [':pay_gateway' => 'ExamplePay', ':missing' => 'Test Merchant ID'],
                    4001
                );
            }
        } else {
            if (empty($this->config['merchant_id'])) {
                throw new Payment_Exception(
                    'The ":pay_gateway" payment gateway is not fully configured. Please configure the :missing',
                    [':pay_gateway' => 'ExamplePay', ':missing' => 'Merchant ID'],
                    4001
                );
            }
            if (empty($this->config['secret_key'])) {
                throw new Payment_Exception(
                    'The ":pay_gateway" payment gateway is not fully configured. Please configure the :missing',
                    [':pay_gateway' => 'ExamplePay', ':missing' => 'Secret Key'],
                    4001
                );
            }
        }
    }

    public function setDi(Pimple\Container $di): void
    {
        $this->di = $di;
    }

    public function getDi(): ?Pimple\Container
    {
        return $this->di;
    }

    /**
     * Gateway configuration: capabilities, description, and admin form fields.
     */
    public static function getConfig(): array
    {
        return [
            'supports_one_time_payments' => true,
            'supports_subscriptions'     => false,
            'can_load_in_iframe'         => false,
            'description'                => 'Accept payments via ExamplePay. Enter your merchant credentials to get started.',
            'logo' => [
                'logo'   => 'examplepay.png',
                'height' => '30px',
                'width'  => '80px',
            ],
            'form' => [
                'merchant_id' => [
                    'text', [
                        'label' => 'Live Merchant ID:',
                    ],
                ],
                'secret_key' => [
                    'text', [
                        'label' => 'Live Secret Key:',
                    ],
                ],
                'test_merchant_id' => [
                    'text', [
                        'label' => 'Test Merchant ID:',
                        'required' => false,
                    ],
                ],
            ],
        ];
    }

    /**
     * Generate the payment form shown to the client.
     */
    public function getHtml($api_admin, $invoice_id, $subscription): string
    {
        $invoice = $api_admin->invoice_get(['id' => $invoice_id]);

        $merchantId = $this->config['test_mode']
            ? $this->config['test_merchant_id']
            : $this->config['merchant_id'];

        $amount = number_format($invoice['total'], 2, '.', '');

        $fields = [
            'merchant_id'   => $merchantId,
            'amount'        => $amount,
            'currency'      => $invoice['currency'],
            'description'   => 'Payment for invoice ' . $invoice['serie_nr'],
            'reference'     => $invoice['id'],
            'callback_url'  => $this->config['notify_url'],
            'success_url'   => $this->config['thankyou_url'],
            'cancel_url'    => $this->config['cancel_url'],
            'customer_email'=> $invoice['buyer']['email'],
        ];

        // Build a hidden form that redirects to ExamplePay's checkout page
        $gatewayUrl = $this->config['test_mode']
            ? 'https://sandbox.examplepay.com/checkout'
            : 'https://checkout.examplepay.com/pay';

        $form = '<form name="payment_form" action="' . $gatewayUrl . '" method="post">' . PHP_EOL;
        foreach ($fields as $key => $value) {
            $form .= sprintf('<input type="hidden" name="%s" value="%s" />', htmlspecialchars($key), htmlspecialchars((string) $value)) . PHP_EOL;
        }
        $form .= '<input class="btn btn-primary" type="submit" value="Pay with ExamplePay" id="payment_button" />' . PHP_EOL;
        $form .= '</form>' . PHP_EOL;

        // Auto-redirect if configured
        if (!empty($this->config['auto_redirect'])) {
            $form .= "<script>document.addEventListener('DOMContentLoaded', function() {

```

--------------------------------

### Accessing FOSSBilling DI Services

Source: https://fossbilling.org/docs/developing-fossbilling/guides/creating-a-payment-gateway

Demonstrates how to interact with the DI container to load database models, execute raw SQL, access module-specific services, and utilize utility tools like the logger and URL generator.

```php
// Load a database model by ID
$invoice = $this->di['db']->load('Invoice', $invoice_id);
$invoice = $this->di['db']->getExistingModelById('Invoice', $invoice_id);
 
// Find a model with conditions
$gateway = $this->di['db']->findOne('PayGateway', 'gateway = ?', ['MyGateway']);
 
// Run raw SQL
$rows = $this->di['db']->getAll('SELECT * FROM transaction WHERE txn_id = :txn_id', [':txn_id' => $txnId]);
 
// Access module services
$invoiceService = $this->di['mod_service']('Invoice');
$clientService  = $this->di['mod_service']('Client');
$systemService  = $this->di['mod_service']('System');
$payGwService   = $this->di['mod_service']('Invoice', 'PayGateway');
 
// Common service methods
$invoiceService->getTotalWithTax($invoiceModel);
$invoiceService->payInvoiceWithCredits($invoiceModel);
$invoiceService->isInvoiceTypeDeposit($invoiceModel);
$invoiceService->markAsPaid($invoiceModel, true, true);
$clientService->addFunds($client, $amount, $description, $extraData);
 
// Utility: generate a URL
$url = $this->di['tools']->url('/invoice/' . $invoiceModel->hash);
 
// Logger
$this->di['logger']->info('MyGateway: Payment processed for invoice #%s', $invoice->id);
```

--------------------------------

### NGINX Configuration Snippet

Source: https://fossbilling.org/docs/troubleshooting

This NGINX configuration block is a common setup for serving PHP applications like FOSSBilling. It ensures that requests for existing files are served directly, while other requests are passed to the PHP FastCGI process manager.

```nginx
location / {
    try_files $uri $uri/ /index.php?/$request_uri;
}

location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
}
```

--------------------------------

### Create and Update FOSSBilling Subscriptions (PHP)

Source: https://fossbilling.org/docs/developing-fossbilling/guides/creating-a-payment-gateway

Demonstrates how to create a new subscription and update an existing one to 'canceled' status using the FOSSBilling admin API. Requires client ID, gateway ID, currency, external subscription ID, amount, and invoice details for creation. For cancellation, it requires fetching the subscription by its external ID and then updating its status.

```php
// When a subscription is created:
$api_admin->invoice_subscription_create([
    'client_id'  => $clientId,
    'gateway_id' => $gateway_id,
    'currency'   => $currency,
    'sid'        => $externalSubscriptionId,  // The ID from the payment gateway
    'status'     => 'active',
    'period'     => $cycle . $unit,           // e.g., '1M' for monthly
    'amount'     => $amount,
    'rel_type'   => 'invoice',
    'rel_id'     => $invoiceId,
]);
 
// When a subscription is canceled:
$subscription = $api_admin->invoice_subscription_get(['sid' => $externalSubscriptionId]);
$api_admin->invoice_subscription_update(['id' => $subscription['id'], 'status' => 'canceled']);
```

--------------------------------

### Conditional Payment Instructions by Currency

Source: https://fossbilling.org/docs/developing-fossbilling/guides/custom-gateway

Demonstrates using Twig conditional logic to display specific bank account details based on the invoice currency.

```html
{% 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 %}
```

--------------------------------

### Apache .htaccess Configuration

Source: https://fossbilling.org/docs/troubleshooting

This snippet represents the typical content of an .htaccess file used by Apache to enable URL rewriting for applications like FOSSBilling. It ensures that requests are correctly routed to the index.php file, which is crucial for subfolder installations and proper routing.

```apache
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^(.*)$ index.php?/$1 [L]
</IfModule>
```

--------------------------------

### Payment Adapter File Placement

Source: https://fossbilling.org/docs/developing-fossbilling/guides/creating-a-payment-gateway

Illustrates the recommended directory structure for placing custom payment gateway adapter files within the FOSSBilling project.

```APIDOC
## File Placement

Payment adapter files reside under `src/library/Payment/Adapter/`. FOSSBilling discovers adapters by scanning this directory for PHP files. You have two placement options:

```

src/library/Payment/Adapter/
├── MyGateway.php                    # Option 1: Single file
├── MyGateway/
│   └── MyGateway.php                # Option 2: Subdirectory (for complex adapters)
├── Stripe.php                       # Built-in adapter
├── PayPalEmail.php                  # Built-in adapter
├── Custom.php                       # Built-in adapter
└── ClientBalance.php                # Built-in adapter
```

Use a subdirectory if your adapter has additional dependencies, helper files, or assets (like a logo image).
```

--------------------------------

### Update FOSSBilling Configuration Structure

Source: https://fossbilling.org/docs/changelog

Demonstrates the transition from legacy flat configuration keys to the new nested i18n array structure in config.php.

```php
// Old configuration format
'timezone' => 'UTC',
'locale' => 'en_US',
'locale_date_format' => 'l, d F o',
'locale_time_format' => ' G:i:s',

// New configuration format
'i18n' => [
  'locale' => 'en_US',
  'timezone' => 'UTC',
  'date_format' => 'medium',
  'time_format' => 'short',
  'datetime_pattern' => '',
]
```

--------------------------------

### GET /guest/serviceapikey/check

Source: https://fossbilling.org/docs/product-types/apikeys

Validates whether a provided API key is active and valid within the system.

```APIDOC
## GET /guest/serviceapikey/check

### Description
Checks if the provided API key is valid.

### Method
GET

### Endpoint
/guest/serviceapikey/check

### Parameters
#### Query Parameters
- **api_key** (string) - Required - The API key string to validate.

### Response
#### Success Response (200)
- **result** (boolean) - Returns true if the key is valid, false otherwise.
```

--------------------------------

### Check module permissions in FOSSBilling

Source: https://fossbilling.org/docs/developing-fossbilling/guides/creating-a-module

Demonstrates how to verify staff permissions using the staff service. Includes a one-liner approach that throws an exception on failure and a manual check approach for custom logic handling.

```php
// One-liner: Checks permission and throws exception if denied
$this->di['mod_service']('Staff')->checkPermissionsAndThrowException('example', 'delete_something');

// Manual check: Allows custom handling of unauthorized access
$staff_service = $this->di['mod_service']('Staff');
if (!$staff_service->hasPermission(null, 'example', 'delete_something')) {
    throw new \FOSSBilling\InformationException('You do not have permission to perform this action', [], 403);
}
```

--------------------------------

### POST /api/admin/staff/create

Source: https://fossbilling.org/docs/developing-fossbilling/api

Example of creating a new staff member using the FOSSBilling admin API. This endpoint requires administrator authentication.

```APIDOC
## POST /api/admin/staff/create

### Description
Creates a new staff member within the FOSSBilling system. Requires administrator privileges.

### Method
POST

### Endpoint
`/api/admin/staff/create`

### Parameters
#### Query Parameters
None

#### Request Body
- **email** (string) - Required - The email address for the new staff member.
- **password** (string) - Required - The password for the new staff member.
- **name** (string) - Required - The full name of the staff member.
- **admin_group_id** (integer) - Required - The ID of the administrator group to assign.
- **status** (string) - Required - The status of the staff member (e.g., 'active').

### Request Example
```json
{
  "email": "hello@fossbilling.org",
  "password": "Testing123+",
  "name": "John Doe",
  "admin_group_id": 1,
  "status": "active"
}
```

### Response
#### Success Response (200)
- **id** (integer) - The ID of the newly created staff member.
- **email** (string) - The email address of the staff member.
- **name** (string) - The name of the staff member.
- **status** (string) - The status of the staff member.

#### Response Example
```json
{
  "id": 1,
  "email": "hello@fossbilling.org",
  "name": "John Doe",
  "status": "active"
}
```
```

--------------------------------

### Clone FOSSBilling Repository and Navigate

Source: https://fossbilling.org/docs/getting-started/building

This command clones the FOSSBilling repository from GitHub and changes the current directory to the newly cloned repository. It's the first step in building the project from source.

```bash
git clone https://github.com/FOSSBilling/FOSSBilling.git && cd FOSSBilling
```

--------------------------------

### FOSSBilling Security Configuration Example

Source: https://fossbilling.org/docs/security/securing-fossbilling

This code snippet demonstrates how to configure security settings within the FOSSBilling config.php file. It includes options for 'mode', 'force_https', and 'session_lifespan'.

```php
'security' => [
	'mode' => 'strict',
	'force_https' => true,
	'session_lifespan' => 7200,
],
```

--------------------------------

### Payment Initiation Flow

Source: https://fossbilling.org/docs/developing-fossbilling/guides/creating-a-payment-gateway

Details the steps involved when a client initiates a payment on an invoice, from clicking 'Pay' to the gateway returning HTML or redirecting the client.

```APIDOC
## Payment Initiation Flow

When a client clicks “Pay” on an invoice, the following happens:

```
Client clicks "Pay"
        |
        v
Guest API: invoice/payment
        |
        v
FOSSBilling loads the gateway adapter
        |
        v
Calls adapter's getHtml() method
        |
        v
Returns HTML to client browser
        |
        +---> Embedded form (e.g. Stripe Elements)
        |         Client completes payment in-page
        |         Gateway redirects to callback URL
        |
        +---> Redirect form (e.g. PayPal)
                  Client is redirected to gateway site
                  Client completes payment externally
                  Gateway posts back to callback URL
```
```

--------------------------------

### Verify Payments via External API

Source: https://fossbilling.org/docs/developing-fossbilling/guides/creating-a-payment-gateway

Performs an HTTP GET request to an external payment provider to validate a transaction ID. Uses Symfony HttpClient and handles authorization headers.

```php
private function verifyPayment(string $paymentId): array
{
    $apiKey = $this->config['test_mode'] ? $this->config['test_secret_key'] : $this->config['secret_key'];
    $apiBase = $this->config['test_mode'] ? 'https://sandbox.examplepay.com/api/v1' : 'https://api.examplepay.com/v1';

    $httpClient = Symfony\Component\HttpClient\HttpClient::create(['bindto' => BIND_TO]);
    $response = $httpClient->request('GET', $apiBase . '/payments/' . $paymentId, [
        'headers' => ['Authorization' => 'Bearer ' . $apiKey],
    ]);

    if ($response->getStatusCode() !== 200) {
        throw new Payment_Exception('Failed to verify payment with ExamplePay');
    }
    return $response->toArray();
}
```

--------------------------------

### Performing HTTP Requests with Symfony HttpClient

Source: https://fossbilling.org/docs/developing-fossbilling/guides/creating-a-payment-gateway

Shows how to initialize the Symfony HTTP client and execute a POST request with headers and JSON payloads, ensuring network compliance via the BIND_TO constant.

```php
$httpClient = Symfony\Component\HttpClient\HttpClient::create(['bindto' => BIND_TO]);
 
$response = $httpClient->request('POST', 'https://api.mygateway.com/verify', [
    'headers' => [
        'Authorization' => 'Bearer ' . $this->config['api_key'],
        'Content-Type'  => 'application/json',
    ],
    'json' => [
        'payment_id' => $paymentId,
    ],
]);
 
$result = $response->toArray();
```

--------------------------------

### Constructor Validation for Payment Gateway Configuration (PHP)

Source: https://fossbilling.org/docs/developing-fossbilling/guides/creating-a-payment-gateway

This PHP code snippet demonstrates how to validate essential configuration parameters within the constructor of a FOSSBilling payment adapter. It checks for the presence of API keys based on whether the gateway is in test or live mode, throwing a `Payment_Exception` if required keys are missing.

```php
public function __construct(private $config)
{
    if ($this->config['test_mode']) {
        if (!isset($this->config['test_api_key'])) {
            throw new Payment_Exception("Test API Key missing for (example gateway)");
        }
    } else {
        if (!isset($this->config['api_key'])) {
            throw new Payment_Exception("Live API Key missing for (example gateway)");
        }
    }
}

```

--------------------------------

### Minimal FOSSBilling Payment Adapter Structure (PHP)

Source: https://fossbilling.org/docs/developing-fossbilling/guides/creating-a-payment-gateway

This is the basic skeleton for a FOSSBilling payment adapter class. It implements the `InjectionAwareInterface` and defines the essential methods required for a payment gateway. Dependencies include PimpleContainer for dependency injection.

```php
<?php

class Payment_Adapter_MyGateway implements FOSSBilling\InjectionAwareInterface
{
    protected ?Pimple\Container $di = null;

    public function __construct(private $config)
    {
        // Validate required configuration
        if (!isset($this->config['api_key'])) {
            throw new Payment_Exception(
                'The ":pay_gateway" payment gateway is not fully configured. Please configure the :missing',
                [':pay_gateway' => 'MyGateway', ':missing' => 'API Key'],
                4001
            );
        }
    }

    public function setDi(Pimple\Container $di): void
    {
        $this->di = $di;
    }

    public function getDi(): ?Pimple\Container
    {
        return $this->di;
    }

    public static function getConfig(): array
    {
        // Declare capabilities, description, logo, and configuration form fields
    }

    public function getHtml($api_admin, $invoice_id, $subscription): string
    {
        // Generate the payment form/widget shown to the client
    }

    public function processTransaction($api_admin, $id, $data, $gateway_id): void
    {
        // Handle IPN/webhook: verify payment, add funds, pay invoice
    }
}

```

--------------------------------

### Gateway Configuration Definition (PHP)

Source: https://fossbilling.org/docs/developing-fossbilling/guides/creating-a-payment-gateway

This PHP static method, `getConfig()`, defines the capabilities and configuration form fields for a FOSSBilling payment gateway. It specifies support for one-time payments, subscriptions, iframe loading, provides a description, logo details, and defines the input fields for the admin configuration panel.

```php
public static function getConfig(): array
{
    return [
        'supports_one_time_payments' => true,
        'supports_subscriptions' => false,
        'can_load_in_iframe' => false,
        'description' => 'Accept payments via MyGateway. Enter your API credentials to get started.',
        'logo' => [
            'logo' => 'mygateway.png',
            'height' => '30px',
            'width' => '65px',
        ],
        'form' => [
            'api_key' => [
                'text',
                [
                    'label' => 'Live API Key:',
                ],
            ],
            'api_secret' => [
                'text',
                [
                    'label' => 'Live API Secret:',
                ],
            ],
            'test_api_key' => [
                'text',
                [
                    'label' => 'Test API Key:',
                    'required' => false,
                ],
            ],
            'test_api_secret' => [
                'text',
                [
                    'label' => 'Test API Secret:',
                    'required' => false,
                ],
            ],
        ],
    ];
}

```
Tokens:
Raw