### Install Project Dependencies

Source: https://github.com/fossbilling/fossbilling.org/blob/main/README.md

Installs all necessary dependencies for the project. Use `npm install` if not starting from a clean state.

```bash
npm ci
```

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

### Start Local Development Server

Source: https://github.com/fossbilling/fossbilling.org/blob/main/README.md

Starts a local development server for live previewing changes. The server typically runs at `http://localhost:3000` and reflects most changes without a restart.

```bash
npm run dev
```

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

### Make Guest API GET Request

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/developing-fossbilling/javascript/page.mdx

Example of making a GET request to the guest API endpoint for system version. Includes success and error handlers.

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

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

### Database Configuration Example

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/maintaining-fossbilling/admin-manual-reset/page.mdx

This snippet shows an example of the database configuration array, typically found in a config file. Ensure the 'name' field matches your FOSSBilling database name.

```php
'db' =>
  array (
    'type' => 'mysql',
    'host' => 'localhost',
    'port' => '3306',
    'name' => 'fossbilling',
    'user' => 'fossbilling_user',
    'password' => 'fossbilling_password',
  ),
```

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

### Guest API: Get System Version

Source: https://context7.com/fossbilling/fossbilling.org/llms.txt

This example demonstrates how to retrieve the FOSSBilling system version using the guest API. This endpoint does not require authentication.

```APIDOC
## POST /api/guest/system/version

### Description
Retrieves the current version of the FOSSBilling system. This is a public endpoint and does not require authentication.

### Method
POST

### Endpoint
https://example.com/api/guest/system/version

### Parameters
No specific parameters are required for this endpoint.

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **result** (string) - The current version of the FOSSBilling system.
- **error** (null) - Null if the operation was successful.

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

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

### Admin API: Get Client List

Source: https://context7.com/fossbilling/fossbilling.org/llms.txt

This example shows how to retrieve a list of clients using the admin API. It supports pagination parameters and requires administrator authentication.

```APIDOC
## POST /api/admin/client/get_list

### Description
Retrieves a list of clients from the FOSSBilling system. This endpoint is accessible to authenticated administrators and supports pagination.

### Method
POST

### Endpoint
https://example.com/api/admin/client/get_list

### Parameters
#### Query Parameters
- **per_page** (integer) - Optional - The number of clients to return per page.
- **page** (integer) - Optional - The page number to retrieve.

#### Request Body
- **per_page** (integer) - Optional - The number of clients to return per page.
- **page** (integer) - Optional - The page number to retrieve.

### Request Example
```json
{
  "per_page": 10,
  "page": 1
}
```

### Response
#### Success Response (200)
- **result** (object) - An object containing the list of clients and total count.
  - **list** (array) - An array of client objects.
  - **total** (integer) - The total number of clients available.
- **error** (null) - Null if the operation was successful.

#### Response Example
```json
{
  "result": {
    "list": [...],
    "total": 42
  },
  "error": null
}
```
```

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

### NGINX Configuration for FOSSBilling

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/getting-started/installation/page.mdx

This NGINX configuration serves as a starting point for FOSSBilling. Remember to replace placeholders like %%DOMAIN%% and %%SOURCE_PATH%% with your specific server details. Adjust SSL settings and the fastcgi_pass directive based on your server's PHP-FPM setup.

```conf
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 need to be changed according your server setup:
		# phpx.x is your server setup
		# examples: /var/run/phpx.x-fpm.sock, /var/run/php/phpx.x-fpm.sock or /run/php/phpx.x-fpm.sock are all valid options
		# Or even localhost:port (Default 9000 will work fine)
		# Please check your server setup

		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;
		}
}

```

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

### JavaScript API Wrapper: Guest GET Request

Source: https://context7.com/fossbilling/fossbilling.org/llms.txt

Demonstrates how to make a GET request to the guest API using the FOSSBilling JavaScript API wrapper. This is useful for fetching public system information.

```APIDOC
## API.guest.get(endpoint, params, callback, errorCallback)

### Description
Makes a GET request to the guest API. No authentication is required.

### Parameters
- **endpoint** (string) - Required - The API endpoint to call (e.g., "system/version").
- **params** (object) - Optional - Parameters to send with the request.
- **callback** (function) - Required - Function to handle the successful response.
- **errorCallback** (function) - Optional - Function to handle errors.

