BILLmanager has an open API to communicate with third-party services. It allows you to integrate the billing system with your website.
The API enables to register clients in the billing system directly from your website. Alternatively, your clients can order services from the website and they will be redirected to BILLmanager for payment. The system can also upload and update the cost of the services from BILLmanager to the website automatically. It improves the level of user-friendliness for clients and increases your website conversion rate.
Use the following API requests to integrate BILLmanager with the website.
Enabling reCATPCHA for BILLmanager integrated with a website may disturb the normal operation of the billing system and website. To avoid this, add reCAPTCHA with the same keys as in BILLmanager. Read more in Integration with a website with reCAPTCHA.
All requests to BILLmanager API are made through the standard protocol (HTTP). Responses can be either in the XML or JSON form. To specify the format, add '&out=xml', '&out=json' or '&out=sjson' to your API request.
We use the following definitions in our examples below:
- DOMAIN — BILLmanager server domain name.
- PRICELIST_ID — tariff plan id.
- ADDON_ID — tariff plans add-on id.
- PERIOD_ID — payment period id. Trial: -100, day: -50, lifetime: 0. If the value is more than 0, then the period length is specified in months.
- ITEM_id — service id.
- ACCOUNT_ID — client id.
- PARTNER_ID — partner id.
- COUNTRY_ID — country id in "Countries".
- PROJECT_ID — provider id. In "BILLmanager" version it is 1.
- ITEMTYPE_INTNAME — internal (service) product type name. You can check the values in the section Product types, the Internal name field.
By default, the column id is hidden in most lists. To display this column, click the Adjust the table settings button and activate the id flag:
The system redirects a new client from your website to the registration form:
To register a user on the website without redirecting to BILLmanager, use the register function. A remote call of this function will register a new client in the billing system. The function has the following parameters:
- sok = ok — save data
- email — login and email of a new client
- passwd — password of a new client
- realname — client name
- phone — phone number
- conditions_agree set to on, if a client has to agree to a service agreement at the registration process
- offer_xxx set to on, if a client has to agree to a formal offer at the registration process
- country — country id according to BILLmanager directory, optional
- state — country id according to BILLmanager directory, optional
- project — provider id. In the version"BILLmanager" it equals 1;
- recovery set to on, if you want to send a password reset notification in the registration email
- _ga — Google Analytics id, optional
- partner — if you use the affiliate program, the website should remember 'PARTNER_ID' in case a client was referred by the referral link. Usually, this parameter is kept in cookies.
- sesid — only if you use the affiliate program. This is the click identifier.
tzoffset — time zone offset off GMT, optional. in BILLmanager it can be set via JavaScirpt:
BILLmanager will return user.id — the id of the newly created client, and account.id — the id of the registered client.
To authorize a client in BILLmanager, use the auth function with the following parameters:
- username — login, Username field in the section Clients. Usually, it coincides with the email registered by the client;
- password — password of the user;
- lang — a language of BILLmanager interface;
- project — provider id. In "BILLmanager" version = 1.
In order to understand what account was used for the client authorization, use the whoami function. The function returns the code of an authorized client and his name and surname.
To automatically upload tariffs prices from BILLmanager to the website, use the pricelist.export function with the following parameters:
- elid=PROJECT_ID — Provider id in BILLmanager.
onlyavailable — Show only tariff plans that are available for order.Details
For example, there are two tariff plans in BILLmanager: "VPS for all" and "VPS for partner". VPS for all is available to all customers of the service provider. "VPS for partner" is available only to the customers from the group"Partners". The API-request without authorization in BILLmanager and with the parameter
onlyavailable="yes"will not show the tariff "VPS for partner". The API-request without authorization and with the parameter onlyavailable="off" will show the tariff "VPS for all" and "VPS for Partner".
- pricelist — Tariffs plan ids separated by commas. They are to be specified only if you need to get data from a certain tariff plan.
- addonitemtype — Id of product type add-ons to tariff plans. They are specified only if you need to get data only from certain add-ons.
- itemtype — Product type id. They are specified only if you need data on tariff plans of a certain type.
- exclude_pricelist — Tariff ids which are excluded from the function output, separated by commas.
- othercurrency — ISO code of the currency in which you would like to bill clients for tariffs and add-ons if you need the additional output in another currency different from the provider's currency. It is converted according to the current exchange rate in BILLmanager.
- out — data output format. Possible values: "json" and "xml".
This function returns the cost of tariffs and add-ons in the selected format.
How to retrieve information about all tariff plans
To retrieve information about all tariff plans including disabled ones, use the function pricelist.export with the parameter pricelist.
To perform this operation you must log in to BILLmanager with administrator permissions.
Receive the ID of all tariff plans. Eg., you can use the function pricelist:
Use the function pricelist.export with the parameter pricelist:Where
domain.com — the domain or public IP address of the server with BILLmanager.
id_list — all ID of tariff plans created in BILLmanager, separated by commas.
Usually, a client chooses the service and its configuration directly on the provider's website. Clicking on Order or Pay for the service buttons on the website will redirect him to the billing system to complete the order. If the client is not authorized in the system, BILLmanager will suggest registering or logging in under the existing account. After log in/sign up the client will be automatically redirected to the billing system order page.
Client registration link
You can redirect clients to different ordering pages:
- tariff plan page, payment period, tariff plan parameters and payment processing page;
- tariff plan page with a specific payment period. The client has to select tariff parameters and then make a payment;
- tariff plan page with a specific payment period and selected parameters. The client only has to make a payment.
Tariff plan order link
The link to the page where your client can select a tariff plan:
- startpage — page/list that will open after registration/login
- startform — service order form that will open after registration/login
- pricelist — tariff plan id
- project — provider id
The URL standard adds some limits to the symbols you can use. In this regard, you need to encode all links to the URL format; otherwise, the links might be displayed incorrectly.
In the section "Service order" only coded links are used. We can only recommend to use them in such a format.
The example of a link to the shared hosting tariff plan (startform=vhost.order):
Link to the order page with specific tariff plan and selected payment period
BILLmanager automatically generates tariff plan order links. You can find them if the section Tariff plans → Edit →section URLs.
You can also pass add-ons addon_N=xxx, where N is add-on id, xxx is resource value:
- integer add-ons — integer value of the resource that a client orders
- add-on specified by enumeration — id of the enumeration element
- "client can choose" add-on — id of the add-on added to the main addon. The value of the resource that a client orders shall be passed in the parameter addon_N
You can find the add-on id in Tariff plans → Options → "Id" field.
Tariff plan order page with selected parameters:
The example of shared hosting (startform=vhost.order.param) with id 2 (pricelist=2). Set add-on value "Web domain limit" to 15 (addon_5=15) and add-on value "Disk space" to 2048 (addon_3=2048).
Service payment link
If you need to redirect your client directly to the cart or to the payment page, you need to edit the following parameters: the starform parameter value shall be changed to quickforder, parameter redirect parameter with basket (redirect to cart) value or payment (redirect to service payment) is added.
You can redirect your client to the cart by using this link:
Alternatively, you can redirect a client to the page where he/she can select a payment method:
Domain order link
Domain order link requires parameters in the 'redirect' parameter:
- checked_domain — a list of the checked domains with additional parameters. The format:
- The '-' symbols in a domain name are changed into '_', '.', is changed into '____________'
- A domain status separated with ':' will be added to the resulting value:
- 0 — not checked,
- 1 — available,
- 2 — in use,
- 3 — error defining status,
- 4 — domain is registered in BILLmanager.
- For domain registration use value — 1 as its status, 3 — for transfer.
- A tariff id separated with ':' will be added to the resulting value.
Domain name selection identifier (0 — not selected, 1 — selected) separated with ':' will be added to the resulting value.
- startform=domain.order.contact — redirect a client to BILLmanager to fill out the information
- domain_action — 'register' for registration of a new domain name, 'transfer' for domain transfer
- domain_name — registered domain name
- selected_domain — domain name encoded as described above
- selected_pricelist — id of the selected tariff plan
When passing several values to 'checked_domain', 'selected_domain' and 'selected_pricelist', values are separated with ','.
Example of the link using "redirect" parameter:
Calculating order price
Function pricelist.calculate allows to show the price for a certain service and certain add-ons:
To add the cost of the add-on to the total amount of the order, you need to add the addon parameter to the query:
addon_XXX=VALUE — additional resources where:
- XXX — Id of the tariff add-on, ADDON_ID.
- VALUE — the amount of the allocated resource.
Checking promo code
You can place a promo code field (to get a discount) on your website. To check the availability of such code in the billing system, you can use promotion.promocode.check command:
You can use callback for json to send requests to BILLmanager API: