Request for completion in partial amount, monetary funds, shopping cart (depositOrder)

The request used for debiting the full pre-authorized amount is depositOrder. This operation can be performed provided that the merchant has the corresponding permissions in the system.

Use the following URL to connect to the Test Service (WSDL):
https://3dsec.sberbank.ru/payment/webservices/merchant-ws?wsdl.

When orders are completed, the cart is passed in the element deposititems.

In the case of completing an order with a full pre-authorized amount, passing the cart data is optional.
The operation completion amount in the cart must not exceed the pre-authorized amount of the order.
When completing an order for an amount that differs from the amount of the pre-authorization (apart from passing the 0 value), the data about the cart of items must mandatory be passed.
Prices of all the items in the cart must be specified in the same currency (if the currency of items is to be specified) and must match the currency of the original order. For Sberbank «Spasibo» the order currency must be Russian rubles (643-RUB).
It is prohibited to pass in the cart new items, which are missing from the original order. A check is carried out whether given item in the request cart is present in the original order. The positionId, name, and itemCode must match. If at least one value does not coincide, it is considered that the line item is missing from cart in the registration order.
The value of the quantity element in the cart of the completion request must not exceed the value of the same parameter in the cart of the registration order request.
The itemAmount element value of the items block must not exceed the value of the same parameter in the original order.
A passed value of the quantity parameter is to be checked for each line item. If the value is too large or too small, the request will fail.
All the parameters of the cart are to be checked for meeting the required format (length).

If at least one of the above conditions is not met, the order completion request is considered incorrectly formed and the payment gateway returns an error.

In this document, the following data type conventions are used when describing request and response parameters:

A<n> – a sequence of Latin letters of length <n>;
A..<n> – a sequence of Latin letters with a length not exceeding <n>;
N<n> – a sequence of digits of length <n>;
N..<n> – a sequence of digits with a length not exceeding <n>;
AN<n> – a sequence of Latin letters and numbers of fixed length <n>;
AN.. <n> – a sequence of Latin letters and numbers with a length not exceeding <n>;
ANS<n> – a sequence of Latin letters, numbers and characters of fixed length <n>
ANS.. <n> – a sequence of Latin letters, numbers and characters with a length not exceeding <n>;
UTC – date and time, in this case: the date must be passed without specifying the time zone, Moscow time, for the SOAP protocol, the standard encoding xs: dateTime is used.

Request parameters

Name	Type	Mandatory	Description	FFD version
`orderId`	ANS36	Yes	Identifier of the order in the payment system. It is unique within the system. The identifier is missing if the order registration failed due to an error detailed in errorCode.	All versions.
`depositAmount`	N..5	Yes	The amount to be charged in the currency of the order (in minimum currency units). The amount must coincide with the total amount to be charged for all items in the cart for the completion operation. Note: The withdrawal amount is indicated only in money.	All versions.
`language`	A2	No	Language code in accordance with ISO 639-1. If this parameter is not specified, it is considered that the language is Russian. An error message will be returned in this language.	All versions.
`depositItems`	Not applicable	Yes	Tag with the attributes of the cart items. Nested tags are described below. (See description.)	All versions.

deposItitems

deposItitems contains the following elements.

A parameter included in a block and indicated as mandatory is only mandatory within that block. If the section is optional and missing, then the parameters included in it should not be passed.

Name	Type	Mandatory	Description	FFD version
`items`	Not applicable	Yes	An element of the array containing attributes of an item in the cart. The description of the attributes is given below. (See description.)	All versions.

items

A parameter included in a block and indicated as mandatory is only mandatory within that block. If the section is optional and missing, then the parameters included in it should not be passed.

