Request for order registration with shopping cart, Online Lending (register.do)

The request used for registering an order on payment system side is register.do. The shopping cart is passed in the orderBundle parameter. The registration request must meet the requirements below.

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

The request parameters are given in table below.

Name	Type	Mandatory	Description
`userName`	AN..30	Yes	Login of the service account of the merchant.
`password`	AN..30	Yes	Merchant's service account password.
`orderNumber`	ANS..32	Yes	Number (identifier) of the order in the store system. It is unique for every store within the Payment Gateway. If the order number is generated on the Payment Gateway side, this parameter is not mandatory.
`amount`	N..12	Yes	Payment amount in minimum currency units (kopecks, cents, etc.). Must match the total amount for all line items in the shopping cart. Before summing up all line items, the product of quantity and price for each good item is rounded to an integer. If the value is followed by 5 or greater after the decimal point, it is rounded up. Below there are examples of rounding. If quantity = 0.111, and price = 5500, then the result is 611 (610.5 rounded up). If quantity = 1.455, and price = 6900, then the result is 10040 (10039.5 rounded up). If quantity = 1.211, and price = 6988, then the result is 8462 (8462.468 rounded down). Therefore, the «amount» parameter value must be equal to the sum of the line items rounded.
`currency`	N3	Yes	ISO 4217 code of the payment currency. If not specified, default value is used.
`returnUrl`	ANS..512	Yes	The URL to which the user is to be redirected in case of a successful payment (and also in case of a failed payment where the `failUrl` parameter is not passed). The address must be specified in full including the protocol used (for example, https://test.ru instead of test.ru). Otherwise, the user will be redirected to the address of the following type: http://<payment_gateway_address>/<merchant_address>.
`failUrl`	ANS..512	No	The address to which the user is to be redirected in case of a failed payment. The address must be specified in full including the protocol used (for example, https://test.ru instead of test.ru). Otherwise, the user will be redirected to the address of the following type: http://<payment_gateway_address>/<merchant_address>. The parameter is optional. In this case, an unsuccessful payment will lead to a redirect to `returnUrl`, in the same way it happens when the payment is successful.
`description`	ANS..512	No	Description of the order in free form. To enable sending this field to the processing system, contact the technical support service.
`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.
`pageView`	ANS..20	No	The value of this parameter defines what kind of pages of the payment interface will be loaded for the Customer. The available values are: `DESKTOP` – pages designed to be displayed on desktop computers (pages with names like `payment_<locale>.html` and `errors_<locale>.html` will be searched for in the payment service archive); `MOBILE` – pages designed to be displayed on mobile devices (pages with names like `mobile_payment_<locale>.html` and `mobile_errors_<locale>.html` will be searched for in the payment service archive); If a store has created payment interface pages with arbitrary prefixes added to the names of page files, pas the value of the necessary prefix in the `pageView` parameter to load corresponding pages. For example on passing the iphone value, a search will be carried out in the archive of payment interface pages for pages with the iphone_payment_<locale>.html and iphone_error_<locale>.html names. Where: `locale` – the language of the page in ISO 639-1. For example, ru for Russian or en for English. If the parameter is missing or its value is in incorrect format, the default value is pageView=DESKTOP.
`clientId`	ANS..255	No	Identifier of the Customer in the Store system. This parameter is used for the binding functionality. May be present if the store is allowed to create bindings. Specifying this parameter when processing payments with the use of bindings is mandatory. Otherwise, a payment will be unsuccessful.
`merchantLogin`	AN..255	No	To register an order on behalf of a child Merchant, specify the Merchant login in this parameter.
`jsonParams`	String	No	Block for transferring additional parameters of the merchant. Fields of additional information for further storage are transferred in the following form. `{name1:value1,…,nameN:valueN}` These fields can be transferred to the bank processing for subsequent display in the registers. The inclusion of this functionality is possible by agreement with the bank during the integration period. If sending notifications from merchant to customer is enabled, the customer's email address must be passed in this block in the `email` parameter. The following can be passed as additional parameters: «email» – if the customer's email address is passed, it will be displayed on the payment page; `phone` – if the customer's cell phone number is passed, it will be displayed on the payment page; «backToShopUrl» – if this parameter is passed, the payment page will display a button for returning the customer to the store. Specify the address of the store's website in this parameter. «backToShopName» – the caption on the return-to-store button that will be displayed if the parameter «backToShopUrl» is passed. It is forbidden to pass reserved names in the parameter (if they are passed, the order may be rejected): sbrf_spasibo:amount_bonus sbrf_sbermiles:amount_bonus loyaltyId
`sessionTimeoutSecs`	N..10	No	Order lifetime in seconds. If the parameter is not specified, the value specified in the Merchant settings or the default value (1200 seconds = 20 minutes) will be used. If the request contains the expirationDate parameter, then the value of sessionTimeoutSecs parameter is disregarded.
`expirationDate`	UTC	No	The date and time of the order lifetime expiration. Format: yyyy-MM-ddTHH:mm:ss. If this parameter is not passed in the request, `sessionTimeoutSecs` parameter is used to determine the end of lifetime of the order.
`bindingId`	AN..255	No	The identifier of the previously created binding. Can only be used if the merchant has permission to work with bindings. If this parameter is passed in the given request, it means that: 1. The given order can be paid only using a binding; 2. The payer will be redirected to the payment page on which only entering CVC is required.
`dummy`	N4	No	Attribute for enabling the test «stub». To enable test `stub`, pass the value `true` in this parameter. If the «stub» is enabled, scenario goes as follows: The user goes to the payment page and clicks on Submit request. The user is redirected to the «stub» page, which visually duplicates the payment page. The user selects the credit term: 3 months – in this case after clicking on the Submit request button the order will be successfully registered; 6 months – in this case after clicking on the Submit request button the order will be declined.
`orderBundle`	Not applicable	Yes	Block containg the cart of items of the order. The description of the attributes is given below. (Go to description.)
`billingPayerData`	See description	No	Customer's registration data (street address, postal code). Required for AVS/AVV checks. Mandatory if «AVS/AVV use allowed» permission is enabled for merchant

By default, the following fields are passed to the Bank processing system:

orderNumber – order number in the store system;
description – order description (no more than 24 characters; %, +, carriage return \r, and line feed \n cannot be used).

billingPayerData

billingPayerData block parameters

Name	Type	Mandatory	Description
`billingCity`	AN..50	No	City registered for the card at the Issuer Bank.
`billingCountry`	AN..50	No
`billingAddressLine1`	AN..50	No	Address registered for the card at the Issuer Bank. Line 1. Mandatory if «AVS/AVV use allowed» permission is enabled for merchant.
`billingAddressLine2`	AN..50	No	Address registered for the card at the Issuer Bank. Line 2.
`billingAddressLine3`	AN..50	No	Address registered for the card at the Issuer Bank. Line 3.
`billingPostalCode`	AN..50	No	Postal code registered for the card at the Issuer Bank. Mandatory if «AVS/AVV use allowed» permission is enabled for merchant.
`billingState`	AN..50	No	State registered for the card at the Issuer Bank (ISO 3166-2).

orderBundle

orderBundle contains the following elements.

Name	Type	Mandatory	Description
`orderCreationDate`	ANS..21	No	Order creation date in the format YYYY-MM-DDTHH:MM:SS.
`customerDetails`	Not applicable	No	Block containing attributes with data about the customer. The description of the attributes is given below. (Go to description.)
`cartItems`	Not applicable	Yes	Block with the attributes of the items in the cart. The description of the attributes is given below. (Go to description.)
`installments`	No longer relevant	Conditional Mandatory when providing the buyer with the possibility Online Lending	Section where parameters of the type of online credit granting are specified. The description is given below. (Go to description.)

installments

Parameters of the installments section

Name	Type	Mandatory	Description
`productType`	A..11	Yes	Sign of buying on credit. The following values are available: CREDIT – payment on credit; INSTALLMENT – payment in installments.
`productID`	ANS..12	Yes	Use the value `10` for Online Lending.
`rightTerms`	ANS…255	No	Desired loan term in months. Multiple comma separated values can be passed. The attribute is passed if `productType = INSTALLMENT` is selected. If the parameter is filled in, only the payment terms specified in the parameter will be available to the customer. For example, if «''rightTerms'':[3,6,9]», then the customer will be able to select the terms of 3, 6 or 9 months. If this parameter is not filled in, all the terms earlier approved by the bank will be available to the customer.

customerDetails

customerDetails contains the following elements.

Name	Type	Mandatory	Description
`email`	ANS..40	No	Customer's email address.
`phone`	NS..12	No	Customer's phone number. It can be of the following format: `^((+7\|7\|8)?([0-9]){10})$`. Examples: +79000000000 89000000000 9000000000 79000000000 If the number is passed in a separate parameter and in additional parameters, the number specified in this `phone` parameter will be used.
`contact`	ANS..40	No	Customer's preferred way of communication.
`fullName`	ANS..100	No	Payer's first name, last name, and patronymic.
`passport`	ANS..100	No	The series and number of the payer's passport in the following format: `2222888888`.
`inn`	N..12	No	Taxpayer identification number. From 10 to 12 digits can be passed.
`deliveryInfo`	Not applicable	No	Block containing the attributes of the delivery address. The description of the attributes is given below. (Go to description.)

deliveryInfo

deliveryInfo contains the following elements.

Name	Type	Mandatory	Description
`deliveryType`	ANS..20	No	Delivery method.
`country`	A..2	Yes	The two-letter country code for the delivery country.
`city`	ANS..40	Yes	Delivery city.
`postAddress`	ANS..255	Yes	Delivery address.

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.

cartItems

cartItems contains the following elements.

Name	Type	Mandatory	Description
`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. (Go to description.)

items

items« contains the following elements.



	
	
		 Name   Type   Mandatory    Description  
	
	
	
		 





positionId





 





ANS..12





 Yes   





Unique identifier of a line item within the order cart.






	
	
		 






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   





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: ' & – # % | ; =







	
	
		 





itemDetails





 





Not applicable





 No   





Additional block containing the parameters describing a line item. The description of the attributes is given below.







 (Go to description.) 


	
	
		 





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


	
	
		 





itemAmount





 





N..12





 Conditional 

Mandatory when providing the customer with the possibility of Online Lending.  





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.















If all the items in the request are delivered without payment (a gift to customer), the value 0 should be passed.






	
	
		 





itemPrice





 





N..18





 Yes  





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.
















If the item is delivered without payment (a gift to customer), the value 0 should be passed.






	
	
		 





itemCurrency





 





N3





 Conditional 

Mandatory when providing the customer with the possibility of Online Lending.   





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.






	
	
		 





itemCode





 





ANS..100





 Yes   





Number (identifier) of a line item in the store system.

Name	Type	Mandatory	Description
`positionId`	ANS..12	Yes	Unique identifier of a line item within the order cart.
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	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: ' & – # % \| ; =
`itemDetails`	Not applicable	No	Additional block containing the parameters describing a line item. The description of the attributes is given below. (Go to description.)
`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.)
`itemAmount`	N..12	Conditional Mandatory when providing the customer with the possibility of Online Lending.	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. If all the items in the request are delivered without payment (a gift to customer), the value 0 should be passed.
`itemPrice`	N..18	Yes	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. If the item is delivered without payment (a gift to customer), the value 0 should be passed.
`itemCurrency`	N3	Conditional Mandatory when providing the customer with the possibility of Online Lending.	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.
`itemCode`	ANS..100	Yes	Number (identifier) of a line item in the store system.

==== quantity ====quantitycontains the following elements.



	
	
		 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.

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.

==== itemDetails ==== 'itemDetails contains the following elements.

Name	Type	Mandatory	Description
`itemDetailsParams`	ANS..255	Conditional. Mandatory when providing the buyer with the possibility of Online Lending	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.)

itemDetailsParams

'itemDetailsParamscontains the following elements.



	
	
		 Name   Type   Mandatory    Description  
	
	
	
		 





value





 





ANS..255





 Conditional. Mandatory if itemDetailsParams parameter is present.  





Additional information on a line item.






	
	
		 






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





 





ANS..255





 Conditional. Mandatory if itemDetailsParams parameter is present.  





Name of the parameter describing the details of a line item






	






===== Response parameters =====

The response parameters are given in table below.


	
	
		 Name   Type   Mandatory   Description  
	
	
	
		 





orderId





 





ANS36





 No  





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.






	
	
		 





formUrl





 





AN..512





 No   





Payment form URL to redirect the client's browser to. This parameter is not returned if the registration of the order was not successful due to the error described in errorCode.







To be able to accept payment in this way, you must have the respective rights in the system. If in doubt, contact technical support.










	
	
		 





errorCode





 





ANS..3





 No   





Error code. Can be missing if the result has not caused an error.






	
	
		 





errorMessage





 





AN..512





 No   





Error description in the language passed in the language parameter in the request.






	





===== Error codes =====


	
	
		 Error code  Error text 
	
	
	
		 1  





An order with this number has already been processed.






	
	
		 1  





Wrong order number.






	
	
		 3  





Unknown currency.






	
	
		 4  





Order number is empty






	
	
		 4  





The amount is missing.






	
	
		 4  





Empty return URL






	
	
		 4  





Password cannot be empty.






	
	
		 5  





A parameter value has been specified incorrectly.






	
	
		 5  





Access denied.






	
	
		 5  





The user is inactive.






	
	
		 7  





System error.






	
	
		 8  





A mandatory parameter of theCart  is missing .






	
	
		 8  





[depositItems.totalAmount] the sum of items in the cart does not match the total.






	
	
		 8  





The currency of the cart does not match the currency of the order.






	
	
		 8  





Incorrect format of the cart.






	
	
		 8  





[depositItems.item.quantity.value] Too high or too low value.






	





===== Examples ====


==== POST request example ====

<sxh javascript>
amount=10000000&currency=643&language=ru&orderNumber=ORDER_NUMBER&returnUrl=http://yoursite.com&jsonParams={«phone»:»+79268936532«}&sessionTimeoutSecs=86400&orderBundle={ 
  «cartItems»: {
        «items»: [
            {
                «positionId»: 1,
                «name»: «Washing machine Siemens WS12T460OE»,
                «quantity»: {
                    «value»: 1,
                    «measure»: «pcs»
                },
                «itemPrice»: «8000000»,
                «itemAmount»: «8000000»,
                «itemCode»: «78864»
            },
            {
                «positionId»: 2,
                «name»: «Service – Delivery»,
                «quantity»: {
                    «value»: 1,
                    «measure»: «pcs»
                },
                «itemPrice»: «1000000»,
                «itemAmount»: «1000000»,
                «itemCode»: «0000»
            },
			{
                «positionId»: 3,
                «name»: «something – Delivery»,
                «quantity»: {
                    «value»: 1,
                    «measure»: «pcs»
                },
                «itemPrice»: «1000000»,
                «itemAmount»: «1000000»,
                «itemCode»: «0000»
            }
        ]
    },
    «installments»: {
        «productID»: «10»,
        «productType»: «INSTALLMENT»
    }
}
</sxh>

==== Response example ====

<sxh javascript>
{«formUrl»:«https://3dsec.sberbank.ru/payment/789/payment_ru.html?
mdOrder=ece47318-19f2-466a-93cd-bdb08c1587ec»,»orderId«:«ece47318-19f2-466a-93cd-bdb08c1587ec»}
</sxh>

Name	Type	Mandatory	Description
`value`	ANS..255	Conditional. Mandatory if `itemDetailsParams` parameter is present.	Additional information on a line item.
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	ANS..255	Conditional. Mandatory if `itemDetailsParams` parameter is present.	Name of the parameter describing the details of a line item

Name	Type	Mandatory	Description
`orderId`	ANS36	No	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.
`formUrl`	AN..512	No	Payment form URL to redirect the client's browser to. This parameter is not returned if the registration of the order was not successful due to the error described in `errorCode`. To be able to accept payment in this way, you must have the respective rights in the system. If in doubt, contact technical support.
`errorCode`	ANS..3	No	Error code. Can be missing if the result has not caused an error.
`errorMessage`	AN..512	No	Error description in the language passed in the `language` parameter in the request.

Error code	Error text
1	An order with this number has already been processed.
1	Wrong order number.
3	Unknown currency.
4	Order number is empty
4	The amount is missing.
4	Empty return URL
4	Password cannot be empty.
5	A parameter value has been specified incorrectly.
5	Access denied.
5	The user is inactive.
7	System error.
8	A mandatory parameter of theCart is missing .
8	`[depositItems.totalAmount]` the sum of items in the cart does not match the total.
8	The currency of the cart does not match the currency of the order.
8	Incorrect format of the cart.
8	`[depositItems.item.quantity.value]` Too high or too low value.

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

Request for order registration with shopping cart, Online Lending (register.do)

Request parameters

billingPayerData

billingPayerData block parameters

orderBundle

installments

customerDetails

deliveryInfo

cartItems

items

Name

Type

Description

REST

REST Online Lending

WS

WS Online Lending

itemDetailsParams

Name

Type

Type2

Description

REST

WS