HF PanelDocsv1.0.0

Billing integration

Connect your own billing system to HF Panel with an API token to create, suspend, upgrade and delete hosting accounts.

If you sell hosting through your own billing or shop system, it can manage HF Panel accounts through the token API: create an account when an order is paid, suspend it when an invoice is overdue, move it to another package, and delete it when the customer leaves. This page shows the calls in the order a billing system needs them.

Ready-made modules for WHMCS and Blesta

If you use WHMCS or Blesta, you do not need to write any code: install the HF Panel module and it makes all the calls on this page for you.

Billing system Guide
WHMCS 8 WHMCS module
Blesta 5 Blesta module

Download both from the Integrations part of the install page, https://hostfog.io/download/#integrations. For any other billing system, follow the steps below.

Tip: HF Panel can also take payments itself, with Stripe and PayPal, under Server Admin › Billing › Billing. Use this page only when another system does your billing. For the built-in billing, see Webhooks.

1. Make a token for the billing system

  1. Sign in to Server Admin (or to the Reseller Panel, to sell as a reseller).
  2. Open your name at the top right › Password & security › API tokens.
  3. Name the token, for example Billing system, and choose Read & change.
  4. In Allowed IPs, type your billing server's IP address.
  5. Type your password and click Create token, then copy the token into the billing system's settings.

A reseller's token manages only that reseller's customers and stays within the reseller's account limit and privileges.

The billing system needs two settings:

Setting Value
API address https://api.yourdomain.com:2087/v1 (or the old address https://panel.yourdomain.com:8443/api/v1)
Header Authorization: Bearer hf_xxx

Check the connection:

bash
curl -s -H "Authorization: Bearer hf_xxx" https://api.yourdomain.com:2087/v1/me

The answer's token.access must be write.

2. Map your products to packages

Each product in your billing system matches a package in HF Panel. List the packages to find their ids and names:

bash
curl -s -H "Authorization: Bearer hf_xxx" https://api.yourdomain.com:2087/v1/packages

You can use either the package's id or its name in the calls below. The id stays the same when someone renames the package.

3. The calls for each event

The examples use:

bash
A=https://api.yourdomain.com:2087/v1
H="Authorization: Bearer hf_xxx"
Billing event Call
Order paid: create the account POST /v1/accounts
Invoice overdue: suspend POST /v1/accounts/{username}/suspend
Invoice paid: unsuspend POST /v1/accounts/{username}/unsuspend
Upgrade or downgrade POST /v1/accounts/{username}/package
Password reset from the billing system POST /v1/accounts/{username}/password
"Log in to control panel" button POST /v1/accounts/{username}/login
Usage for the client area GET /v1/accounts/{username}/usage
Cancelled: terminate DELETE /v1/accounts/{username}

Create

bash
curl -s -H "$H" -H 'Content-Type: application/json' $A/accounts \
     -d '{"username":"sarahbakes","email":"sarah@example.com","package":"Starter","domain":"example.com","welcome":true}'
  • Answers 201 with the account and its password. Store the username; the password is not shown again.
  • Leave out password to have HF Panel make a strong random one.
  • "welcome": true sends the customer the welcome email with their sign-in details.
  • When the domain could not be added, the account is still made and warning says why.
  • Administrators can choose the server with server (a server's id); by default HF Panel picks the server with the fewest accounts that takes new ones.

Suspend and unsuspend

bash
curl -s -H "$H" -X POST $A/accounts/sarahbakes/suspend
curl -s -H "$H" -X POST $A/accounts/sarahbakes/unsuspend

Both are safe to repeat: nothing changes when the account already is in that state. The answer's status shows the result.

Change package

bash
curl -s -H "$H" -H 'Content-Type: application/json' $A/accounts/sarahbakes/package -d '{"package":"Business"}'

Single sign-on: "Log in to control panel"

bash
curl -s -H "$H" -X POST $A/accounts/sarahbakes/login | jq -r .data.url

The answer's url signs the customer in to their Control Panel. It works once, within 2 minutes, so make it when the customer clicks the button and redirect their browser to it straight away. Add "goto" to open a screen, for example {"goto":"email"}. A suspended account answers 422.

Usage

bash
curl -s -H "$H" $A/accounts/sarahbakes/usage

Gives disk space used and allowed, this month's bandwidth, and how many domains, email accounts and databases the account has. See API: accounts.

Terminate

bash
curl -s -H "$H" -X DELETE $A/accounts/sarahbakes

Warning: this deletes the account with all its websites, email and databases, and cannot be undone. When deleting accounts needs a second administrator's approval, this call answers 403 and must be done in the panel.

Handling errors

  • Check the HTTP status and ok of every answer. On failure, error is a sentence you can log or show.
  • 422 means HF Panel refused the request for a reason in error, such as "That username is taken." Fix the data; do not retry unchanged.
  • 500 with Server: … means the server could not carry out the change. Retry later.
  • 429 means your billing server's IP address had too many failed sign-ins. Check the token and wait 15 minutes.
  • 404 "No such account." also covers accounts the token may not manage, for example another reseller's customer.