Name	Type	Mandatory	Description	FFD version
`positionId`	ANS..12	Yes	Unique identifier of a line item within the order cart.	All versions.
Name `name` Type ANS..100 Description REST Name or the description of an item in any format. Use - to pass \ use \«- to pass » REST Online Lending For Online Lending functionality, it's necessary to specify a description of the line item in accordance with the Yandex.Market catalog, subject to the following requirements: The following words and character sequences are not allowed: file, exec, insert, as, select, or, procedure, limit, order, and, or, by, asc, desc, delete, update, distinct, having, truncate, replace, handler, like, regex, tz_offset, to_timestamp_tz, bfilename, union, sql-command, abort, alter, analyze, begin, audit, checkpoint, close, cluster, comment, commit, copy, create, deallocate, declare, delete, drop, end, execute, explain, fetch, grant, insert, lock, move, noaudit, notify, prepare, reindex, rename, reset, revoke, rollback, savepoint, select, set, show, shutdown, start, truncate, unlisten, update, vacuum The following special characters are not allowed: ' & – # % \| ; = WS Name or the description of an item in any format. Use - to pass \ use \«- to pass » WS Online Lending For online crediting functionality it's necessary to specify a description of the good item in accordance with the Yandex.Market.	ANS..100	Yes	Name or the description of an item in any format. Use - to pass \ use \«- to pass »	All versions.
`itemDetails`	Not applicable	No	Additional block containing the parameters describing a line item. The description of the attributes is given below. The field size limit is 1024 bytes. (Go to description.)	All versions.
`quantity`	N..18	Yes	Element describing the total of items of one `positionId` and its unit of measurement The description of the attributes is given below. (Go to description.)	All versions.
`itemAmount`	N..18	Yes	The sum of the cost of all line items of one `positionId` in minimum currency units. Passing `itemAmount` is mandatory only if the `itemPrice` parameter was not passed. Otherwise passing of `itemAmount` is not required. If both parameters – itemPrice and itemAmount – are passed. then itemAmount must be equal to itemPrice * quantity, otherwise, the request will result in an error. When calculating itemAmount = itemPrice*quantity parameter, the result is rounded up to the second digit after the decimal point. For example, if the calculation result is 100.255, then final value will be 100.26.	All versions.
`itemCurrency`	N3	No	Currency code of a line item according to ISO 4217. If the parameter is not specified, it is considered to be equal to the order currency.	All versions.
`itemCode`	ANS..100	Yes	Number (identifier) of a line item in the store system.	All versions.
`tax`	Not applicable	Only if the Merchant is connected to fiscalization service	An additional tag with attributes describing the tax. Nested tags are described below. (Go to description.)	All versions.
`itemPrice`	N..18	Only if the Merchant is connected to fiscalization service	The price of one line item of one `positionId` specified in minimum currency units. Mandatory for merchants using fiscalization. itemPrice cannot be less than 0. itemPrice may be either string or integer.	All versions.
`itemAttributes`	See description.	Only for stores with enabled fiscalization settings	Tag that serves to pass a set of attributes of the line item. Attributes must be specified as follows. <attributes name="attribute_name_1">attribute_value_1</attributes> <attributes name="attribute_name_2">attribute_value_2</attributes> See description below.	1.05 and later versions.

itemAttributes

Name	Type	Mandatory	Description	FFD version
`paymentMethod`	N..2	Yes	Payment type. Possible values: `1` – full pre-payment before the delivery date of the payment subject; `2` – partial pre-payment before the delivery date of the payment subject; 3 – advance payment; `4` – full payment on the delivery date of the payment subject; `5` – partial payment for the payment subject on the delivery date followed by payment on credit; `6` – delivery of the payment subject on the delivery date without payment followed by payment on credit; `7` – payment for the payment subject after its delivery using payment on credit. Values are passed in the following priority (indicated in descending order of priority): Shopping cart from API request. Fiscalization settings in your personal account. Default values. For paymentMethod, the default value is 1 (full prepayment before the transfer of the payment item).	1.05 and later versions.
`paymentObject`	N..2	Yes	Type of item being paid for. Possible values: `1` – product; `2` – excisable product; `3` – work; `4` – service; `5` – gambling bet; `6` – gambling winnings; `7` – lottery ticket; `8` – lottery winnings; `9` – intellectual property; `10` – payment; `11` – agent's fee; `12` – several subjects; `13` – other payment subject. * `14` – property rights; `15` – non-operating income; `16` – insurance premiums: on the amount of expenses that reduce the amount of tax (advance payments) in accordance with paragraph 3.1 of Article 346.21 of the Tax Code of the Russian Federation; `17` – sales tax; `18` – resort tax. Values are passed in the following priority (indicated in descending order of priority): Shopping cart from API request. Fiscalization settings in your personal account. Default values. The default value for paymentObject is 1 (item).	1.05 and later versions.
`nomenclature`	ANS	yes (if `markQuantity` is passed)	Trade item code in text representation. Maximum length – 32 bytes.	1.05 and later versions.
`markQuantity` (Go to description.)		No	Fractional quantity of the labeled item.	1.2 and later versions.
`userData`	ANS..64	No	Value of user details. May be transferred only after approval by Federal Tax Service.	1.05 and later versions.
`agent_info.type`	N..2	Mandatory if `agent_info` object is passed.	Agent type. The following values are available: `1` – banking payment agent; `2` – banking payment subagent; `3` – payment agent; `4` – payment subagent; `5` – attorney; `6` – commission agent; `7` – other agent.	1.05 and later versions.
`agent_info.paying.operation`	ANS..24	No	Name of the transaction of the paying agent.	1.05 and later versions.
`agent_info.paying.phones`	array ANS..19	No	Phone numbers array of the payments agent in +N format.	1.05 and later versions.
`agent_info.paymentsOperator.phones`	Array ANS..19	No	Phone numbers array of the payments operator in +N format.	1.05 and later versions.
`agent_info.MTOperator.phones`	array ANS..19	No	An array of Money Transfer operator phone numbers in +N format.	1.05 and later versions.
`agent_info.MTOperator.name`	ANS..64	No	Money Transfer operator name.	1.05 and later versions.
`agent_info.MTOperator.address`	ANS..256	No	Money Transfer operator address.	1.05 and later versions.
`agent_info.MTOperator.inn`	N10..12	No	Money Transfer operator TIN.	1.05 and later versions.
`supplier_info.phones`	Array ANS..19	No	An array of supplier phone numbers in +N format.	1.05 and later versions.
`supplier_info.name`	ANS..256	No	Supplier name.	1.05 and later versions.
`supplier_info.inn`	N10..12	No	Supplier TIN.	1.05 and later versions.