### Example Usage
```javascript
API.guest.get("system/version", {}, function(response) {
    console.log("FOSSBilling version:", response);
}, function(error) {
    console.error("Error:", error);
});
```
```

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

### Make Admin API POST Request

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/developing-fossbilling/javascript/page.mdx

Example of making a POST request to the admin API endpoint to get a list of clients. Includes success and error handlers.

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

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

### Apply Permissions to Folders and Files

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/troubleshooting/page.mdx

Use these commands to set correct file and folder permissions for FOSSBilling installations. Ensure you are in the document root before executing.

```bash
find . -type d -exec chmod 755 {} \;
```

```bash
find . -type f -exec chmod 644 {} \;
```

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

### FOSSBilling Configuration File Example

Source: https://context7.com/fossbilling/fossbilling.org/llms.txt

A representative configuration file for FOSSBilling, controlling core behavior including URL, security settings, internationalization, database connection, API limits, and logging.

```php
<?php
// config.php — representative configuration

return [
    'url'               => 'https://example.com/',
    'admin_area_prefix' => '/admin',
    'salt'              => 'CHANGE_ME_TO_RANDOM_STRING',
    'debug'             => false,
    'update_branch'     => 'release',   // 'release' or 'preview'

    'security' => [
        'mode'             => 'strict',  // 'strict' or 'regular'
        'force_https'      => true,
        'session_lifespan' => 7200,      // seconds (2 hours)
    ],

    'i18n' => [
        'locale'           => 'en_US',
        'timezone'         => 'UTC',
        'date_format'      => 'medium',  // 'none','short','medium','long'
        'time_format'      => 'short',
        'datetime_pattern' => '',        // overrides date/time_format when set
    ],

    'db' => [
        'type'     => 'mysql',
        'host'     => '127.0.0.1',
        'name'     => 'fossbilling',
        'user'     => 'db_user',
        'password' => 'db_password',
        'port'     => 3306,
    ],

    'api' => [
        'require_referrer_header' => false,
        'allowed_ips'             => [],        // empty = allow all
        'rate_span'               => 60,        // seconds
        'rate_limit'              => 1000,      // requests per rate_span
        'rate_span_login'         => 60,
        'rate_limit_login'        => 20,
        'CSRFPrevention'          => true,
    ],

    'maintenance_mode' => [
        'enabled'      => false,
        'allowed_urls' => ['/api/guest/system/ping'],
        'allowed_ips'  => ['192.168.1.0/24'],
    ],

    'twig' => [
        'debug'       => false,
        'auto_reload' => true,
        'cache'       => '/var/www/fossbilling/data/cache',
    ],

    'log_stacktrace'    => false,
    'stacktrace_length' => 25,
    'disable_auto_cron' => false,   // set true in production for cron stability
];

```

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

### Install NPM Dependencies

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/getting-started/building/page.mdx

Install the necessary Node Package Manager (NPM) dependencies for the project. This is required before building front-end assets.

```bash
npm i
```

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

### Simple License Plugin Example

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/product-types/license/page.mdx

Demonstrates a basic license generation plugin. It creates a license key with a default length, optional prefix, and formatted for readability. This plugin uses uppercase letters and digits 1-9.

```php
MYAPP-ABCD1-EFGH2-IJKL3-MNOP4
```

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

### Admin API Endpoint Example

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/developing-fossbilling/api/page.mdx

This example demonstrates how to make a POST request to an admin API endpoint using cURL, including authentication and a JSON payload. Replace 'YOUR_API_KEY' with your actual API key.

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

### Description
Creates a new staff member in the FOSSBilling system.

### Method
POST

### Endpoint
`https://example.com/api/admin/staff/create`

### Parameters
#### Request Body
- **email** (string) - Required - The email address of the new staff member.
- **password** (string) - Required - The password for the new staff member.
- **name** (string) - Required - The full name of the new staff member.
- **admin_group_id** (integer) - Required - The ID of the administrator group.
- **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.
- **message** (string) - A success message.

#### Response Example
```json
{
  "id": 1,
  "message": "Staff member created successfully."
}
```
```

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

### Install Composer Dependencies

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/getting-started/building/page.mdx

Install the PHP Composer dependencies for FOSSBilling. Ensure you have Composer installed and a supported PHP version.

```bash
composer install
```

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

### Authenticate and Create Staff User (curl)

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/developing-fossbilling/api/page.mdx

Example using curl to authenticate with an API key and send a POST request to create a staff user. Ensure to replace 'YOUR_API_KEY' with your actual key and adjust the JSON payload as necessary.

```bash
# Example curl request to authenticate and call an admin API endpoint

