Request for completion in partial amount, monetary funds, shopping cart (deposit.do)

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

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

userName

AN..30

Yes

Login of the service account of the merchant. If login and password are used for authentication during token registration, then the token parameter does not need to be passed.

All versions.

password

AN..30

Yes

Merchant's service account password. If login and password are used for authentication during token registration, then the token parameter does not need to be passed.

All versions.

orderId

ANS36

Yes

Identifier of the order in the payment system. It is unique within the system. Missing if order registration failed due to an error detailed in ErrorCode.

All versions.

amount

N..12

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 in the ISO 639-1 encoding. If the language is not specified, the default language defined in the store settings is used.

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 block itself is not mandatory and is not passed, its included parameters should not be passed.

Name Type Mandatory Description FFD version

items

Not applicable

Yes

Array of blocks describing line items in the cart. Information about every line item in the cart is passed in a separate block that is included in items.

Do not use «‘)«character combination inside this section, or it will cause an error on the gateway side.

(See description.)

All versions.

items

A parameter included in a block and indicated as mandatory is only mandatory within that block. If the block itself is not mandatory and is not passed, its included parameters 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

yes – for fiscalization (for stores without fiscalization settings this parameter is optional)

An additional tag with attributes describing the tax. Nested tags are described below.

(Go to description.)

All versions.

itemPrice

N..12

yes – for fiscalization (for stores without fiscalization settings this parameter is optional)

The cost of one line item 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.

No

Block containing the attributes of the item.

(Go to description.)

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

  1. Shopping cart from API request.
  2. Fiscalization settings in your personal account.
  3. 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):

  1. Shopping cart from API request.
  2. Fiscalization settings in your personal account.
  3. 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. POST method must be used for passing this parameter. Example: «supplier_info.phones»: «+79123456789, +79123456790, +79123456791, +79123456792, +79123456793, +79123456794»

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.

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

Name Type Mandatory Description

value

N..18

Yes

Quantity of line items in given positionId. Use a decimal point as a separator in fractions.

measure

ANS..20

Yes

The unit of measurement for the quantity of line item instances.

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

'itemDetails contains the following elements. A parameter included in a block and indicated as mandatory is only mandatory within that block. If the block itself is not mandatory and is not passed, its included parameters should not be passed.

Name Type Mandatory Description FFD version

itemDetailsParams

ANS..255

No

Additional information on a line item. The parameter represents an array of blocks each of which contains information on a certain characteristic of the line item.

(Go to description.)

All versions.

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

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

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.

tax

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

Name Type Mandatory Description

taxType

N..2

No

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

taxSum

N..18

No

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. Can be missing if the result has not caused an error.

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

Specified completion amount does not match the full amount of the order. The cart data is mandatory to complete the operation with a partial pre-authorization amount.

8

[items.item.position] the original order does not contain a line item with this number.

8

[orderBundle.cartItems.item.quantity.value] Too high or too low value.

Examples

POST request example

userName=username-api&password=testPwd&amount=23500&returnUrl=http://ya.ru&orderId=b089befe-127a-75e4-a68f-918c0128092a&depositItems={"items":[{"positionId":1,"name":"По-аджарски \"Лодочка\" SMALL","quantity":{"value":"1","measure":"0"},"itemCode":"270_235.00","itemPrice":23500,"tax":{"taxType":0,"taxSum":0},"itemAttributes":{"attributes":[{"name":"nomenclature","value":"010463003407001221CMK45BrhN0WLf"},{"name":"paymentMethod","value":"1"},{"name":"paymentObject","value":"30"},{"name":"agent_info.type","value":"7"},{"name":"agent_info.paying.operation","value":"test operation"},{"name":"agent_info.paying.phones","value":"%2B79161234123"},{"name":"agent_info.paymentsOperator.phones","value":"%2B79161234456"},{"name":"agent_info.MTOperator.phones","value":"%2B79161234789"},{"name":"agent_info.MTOperator.name","value":"MT operator"},{"name":"agent_info.MTOperator.address","value":"Moscow"},{"name":"agent_info.MTOperator.inn","value":"8634330204"},{"name":"supplier_info.phones","value":"%2B79161234333"},{"name":"supplier_info.name","value":"Supplier"},{"name":"supplier_info.inn","value":"287381373424"},{"name":"excise","value":"10.0"},{"name":"country_code","value":"810"},{"name":"declaration_number","value":"12332234533"},{"name":"userData","value":"user data"},{"name":"markQuantity.numerator","value":"1"},{"name":"markQuantity.denominator","value":"2"},{"name":"sectoralItemProps[0].federalId","value":"001"},{"name":"sectoralItemProps[0].date","value":"10.10.2021"},{"name":"sectoralItemProps[0].number","value":"123/4567"},{"name":"sectoralItemProps[0].value","value":"value1"},{"name":"sectoralItemProps[1].federalId","value":"003"},{"name":"sectoralItemProps[1].date","value":"11.10.2021"},{"name":"sectoralItemProps[1].number","value":"321/4567"},{"name":"sectoralItemProps[1].value","value":"value2"}]}}]}

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

{"errorCode":"0","errorMessage":"Success"}