New Order API
The examples are based on logging in as administrator and then performing the functions with client permissions. You can learn about authorization methods in the Service management via API article.
Glossary
cart — new cart. Each client has one shopping cart for each provider. For example, a client belongs to one provider, therefore it has one shopping cart and all items the client orders go into that cart.
lineitem.id — new cart item.
order — one or more items from the cart, for which a payment is created.
Adding an item to cart
The API of a new order is similar to the API of the old order, so the values of addons and parameters are passed in the same way, whereas additional and differing parameters are described in the table below.
For SSL and Domain product types, use functions like "{ITEMTYPE}.order.param". To add these services to the cart via API using quick order, use the old order API with parameters "clicked_button=quickbasket" and "force_use_new_cart=on".
Name | Description | Meaning | Example |
---|---|---|---|
func * | Order function | v2.{ITEMTYPE}.order.param {ITEMTYPE} — internal product type name | func=v2.soft.order.param func=v2.vds.order.param func=v2.dedic.order.param |
order_period * | Order period | Assumes one of the following values:
| order_period=1 |
pricelist * | Tariff ID | Integer | pricelist=111 |
sok * | Confirm the operation | ok | sok=ok |
clicked_button * | Operation subtype | order | clicked_button=order |
autoprolong | Enable auto-renewal Flag | Assumes one of the following values:
| autoprolong=on |
datacenter | ID of the data center where the service will be opened | Integer | datacenter=2 |
force_use_new_cart | Enable use of the new shopping cart Flag | Assumes one of the following values:
| force_use_new_cart=on |
out | Response format | Assumes one of the following values:
| out=xml |
addon_{ADDON_PRICELIST_ID} | Addon value | The value depends on the setting of the addon in the tariff plan Tariff addons are passed through the API via the addon_ parameter. For example, addon_5=10, where
To find the addon code, enter Products → Tariff plan → Options → Id field | addon_12=126 |
skipbasket | Enable payment for the service from the personal account without placing it in the cart Flag | Assumes one of the following values:
| skipbasket=on |
* — mandatory parameter
Пример запроса добавления позиции в корзину:
curl -X POST -k https://domain.com/billmgr \
-d 'authinfo=admin_login:admin_password' \
-d 'su=client_login' \
-d 'out=xml' \
-d 'sok=ok' \
-d 'force_use_new_cart=on' \
-d 'func=v2.{ITEMTYPE}.order.param' \
-d 'datacenter={DATACENTER_ID}' \
-d 'pricelist={PRICELIST_ID}' \
-d 'addon_{ADDON_PRICELIST_ID}={ADDON_VALUE}' \
-d 'order_period={PERIOD}' \
-d 'clicked_button=order'
curl -X POST -k https://domain.com/billmgr \
-d 'authinfo=admin_login:admin_password' \
-d 'su=client_login' \
-d 'out=xml' \
-d 'sok=ok' \
-d 'force_use_new_cart=on' \
-d 'func=v2.vds.order.param' \
-d 'datacenter=1' \
-d 'pricelist=2' \
-d 'addon_2=10' \
-d 'order_period=1' \
-d 'clicked_button=order'
The response will contain the position id of the new cart lineitem.id.
Пример ответа
<?xml version="1.0" encoding="UTF-8"?>
<doc ...>
...
<lineitem.id>497</lineitem.id>
...
</doc>
Shopping cart operations
Name | Description | Meaning | Example |
---|---|---|---|
func * | Cart functions | cart | func=cart |
clicked_button | Operation subtype | Assumes one of the following values: activate — activate the selected free items delete — delete the selected items apply_promocode — apply promocode to the entire cart, regardless of the selected items (promocode parameter is required). | clicked_button=activate clicked_button=delete clicked_button=apply_promocode |
selected | Items (lineitem) selected for transaction execution | List of integer values Separator ',' | 155, 105.106, 107. |
sok | Confirm the operation Must be specified in the request if the clicked_button parameter is present | ok | sok=ok |
promocode | Promo code Must be specified if clicked_button=apply_promocode | Promo code | promocode=IDDQD |
* — mandatory parameter
Order summary
Function: Cartorder
Returns summary information about the created order for display in the interface:
curl -X POST -k https://domain.com/billmgr \
-d 'authinfo=admin_login:admin_password' \
-d 'su=client_login' \
-d 'func=cartorder' \
-d 'elid={billorder}'
where elid is the order ID (billorder)
<?xml version="1.0" encoding="UTF-8"?>
<doc lang="ru" func="cartorder" binary="/billmgr" host="https://ubu.lxc:1500" themename="dragon" features="25d83c4f3f3fa0d69d63c201cad676d2" notify="" theme="/manimg/dragon/">
<list name="payment_info_list">
<elem is_json_array="yes">
<img img="m-account" width="20px" height="15px" sprite="yes" spritesvg="yes"/>
<profile size="h3">notav@example.com, natural person</profile>
</elem>
<elem is_json_array="yes">
<img img="card" width="18px" height="16px" spritesvg="yes"/>
<to_pay size="h3">To payment 20.00 RUB</to_pay>
</elem>
</list>
<list name="general_info">
<elem is_json_array="yes">
<position_count>1 position</position_count>
</elem>
</list>
<list name="details">
<elem is_json_array="yes">
<item>oneAddon #4176</item>
<count>1pcs.</count>
<price>
<price>
<currency>RUB</currency>
<cost>20.00</cost>
</price>
</price>
<configuration>
<header name="configuration_name" color="main">Service</header>
<header name="configuration_value" color="main">Value</header>
<header name="configuration_limit" color="main">Limit</header>
<elem is_json_array="yes">
<configuration_name>oneAddon #4176</configuration_name>
<configuration_value>Base cost</configuration_value>
<configuration_price>
<price>
<currency>RUB</currency>
<cost>10.00</cost>
</price>
</configuration_price>
</elem>
<elem is_json_array="yes">
<configuration_name>numerical</configuration_name>
<configuration_value>10 pcs.</configuration_value>
<configuration_price>
<price>
<currency>RUB</currency>
<cost>10.00</cost>
</price>
</configuration_price>
</elem>
</configuration>
<extra_info>
<elem is_json_array="yes">
<autoprolong>
<input name="autoprolong_4176" type="checkbox" msg_side="left" color_on="green" color_off="red" readonly="yes"/>
</autoprolong>
</elem>
</extra_info>
</elem>
</list>
<autoprolong_4176>off</autoprolong_4176>
<list name="help_faq">
<elem is_json_array="yes">
<link internal="no" target="_blank" name="faq_link_0">https://docs.ispsystem.com/x/9JUHBQ</link>
</elem>
<elem is_json_array="yes">
<link internal="no" target="_blank" name="faq_link_1">https://docs.ispsystem.com/x/ApYHBQ</link>
</elem>
<elem is_json_array="yes">
<link internal="no" target="_blank" name="faq_link_2">https://docs.ispsystem.com/x/LJYHBQ</link>
</elem>
</list>
<list name="help_support">
<elem is_json_array="yes">
<link name="help_support_link" internal="yes" newtab="yes">func=clientticket</link>
</elem>
</list>
<elid>689</elid>
<tparams>
<elid>689</elid>
<out>xml</out>
<func>cartorder</func>
</tparams>
<saved_filters/>
</doc>
Examples
After adding an item to the cart, different options of interaction with the client are possible. The following examples are given below:
- displaying a shopping cart form where the client will proceed to checkout on their own;
- free item activation;
- creating an order and paying for it.
Displaying the shopping cart form
To display the shopping cart form, send the user to a link in the format:
https://domain.com/billmgr?startform=cart&selected={lineitem.id}
By clicking on the link the client will be directed to the cart with the selected item (lineitem.id) and its price, and can proceed to payment for the ordered item or continue shopping.
Use this interaction option if:
- a payer is required for payment, but the client has not created one yet. When placing an order, the client will specify all the necessary data for the payer through the billing platform interface;
- phone or mail confirmation is required before payment. When placing an order, the client will be prompted to undergo verification.
Free item activation
You can activate a free item in two ways: specify skipbasket=on when ordering a service or use a request:
Пример запроса
curl -X POST -k https://domain.com/billmgr \
-d 'authinfo=admin_login:admin_password' \
-d 'su=client_login' \
-d 'out=xml' \
-d 'sok=ok' \
-d 'func=cart' \
-d 'selected={lineitem.id}' \
-d 'clicked_button=activate'
If the request is successful, the items will be combined into an order (billorder) and will be processed shortly.
Пример ответа
<?xml version="1.0" encoding="UTF-8"?>
<doc ...>
...
<billorder saveoutput="yes">555</billorder>
...
</doc>
Order creation and payment
To receive the payment link you need to create and confirm the order of the selected items (lineitem).
Name | Description | Meaning | Example |
---|---|---|---|
func * | Order creation function for selected items | cartorder.create.confirm | func=cartorder.create.confirm |
elid * | Items (lineitem) selected for ordering | List of integer values separator ',' | 155, 105.106, 107. |
sok * | Confirm the operation | ok | sok=ok |
Payment method * paymethod_id or storedmethod_id Note: The parameters are mutually exclusive, specify only one of them in the request | paymethod_id — payment method ID. Additional parameters may be required for the payment method, e.g. for Yookassa you need to specify payment_method For the definition of such parameters, see Interaction via API storedmethod_id — ID of the saved client's payment method | Integer Specify paymethod_id=0 to use personal account as a payment method | paymethod_id=15 storedmethod_id=455 |
profile_id | Payer ID Specified if a payer is required for the selected payment method | Integer | profile_id=42 |
store_paymethod | If the parameter assumes the value "on" and the payment method supports the option to save the selected payment method, the method of this payment will be saved for the client Flag | Assumes one of the following values:
| store_paymethod=on |
* — mandatory parameter
Пример запроса
curl -X POST -k https://domain.com/billmgr \
-d 'authinfo=admin_login:admin_password' \
-d 'su=client_login' \
-d 'sok=ok' \
-d 'func=cartorder.create.confirm' \
-d 'elid=506' \
-d 'paymethod_id=3' \ // ЮKassa
-d 'profile_id=72' \
-d 'payment_method=bank_card'
Пример ответа
<?xml version="1.0" encoding="UTF-8"?>
<doc ...>
...
<billorder saveoutput="yes">663</billorder>
<payment_id saveoutput="yes">755</payment_id>
<ok type="blank" on_blank_redirect_action="func=cartorder&elid=663">/mancgi/ycpayment?elid=755</ok>
...
</doc>
billorder — ID of the created order
payment_id — ID of the created payment
ok — contains a link to payment of the payment, similar to the old payment
on_blank_redirect_action — contains a link to the form of the order being paid