curl -X POST "https://example.com/api/admin/staff/create" \
  -H "Authorization: Basic $(echo -n 'admin:YOUR_API_KEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "hello@fossbilling.org",
    "password": "Testing123+",
    "name": "John Doe",
    "admin_group_id": 1,
    "status": "active"
  }'

# Replace YOUR_API_KEY with your actual API key and adjust the payload as needed.
```

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

### Check Permissions (Detailed)

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/developing-fossbilling/guides/creating-a-module/page.mdx

This example demonstrates how to check for a specific permission using the `hasPermission` method and manually throw an exception with a custom message and status code if the permission is denied.

```PHP
$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);
}
```

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

### Authenticate and Create Staff User (JavaScript)

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/developing-fossbilling/api/page.mdx

Example using JavaScript's fetch API to authenticate with Basic Auth and send a POST request to create a staff user. Remember to replace 'YOUR_API_KEY' with your actual key and adjust the payload.

```javascript
// Example JavaScript request to authenticate and call an admin API endpoint

const url = "https://example.com/api/admin/staff/create"; // /api/{role}/{module}/{endpoint}
const apiKey = "YOUR_API_KEY";

const payload = {
    email: "hello@fossbilling.org",
    password: "Testing123+",
    name: "John Doe",
    admin_group_id: 1,
    status: "active"
};

const headers = new Headers();
headers.set("Content-Type", "application/json");
headers.set("Authorization", "Basic " + btoa("admin:" + apiKey));

fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload)
})
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error("Error:", error));

// Replace YOUR_API_KEY with your actual API key and adjust the request as needed.
```

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

### Get Available License Plugins

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/product-types/license/page.mdx

Retrieve a list of available license validation plugins. This is useful for understanding the different licensing strategies supported by FOSSBilling.

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

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

### Authenticate and Create Staff User (Python)

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/developing-fossbilling/api/page.mdx

Example using Python's requests library to authenticate with HTTP Basic Auth and send a POST request to create a staff user. Replace 'YOUR_API_KEY' with your actual key and modify the payload.

```python
# Example Python request to authenticate and call an admin API endpoint

import requests
from requests.auth import HTTPBasicAuth

url = "https://example.com/api/admin/staff/create" # /api/{role}/{module}/{endpoint}
api_key = "YOUR_API_KEY"

payload = {
    "email": "hello@fossbilling.org",
    "password": "Testing123+",
    "name": "John Doe",
    "admin_group_id": 1,
    "status": "active"
}

auth = HTTPBasicAuth('admin', api_key)
headers = {
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, auth=auth)
print(response.json())

# Replace YOUR_API_KEY with your actual API key and adjust the request as needed.
```

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

### Admin API: Create Staff Member

Source: https://context7.com/fossbilling/fossbilling.org/llms.txt

This example demonstrates how to create a new staff member using the admin API. It requires administrator authentication and sends staff details in JSON format.

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

### Description
Creates a new staff member in the FOSSBilling system. This endpoint is accessible only to authenticated administrators.

### Method
POST

### Endpoint
https://example.com/api/admin/staff/create

### Parameters
#### 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)
- **result** (boolean) - Indicates if the operation was successful.
- **error** (null) - Null if the operation was successful.

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

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

### Get Client List via Admin API (Python)

Source: https://context7.com/fossbilling/fossbilling.org/llms.txt

This Python script demonstrates how to fetch a list of clients using the admin API. It utilizes the requests library for HTTP communication and Basic Authentication.

```python
import requests
from requests.auth import HTTPBasicAuth

