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: 1 — month 3 — 3 months 6 — 6 months 12 — year 24 — 2 years 36 — 3 years	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: on off	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: on off	force_use_new_cart=on
out	Response format	Assumes one of the following values: xml xjson devel text	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 5 is the addon code, 10 - value. 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: on off	skipbasket=on

* — mandatory parameter

Example of a request to add an item to cart:

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'

Example with values

The response will contain the position id of the new cart lineitem.id.

Response example

<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)

Examples

<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:

Request example

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.

Response example

<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: on off	store_paymethod=on

* — mandatory parameter

Request example

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'

Response example

<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>

Details