Custom Billing Integration¶

This topic will explain how to set up postpaid billing integration with any billing system except WHMCS (for example, Blesta, Hostbill, Ubersmith, or others).

Step 1 - Define your conversion rate between tokens and currencies¶

SolusVM 2 offers hourly and monthly billing. Decide how much real money (in desired currencies) one token costs.

Note

Tokens can be only integers.

We recommend that you prepare a detailed conversion table, for example:

 Tokens Token price in USD Token price in EUR 1 \$0.00100 €0.00091 10 \$0.01000 €0.00910 100 \$0.10000 €0.09100 1,000 \$1.00000 €0.91000 10,000 \$10.00000 €9.10000

Step 2 – Calculate your hourly and monthly prices¶

Prerequisites: Let’s assume that you’ve already added plans. If not, it’s high time to do so.

You now need to decide how much to charge for your plans. Each plan in SolusVM 2 can have the hourly and the monthly price in tokens:

• “Tokens per hour” is the price in tokens for using a resource for each hour.

For example, if you start a server and terminate it after five minutes, the server’s user has to pay the price for one hour.

• “Tokens per month” is the price in tokens for using a resource for approximately the whole month.

Months have different lengths but the monthly price is fixed. To achieve this, you set the monthly price by calculating the monthly cap. Let’s see an example.

We have the hourly price of 7 tokens (equals \$0.007/h). The whole 31-day month will then cost the following:

7 tokens × 24 hours × 31 days = 7 × 744 hours = 5208 tokens (equals \$5.21)

People like round numbers. We can deduct 208 tokens (\$0.21) and get the price of 5000 tokens (\$5.00). This will be our monthly cap and the monthly price at the same time. SolusVM 2 will choose which price (hourly or monthly) to charge depending on the monthly price.

For example, a user ran a server for 700 hours, which costs 4900 tokens. It’s less than 5000 tokens of the monthly cap so the user will be charged hourly. Next month, the user ran a server for 730 hours, which costs 5110 tokens. It’s more than 5000 tokens of the monthly cap so the user will be charged monthly (\$5.00).

We recommend that you calculate your hourly and monthly prices before actually setting them in SolusVM 2. Below you can see an example of how we calculated prices using the conversion table shown in step 1.

 Plans Tokens per hour Aggregated tokens per month (tokens per hour × 24 hours × 31 days) Aggregated price per month in USD Tokens per month (as the fixed price) Price per month in USD if “tokens per month” was applied 1 Core, 1 GiB RAM 7 5,208 \$5.21 5,000 \$5.00 1 Core, 2 GiB RAM 14 10,416 \$10.42 10,000 \$10.00 2 Cores, 2 GiB RAM 21 15,624 \$15.62 15,000 \$15.00 2 Cores, 4 GiB RAM 28 20,832 \$20.83 20,000 \$20.00

Note

In the example above, we’ve rounded up the monthly prices (the last two columns). It’s more convenient for customers and it can serve as a monthly discount. It’s up to you, if you do the same or not.

Step 3 – Set prices in tokens for plans in SolusVM 2¶

During the previous step, you’ve created the detailed pricing table. You now need to set the hourly and monthly prices (the second and the fifth columns in the pricing table respectively) for plans in SolusVM 2:

2. Go to Compute Resources > Plans.

3. You can specify the token values while editing an existing plan or creating a new one:

• To edit an existing plan, click the icon on the plan’s row.
• To create a new plan, click Add Plan.
4. Specify the hourly and the monthly price in tokens in “Tokens per hour” and “Tokens per month” respectively.

5. If you’re creating a plan, also fill in the required fields.

Note

If you set “Tokens per month” to “0”, only hourly billing will be available. If you set “Tokens per hour” to “0” but you specify the value for “Tokens (per month)”, then hourly billing will not be available. Customers will always be charged the fixed monthly price defined by “Tokens per month”.

6. Click Save.

Step 4 - Disable registration in the SolusVM 2 user area¶

The billing system configured with SolusVM 2 must be the main database for SolusVM 2 users. Only the billing system database must control which users have or don’t have the permission to create servers.

However, SolusVM 2 has a part of its interface called “user area” where users create servers. It is possible to bypass the billing system database by creating users directly in the user area. To prevent this, you need to disable registration in the user area:

2. Go to Settings > User Area and clear the “Enable Registration” checkbox.
3. Click Save.

You’ve disabled registration in the user area. The billing system database is now the main database for SolusVM 2 users.

Step 5 – Create limit groups¶

Limit groups help you set limits on the number of servers a specific user can create and can keep in the running state. We recommend that you create limit groups and choose the default limit group for new users. Learn how to do so.

Step 6 - Configure the API endpoint on the billing system side¶