quantity

quantity contains the following elements.

Name	Type	Mandatory	Description	FFD version
`measure`	ANS..20	Yes	The unit of measurement for the quantity of line item instances.	All versions.

If the FFD is version 1.2 or later, then the following parameters are passed here:

Name	Type	Mandatory	Description	FFD version
`value`	N1	Yes	Quantity of line items in given `positionId`. For FFD version 1.2+, the value is always 1.	1.2 and later versions.
`measure`	N..3	Yes	Unit of measurement for the quantity of the payment subject. In case of FFD version 1.2+, if the 'nomenclature' and 'markQuantity' parameters are passed, the value is always 0. In other cases, it can have some value.	1.2 and later versions.

Possible values of measure

Value	Description
0	Used for payment subjects that can be sold individually or in units (as well as in the event that the payment subject is a product subject to mandatory labeling with an identification tool (which can be known from `mark_code` being passed))
10	Gram
11	Kilogram
12	Ton
20	Centimeter
21	Decimeter
22	Meter
30	Square centimeter
31	Square decimeter
32	Square meter
40	Milliliter
41	Liter
42	Cubic meter
50	Kilowatt hour
51	Gigacalorie
70	Day (24h)
71	Hour
72	Minute
73	Second
80	Kilobyte
81	Megabyte
82	Gigabyte
83	Terabyte
255	Applicable when using other units of measurement

markQuantity

Parameters of markQuantity tag:

A parameter included in a tag and indicated as mandatory is only mandatory within that tag. If the tag itself is not mandatory and is not passed, its included parameters should not be passed.

Name	Type	Mandatory	Description
`numerator`	N..12	yes	The numerator of the fractional part of the payment subject.
`denominator`	N..12	yes	The denominator of the fractional part of the payment subject.

itemDetails

'itemDetailscontains the following elements.






A parameter included in a block and indicated as mandatory is only mandatory within that block. If the section is optional and missing, then the parameters included in it should not be passed.



	
	
		 Name   Type   Mandatory    Description   FFD version 
	
	
	
		 





itemDetailsParams





 





ANS..255





 No  





Parameter describing additional information regarding a line item. The description of the attributes is given below.







 (Go to description.) 

 





All versions.

==== itemDetailsParams ==== 'itemDetailsParams contains the following elements.

Name	Type	Mandatory	Description	FFD version
Name `name` Type AN..255 Type2 ANS..255 Description REST Name of the parameter describing the details of a line item WS Name of the parameter describing the details of a line item	AN..255	Yes	Name of the parameter describing the details of a line item	All versions.

Name	Type	Mandatory	Description	FFD version
`itemDetailsParams`	ANS..255	No	Parameter describing additional information regarding a line item. The description of the attributes is given below. (Go to description.)	All versions.

tax

tax contains the following elements.

A parameter included in a block and indicated as mandatory is only mandatory within that block. If the section is optional and missing, then the parameters included in it should not be passed.

