PHP SDK

The BillingServ PHP SDK is the official Composer package for integrating PHP applications with the BillingServ v2 API. It provides resource clients for billing, checkout, domains, reporting, support, VPN, software licensing, and more, while handling authentication, JSON requests, response decoding, and common API errors.

The SDK is for server-side PHP applications. Never expose your merchant API key in browser code or commit it to your repository.

Requirements

PHP 8.3 or later
PHP curl extension
PHP json extension

Install

Install the package with Composer:

composer require billingserv/php-sdk

The package is released under the MIT license. See the PHP-SDK repository for the source, tests, and release history.

Configure the client

Create an API key from the API Information page, then pass the merchant bearer token to the client:

<?php

require __DIR__.'/vendor/autoload.php';

use BillingServ\BillingServ;

$billingserv = new BillingServ(
    apiKey: $_ENV['BILLINGSERV_API_KEY'],
    options: [
        'base_uri' => $_ENV['BILLINGSERV_BASE_URI'],
        'timeout' => 15,
    ],
);

base_uri should point to your BillingServ installation and end in /api/v2, for example:

https://your-billingserv-domain.com/api/v2

If you omit base_uri, the SDK uses the public demo API URL. Set it explicitly for production and for self-hosted BillingServ installations. The timeout option is in seconds and defaults to 30. Store configuration in environment variables or another secret store. For example:

BILLINGSERV_API_KEY=your-merchant-bearer-token
BILLINGSERV_BASE_URI=https://your-billingserv-domain.com/api/v2
BILLINGSERV_WEBHOOK_SECRET=your-webhook-signing-secret

The merchant key must have permission for the resources and operations your application calls. Keep the key on your server; customers authenticate through your application and do not need a merchant API key.

Make API calls

Resource clients are exposed as properties on the BillingServ instance. For example, list customers and create a customer with an idempotency key:

$customers = $billingserv->customers->list([
    'search' => 'jane',
    'per_page' => 25,
]);

$reference = bin2hex(random_bytes(16));
$customer = $billingserv->customers->create([
    'name' => 'Jane Doe',
    'username' => 'jane@example.com',
    'password' => 'use-a-secret-password',
    'address_1' => '1 High Street',
    'city' => 'Manchester',
    'county_id' => 1231,
    'country_id' => 81,
    'postal_code' => 'M1 1AA',
], idempotencyKey: 'signup-'.$reference);

Idempotency keys are supported for the create and update operations documented in the API overview. Use a unique key for each logical write so a retry does not create a duplicate resource.

Available resources

Client	Covers
`customers`	Customer records, credits, and customer lookup
`invoices`	Invoices, quotes, unpaid invoices, and payment capture
`orders`	Orders, acceptance, and package-change previews
`checkout`	Hosted checkout links
`domains`	Domain availability and lookup
`packages`, `packageGroups`, `packageOptions`	Products and package configuration
`countries`, `counties`, `currencies`	Country, county, and currency data
`marketing`, `reports`, `settings`	Marketing, reporting, and account settings
`tickets`	Support tickets
`usage`, `vpn`, `licenses`, `modules`	Usage metering, VPN, licensing, and modules

Each SDK method maps to a documented v2 API endpoint. Use the API reference to check required fields, permissions, and response details.

Hosted checkout and domains

Create a hosted checkout URL, then redirect the customer to the returned URL:

$checkout = $billingserv->checkout->create([
    'package_id' => 12,
    'cycle_id' => 3,
    'callback_url' => 'https://app.example.com/billing/return',
    'customer_id' => 4,
]);

header('Location: '.$checkout['url']);
exit;

You can also check domain availability across enabled extensions:

$availability = $billingserv->domains->lookup('example');

foreach ($availability['results'] ?? [] as $result) {
    echo $result['domain'];
    echo $result['available'] ? ' is available' : ' is taken';
    echo PHP_EOL;
}

For the complete domain-search and callback flow, see the domain API and hosted checkout guide.

Handle errors

Successful responses are returned as plain PHP arrays. API and network failures throw exceptions:

use BillingServ\Exception\ApiException;
use BillingServ\Exception\AuthenticationException;
use BillingServ\Exception\NetworkException;
use BillingServ\Exception\RateLimitException;
use BillingServ\Exception\ValidationException;

try {
    $customer = $billingserv->customers->get(999);
} catch (ValidationException $e) {
    $errors = $e->getErrors();
} catch (AuthenticationException $e) {
    // The API key is missing, invalid, or not authorized.
} catch (RateLimitException $e) {
    // Back off for the server-provided duration when available.
    sleep($e->getRetryAfter() ?? 30);
} catch (NetworkException $e) {
    // The HTTP request could not be completed.
} catch (ApiException $e) {
    // Inspect the status, error code, request ID, and response.
}

ApiException exposes getStatus(), getErrors(), getErrorCode(), getRequestId(), and getResponse(). Record the request ID with your application logs when reporting an API failure.

Verify webhooks

When webhook signing is enabled, verify the raw request body before parsing it. The SDK checks the BillingServ-Signature header and rejects stale or invalid signatures:

use BillingServ\Webhook;

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_BILLINGSERV_SIGNATURE'] ?? '';
$secret = $_ENV['BILLINGSERV_WEBHOOK_SECRET'];

if (!Webhook::verify($payload, $signature, $secret)) {
    http_response_code(400);
    exit;
}

$event = Webhook::parse($payload);
// Persist or enqueue by $event['id']; deliveries may be retried.

Respond to verified deliveries promptly, then process them asynchronously where possible. See the webhook overview and webhook event reference for event types, retries, and endpoint configuration.

Getting Started

Developer Hub

Webhooks

Endpoints

Requirements

Install

Configure the client

Make API calls

Available resources

Hosted checkout and domains

Handle errors

Verify webhooks

Further reading

​Requirements

​Install

​Configure the client

​Make API calls

​Available resources

​Hosted checkout and domains

​Handle errors

​Verify webhooks

​Further reading

Requirements

Install

Configure the client

Make API calls

Available resources

Hosted checkout and domains

Handle errors

Verify webhooks

Further reading