You now need to configure the `GetTokenPricing` endpoint on the billing system side. You can easily configure it in a coding language of your choice.

You need this endpoint so that SolusVM 2 could show prices to customers.

Note

At the moment, you need to configure only the `GetTokenPricing` endpoint. But we may extend the list of API endpoints in the future.

The `GetTokenPricing` endpoint has the following request and response parameters:

Request parameters¶

 Parameter Type Description Required `token` string Authorization token No `userid` int The user ID in the billing system Yes

Response parameters¶

 Parameter Type Description `base_token_unit_cost` float The price of one token prior to any discounts and/or taxes. `user_token_unit_cost` float The full and final price of one token including discounts and taxes. `currency` array The array consisting of the currency formatting parameters: ISO code, prefix, suffix, number of decimals, thousands, and decimals separator. Example: ``````"currency": { "code": "GBP", "display_prefix": "\u00a3", "display_suffix": " GBP", "thousands_separator": ",", "decimals_separator": ".", "decimals_per_month": 2, "decimals_per_hour": 4 } `````` `discounts` array The array of applied discounts that consists of the name, description, and multiplier. Example: ``````"discounts": [ { "name": "Special Client Group Discount", "description": "5% Recurring Discount", "multipler": 0.95 } `````` `taxes` array The array of tax information including the tax type (compound or not) and rates (a label and rate). Example: ``````"taxes": { "compound": true, "rates": [ { "label": "City Tax", "rate": 6 }, { "label": "State Tax", "rate": 2 } ] } ``````

When SolusVM 2 needs to display a price to a customer, SolusVM 2 sends an API request with the user ID to the `GetTokenPricing` endpoint:

``````curl -X POST "https://www.mybilling.com/solusio/api/"
\ -H "Accept: application/json"
\ -H "Content-Type: application/x-www-form-urlencoded"
\ -d "token=xxxxxxx&action=GetTokenPricing&userid=1"
``````
The billing system then sends an API response with the price-related information, for example:
``````{
"base_token_unit_cost": 1.34,
"user_token_unit_cost": 1.0812,
"currency": {
"code": "GBP",
"display_prefix": "\u00a3",
"display_suffix": " GBP",
"thousands_separator": ",",
"decimals_separator": ".",
"decimals_per_month": 2,
"decimals_per_hour": 4
},
"discounts": [
{
"name": "Special Client Group Discount",
"description": "5% Recurring Discount",
"multipler": 0.95
}
],
"taxes": {
"compound": true,
"rates": [
{
"label": "City Tax",
"rate": 6
},
{
"label": "State Tax",
"rate": 2
}
]
}
}
``````
`user_token_unit_cost` in the response is the coefficient that reflects all taxes, discounts, and special offers of a particular user. SolusVM 2 then multiplies `user_token_unit_cost` by the plan’s price in tokens, gets the real price in the currency (pound sterling in our example), and shows this price to the user.

Step 7 - Enable billing integration in SolusVM 2¶

You have configured the API endpoint on the billing system side. We’ll now use it.

2. Go to Settings > Billing Integration.
3. Under “Type”, select “Custom billing”.
4. Specify the URL of the `GetTokenPricing` endpoint on the billing system side, for example `https://www.mybilling.com/solusio/api/`
5. (Optional) The billing system may require tokens for authorization. If so, paste your billing system authorization token.
6. Click Save.

Step 8 – Integrate user management with SolusVM 2 on the billing system side¶

The billing system must manage users in SolusVM 2 when it’s necessary.

To achieve this, you need to set up user management integration with SolusVM 2 on the billing system side. When you do so, the billing system will be able to create, edit, delete, lock, and suspend users in SolusVM 2 using the SolusVM 2 API endpoint.

Note

When integrating user management, ensure that the billing system sends `billing_user_id` to SolusVM 2. SolusVM 2 needs to have `billing_user_id` to match users stored in the billing system with those stored in SolusVM 2.

Step 9 – Configure automatic logging in to SolusVM 2¶

The billing system redirects users to the SolusVM 2 user area. To help users enter SolusVM 2 without having to log in the second time, configure automatic logging in. To do so, you need to create an access token for a user first. Then use a login link that contains the token to authorize the user in the integration scripts:

``````GET https://www.solus-user-ui.com/auth/by_token/{access_token}
``````

Step 10 - Configure invoices generation on the billing system side¶

As the last step, you need to configure the billing system to send API requests to the /usage SolusVM 2 API endpoint.

At the end of the billing cycle, the billing system generates and sends invoices to users. To calculate charges, the billing system must receive the consumed resources statistics by sending API requests to the `/usage` endpoint.

Congratulations! You’ve finished integrating your billing system with SolusVM 2. We hope money is already coming in.