Name	Type	Mandatory	Description	FFD version
`taxType`	N..2	Yes	VAT rate. The following values are available: `0` – without VAT; `1` – VAT at rate of 0%; `2` – receipt VAT at rate of 10%; `4` – receipt VAT at calculated rate of 10/110; `6` – receipt VAT at rate of 20%; `7` – receipt VAT at calculated rate of 20/120. If the cart and fiscalization data are not included in the request, then the default values specified in the personal account are passed to the Fiscal Data Operator (see User Manual for personal account).	All versions.
`taxSum`	N..18	Yes	Amount of the tax calculated by the merchant. The amount is specified in minimum currency units	All versions.

Response parameters

Name	Type	Mandatory	Description	FFD version
`errorCode`	N3	Yes	Error code.	All versions.
`errorMessage`	AN..512	No	Error description in the language passed in the `language` parameter in the request.	All versions.

Error codes

Value	Description
0	The request has been processed without system errors.
5	The deposit amount must be equal to zero or not less than one roble.
5	Access denied.
5	The user must change the password.
6	Wrong order number.
6	`[orderId]` is empty.
7	Payment must be in the correct state.
7	System error.
8	The deposit amount exceeds the amount on order registration.
8	`[depositItems.items.currency]` the currency in the cart does not match the order currency.
8	`[depositItems.totalAmount]` the sum of items in the cart does not match the total.
8	`[items.item.position]` the original order does not contain a heading with this number.
8	`[refundItems.item.quantity.value]` Too high or too low value.

Examples

Request example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
   <soapenv:Header/>
   <soapenv:Body>
      <mer:depositOrder>
         <order language="ru" orderId="76d7885f-562a-4bac-abc3-18ecaaaca797" depositAmount="20777">
            <!--Optional:-->
            <depositItems>

               <!--Zero or more repetitions:-->
                <items positionId="1">
                     <name>Metzeler Enduro 3 Sahara</name>
                     <!-- Optional: -->
                     <itemDetails>
                        <!-- Zero or more repetitions: -->
                        <itemDetailsParams name="brand">Metzeler</itemDetailsParams>
                        <itemDetailsParams name="radius">17inch</itemDetailsParams>
                     </itemDetails>
                     <quantity measure="pieces">1</quantity>
                     <itemAmount>7777</itemAmount>
                     <itemCurrency>643</itemCurrency>
                     <itemCode>T-M-14</itemCode>                    
                     <tax>
                        <taxType>1</taxType>
                        <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>7777</itemPrice>
                  </items>

                  <items positionId="2">
                     <name>Universal Mirror Enduro</name>
                     <!-- Optional: -->
                     <itemDetails>
                        <!-- Zero or more repetitions: -->
                        <itemDetailsParams name="brand">Noname</itemDetailsParams>
                        <itemDetailsParams name="diameter">12mm</itemDetailsParams>
                     </itemDetails>
                     <quantity measure="pieces">1</quantity>
                     <itemAmount>5000</itemAmount>
                     <itemCurrency>643</itemCurrency>
                     <itemCode>NM-15</itemCode>                     
                     <tax>
                        <taxType>1</taxType>
                        <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>5000</itemPrice>
                  </items>

                  <items positionId="3">
                     <name>Warm Grips</name>
                     <!-- Optional: -->
                     <itemDetails>
                        <!-- Zero or more repetitions: -->
                        <itemDetailsParams name="brand">Noname</itemDetailsParams>
                     </itemDetails>
                     <quantity measure="pieces">1</quantity>
                     <itemAmount>8000</itemAmount>
                     <itemCurrency>643</itemCurrency>
                     <itemCode>G-16</itemCode>                     
                     <tax>
                        <taxType>1</taxType>
                        <taxSum>111</taxSum>
                     </tax>
                     <itemPrice>8000</itemPrice>
                  </items>

            </depositItems>

            <!--Zero or more repetitions:-->
            <params name=" " value=" "/>
         </order>

      </mer:depositOrder>
   </soapenv:Body>
</soapenv:Envelope>

Пример ответа

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:depositOrderResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
         <return errorCode="0"/>
      </ns1:depositOrderResponse>
   </soap:Body>
</soap:Envelope>

Инструменты страницы

Request for completion in partial amount, monetary funds, shopping cart (depositOrder)

Request parameters

deposItitems

items

Name

Type

Description

REST

REST Online Lending

WS

WS Online Lending

itemAttributes

quantity

markQuantity

itemDetails

Name

Type

Type2

Description

REST

WS

tax

Response parameters

Error codes

Examples

Request example

Пример ответа