response = requests.post(
    "https://example.com/api/admin/client/get_list",
    json={"per_page": 10, "page": 1},
    auth=HTTPBasicAuth('admin', 'YOUR_API_KEY')
)
print(response.json())
```

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

### Build for Production

Source: https://github.com/fossbilling/fossbilling.org/blob/main/README.md

Creates a production-ready build of the website, including Pagefind indexing.

```bash
npm run build
```

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

### ExamplePay Payment Adapter Implementation

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/developing-fossbilling/guides/creating-a-payment-gateway/page.mdx

This class implements the FOSSBilling payment adapter interface for the fictional ExamplePay gateway. It includes configuration validation, dependency injection handling, and defines gateway capabilities and form fields.

```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() {

```

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

### Run OpenNext Cloudflare Preview

Source: https://github.com/fossbilling/fossbilling.org/blob/main/README.md

Builds the project and runs a preview environment using OpenNext for Cloudflare Workers.

```bash
npm run preview
```

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

### Payment Adapter File Placement Options

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/developing-fossbilling/guides/creating-a-payment-gateway/page.mdx

Shows the recommended directory structures for placing custom payment gateway adapter files within the FOSSBilling project.

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

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

### Serve Production Build

Source: https://github.com/fossbilling/fossbilling.org/blob/main/README.md

Serves the production build of the website using the Next.js server.

```bash
npm run start
```

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

### Get API Key Information

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/product-types/apikeys/page.mdx

Retrieves information about an API key, including any custom parameters associated with it.

```APIDOC
## POST /guest/serviceapikey/get_info

### Description
Similar to the `check` endpoint, except that this will also return any custom parameters that are defined for the API key.

### Method
POST

### Endpoint
/guest/serviceapikey/get_info

### Parameters
#### Request Body
- **api_key** (string) - Required - The API key to get information for.
```

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

### Get Available License Plugins

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/product-types/license/page.mdx

Administrators can use this endpoint to retrieve a list of all available license validation plugins configured in the system.

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

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

### Method
GET

### Endpoint
/admin/servicelicense/plugin_get_pairs

### Response
#### Success Response (200)
- **result** (object) - A key-value map 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
}
```
```

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

### Payment Initiation Flow Diagram

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/developing-fossbilling/guides/creating-a-payment-gateway/page.mdx

Illustrates the steps involved when a client initiates a payment through an invoice, showing interactions between the client, FOSSBilling, and the payment gateway.

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

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

### Get Callback URL with ServicePayGateway

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/developing-fossbilling/guides/creating-a-payment-gateway/page.mdx

Use the ServicePayGateway to obtain the base callback URL for your payment gateway. You can then append custom parameters as needed.

```php
$payGatewayService = $this->di['mod_service']('Invoice', 'PayGateway');
$payGateway = $this->di['db']->findOne('PayGateway', 'gateway = ?', ['MyGateway']);
$callbackUrl = $payGatewayService->getCallbackUrl($payGateway, $invoiceModel);

// Append extra parameters
$fullUrl = $callbackUrl . '&payment_id=' . $paymentId . '&redirect=true&invoice_hash=' . $invoiceModel->hash;
```

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

### Getting API Key Info

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/product-types/apikeys/page.mdx

Retrieve detailed information about an API key, including its validity and custom parameters, using the /guest/serviceapikey/get_info endpoint.

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

### Description
Retrieves detailed information about an API key, including its validity and configuration parameters.

### Method
GET

### Endpoint
/guest/serviceapikey/get_info

### Parameters
#### Query Parameters
- **key** (string) - Required - The API key to get information for.

### Response
#### Success Response (200)
- **result** (object) - Contains the API key information.
  - **valid** (integer) - Indicates if the key is valid (e.g., 1 for valid).
  - **config** (object) - Contains custom configuration parameters for the key.
    - **monthlyLimit** (integer) - Example: 250
    - **somethingElse** (integer) - Example: 1150
    - **astring** (string) - Example: "words"
- **error** (null) - Contains error details if any.

### Response Example
```json
{
  "result": {
    "valid": 1,
    "config": { "monthlyLimit": 250, "somethingElse": 1150, "astring": "words" }
  },
  "error": null
}
```
```

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

### Custom HTML Email Template

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/customizing-fossbilling/email_templates/page.mdx

An example of a basic HTML email template with embedded CSS for styling. This demonstrates how to create a more visually appealing email.

```html
<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8">
	<style type="text/css">
		body {
			font-family: Arial, sans-serif;
			font-size: 14px;
			color: #333333;
		}

		h1 {
			font-size: 24px;
			font-weight: bold;
			margin: 0 0 20px;
		}

		p {
			margin: 0 0 10px;
		}

		strong {
			font-weight: bold;
		}

		.signature {
			font-style: italic;
			color: #999999;
			margin-top: 20px;
			border-top: 1px solid #cccccc;
			padding-top: 10px;
		}
	</style>
</head>
<body>
	<h1>Test email from [{{ guest.system_company.name }}]</h1>
	<p>Hi {{ staff.name }},</p>
	<p>If you are reading this email, FOSSBilling is <strong>configured properly</strong> and is <strong>able to send emails</strong>.</p>
	<p class="signature">{{ guest.system_company.signature }}</p>
</body>
</html>
```

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

### Configure SELinux for FOSSBilling on RHEL

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/troubleshooting/page.mdx

Use these commands to configure SELinux to allow PHP to create files in the FOSSBilling document root. Ensure paths are correct for your system.

```bash
semanage fcontext -a -t httpd_sys_content_t '/var/www/html(/.*)?'
```

```bash
restorecon -Rv /var/www/html
```

```bash
setsebool -P httpd_can_network_connect on
```

```bash
setsebool -P httpd_can_sendmail on
```

```bash
setsebool -P httpd_can_network_connect_db on
```

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

### IPN/Callback Data Structure

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/developing-fossbilling/guides/creating-a-payment-gateway/page.mdx

The `$data` array contains all information received from the callback request, including GET, POST, raw POST data, and server variables.

```php
$data = [
    'get'                => $_GET,
    'post'               => $_POST,
    'http_raw_post_data' => '...',
    'server'             => $_SERVER,
    'invoice_id'         => 123,
    'gateway_id'         => 5,
];
```

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

### Log Payment Initiation Event

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/developing-fossbilling/guides/creating-a-payment-gateway/page.mdx

Record an informational message when a payment is initiated, including invoice details, amount, and currency. Useful for tracking the start of the payment process.

```php
$this->di['logger']->info('MyGateway: Payment initiated for invoice #%s, amount %s %s', $invoice->id, $amount, $currency);
```

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

### Specify PHP Binary in Cron Job

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/troubleshooting/page.mdx

When cron jobs use an incorrect PHP version, specify a more appropriate binary path. Examples include 'php8.2' or '/usr/bin/php8.2'.

```bash
php8.2 -f /path/to/your/fossbilling/artisan schedule:run
```

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

### Docker Compose for FOSSBilling and MySQL

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/getting-started/docker/page.mdx

This docker-compose.yml file sets up FOSSBilling with a MySQL database. Adjust environment variables for your security needs. Run with 'docker compose up -d'.

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

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

### FOSSBilling Cron Command

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/getting-started/installation/page.mdx

This is the command used to run FOSSBilling's cron job. It can be found on the installation complete page and within the administrator panel under Settings -> Scheduled Tasks.

```bash
php /path/to/your/fossbilling/public/index.php --method cron
```

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

### Import FOSSBilling API Wrapper

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/developing-fossbilling/javascript/page.mdx

Include these tags in your HTML to load the API wrapper and set the CSRF token. The system version is appended to prevent caching issues.

```html
<meta name="csrf-token" content="{{ CSRFToken }}">
<script src="{{ "Api/API.js?v=#{guest.system_version}" | library_url }}"></script>
```

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

### Access Invoice Data via DI Container

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/developing-fossbilling/guides/creating-a-payment-gateway/page.mdx

Use the DI container to get the raw `Model_Invoice` RedBeanPHP model. This is useful when direct interaction with services is needed, such as calculating totals.

```php
$this->di['db']->load('Invoice', $invoice_id)
```

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

### Clone FOSSBilling Repository

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/getting-started/building/page.mdx

Clone the FOSSBilling repository and navigate into the created directory. This is the first step to building from source.

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

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

### API Key Response Example

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/product-types/apikeys/page.mdx

This JSON response indicates a successful update operation for an API key. Note that this endpoint cannot change the API key itself; use the 'reset' endpoint for regeneration.

```json
{
    "result":true,
    "error":null
}
```

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

### Configure FOSSBilling Cron Job

Source: https://github.com/fossbilling/fossbilling.org/blob/main/app/docs/getting-started/docker/page.mdx

After installation, configure a cron job on the host system to ensure FOSSBilling's scheduled tasks run correctly. Replace '<container name/id>' with your container's identifier.

```bash
(crontab -l; echo "*/5 * * * * docker exec <container name/id> su www-data -s /usr/local/bin/php /var/www/html/cron.php")|awk '!x[$0]++'|crontab -
```