Request for order registration with pre-authorization, shopping cart, Online Lending (registerPreAuth.do)

The request used for registering an order on payment system side is registerPreAuth.do.

Requests for registration of an order (with- and without pre-authorization) pass the cart data in the orderBundle parameter.

Prices of all the items within the cart must be specified in one currency (if the currency of an item is to be specified); and this currency must match the currency of the order.
The sum of all line items in the shopping cart must be equal to the order amount.
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 result in an error.
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 is considered incorrectly generated and the payment gateway returns an error.

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. If login and password are used for authentication during token registration, then the `token` parameter does not need to be passed.
`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.
`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	No	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`	ANS..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.
`orderBundle`	Not applicable	Yes	Block containg the cart of items of the order. The description of the attributes is given below. (Go to description.)

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

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.)
`loyalties`	Not applicable	No	A block with attributes of bonus programs, which include items from 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`	String	Yes	The product identifier must be agreed with the bank.

customerDetails

customerDetails contains the following elements.

Name	Type	Mandatory	Description
`email`	ANS..40	See note below.	Customer's email address.
`phone`	NS..12	See note below.	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.
`deliveryInfo`	Not applicable	No	Block containing the attributes of the delivery address. The description of the attributes is given below. (Go to description.)

It is mandatory to pass one of the two parameters: email or phone.

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   





Name or the description of an item in any format.







Use 

- to pass \
use \«- to pass »










	
	
		 





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





 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.










	
	
		 





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.






	
	
		 





itemPrice





 





N..18





 Only for stores with enabled fiscalization settings   





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.

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	Name or the description of an item in any format. Use - to pass \ use \«- to pass »
`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..18	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.
`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.
`itemPrice`	N..18	Only for stores with enabled fiscalization settings	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.

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





 





AN..255





 Conditional. Mandatory if itemDetailsParams parameter is present.  





Name of the parameter describing the details of a line item

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	AN..255	Conditional. Mandatory if `itemDetailsParams` parameter is present.	Name of the parameter describing the details of a line item

==== loyalties ====loyaltiescontains the following elements.



	
		 





loyalties





 





Not applicable





 If the loyalties block was transferred  





A block with attributes of bonus programs, which include items from the cart.






	
	
		 





loyaltyProgramName





 





ANS..20





 If the loyalties block was transferred  





The name of the bonus program in which the product item is involved, you should use the value sbrf_spasibo.






	
	
		 





positionId





 





ANS..12





 If the loyalties block was transferred  





Unique identifier of a line item within the order cart.






	
	
		 





bonusAmountForDebit





 





N..18





 If the loyalties block was transferred  





The total amount of bonuses of all line items for this positionId to debiting, indicated in kopecks.






	
	
		 





bonusAmountForCredit





 





N..18





 No  





The total amount of bonuses of all line items for this positionId to accrual, indicated in kopecks.






	





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





The request has been processed without system errors.






	
	
		 1  





An order with this number has already been processed.






	
	
		 1  





Wrong order number.






	
	
		 3  





Unknown currency.






	
	
		 4  





Order number is empty






	
	
		 4  





Merchant name cannot be empty.






	
	
		 4  





The amount is missing.






	
	
		 4  





Empty return URL






	
	
		 4  





Password cannot be empty.






	
	
		 5  





Access denied.






	
	
		 5  





The user is inactive.






	
	
		 7  





System error.






	
	
		 8  





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






	
	
		 8  





Additional parameter amount_bonus is not allowed if the request contains a cart.






	
	
		 8  





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






	





===== Examples ====


==== POST request example ====

<sxh javascript>
amount=24000&currency=643&language=ru&orderNumber=01a287222222299&returnUrl=https://3dsec.sberbank.ru/payment/finish.html&
jsonParams={«name1»:«value1»}&merchantLogin=merch_child&orderBundle={ «orderCreationDate»:1373622660000,
«customerDetails»:{ «email»:«1234567890123456789012345678901234567890», «phone»: «79851231234»,
«contact»: «Mega Tester», «deliveryInfo»:{ «deliveryType»:«courier», «country»:«RU», «city»:«Moscow»,
«postAddress»:«Bld. 2, 50A/8 Zemlyanoy Val St.» }},  «cartItems»:  { «items»: [
{ «positionId»: «1», «name»: «Metzeler Enduro 3 Sahara»,
«itemDetails»: { «itemDetailsParams»: [{ «value»: «Metzeler », «name»: «brand» },
{ «value»: «17inch», «name»: «radius» }]}, «quantity»: { «value»: 0.71, «measure»: «pieces» },
«itemAmount»: 8000, «itemCurrency»: «643», «itemCode»: «NM-15»,
{ «positionId»: «2», «name»: «Universal Mirror Enduro»,
«itemDetails»: { «itemDetailsParams»: [{ «value»: «Noname», «name»: «brand» },
{ «value»: «12mm», «name»: «diameter» }]}, «quantity»: { «value»: 1.0, «measure»: «pieces» },
«itemAmount»: 8000, «itemCurrency»: «643», «itemCode»: «NM-15»,
{ «positionId»: «3», «name»: «Warm Grips»,
«itemDetails»: { «itemDetailsParams»: [ { «value»: «Noname», «name»: «brand» }]},
«quantity»: { «value»: 1.0, «measure»: «pieces» },
«itemAmount»: 8000, «itemCurrency»: 643, «itemCode»: «G-16» }] } } }
</sxh>

==== Response example ====

<sxh javascript>
{«formUrl»:«https://3dsec.sberbank.ru/payment/merchants/789/payment_ru.html?mdOrder=fc122907-e237-440e-9f25-48bf6120984b»,»orderId«:«fc122907-e237-440e-9f25-48bf6120984b»}
</sxh>

`loyalties`	Not applicable	If the `loyalties` block was transferred	A block with attributes of bonus programs, which include items from the cart.
`loyaltyProgramName`	ANS..20	If the `loyalties` block was transferred	The name of the bonus program in which the product item is involved, you should use the value `sbrf_spasibo`.
`positionId`	ANS..12	If the `loyalties` block was transferred	Unique identifier of a line item within the order cart.
`bonusAmountForDebit`	N..18	If the `loyalties` block was transferred	The total amount of bonuses of all line items for this `positionId` to debiting, indicated in kopecks.
`bonusAmountForCredit`	N..18	No	The total amount of bonuses of all line items for this `positionId` to accrual, indicated in kopecks.

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
0	The request has been processed without system errors.
1	An order with this number has already been processed.
1	Wrong order number.
3	Unknown currency.
4	Order number is empty
4	Merchant name cannot be empty.
4	The amount is missing.
4	Empty return URL
4	Password cannot be empty.
5	Access denied.
5	The user is inactive.
7	System error.
8	`[orderBundle.cartItems.totalAmount]` the sum of items in the cart does not match the total.
8	Additional parameter `amount_bonus` is not allowed if the request contains a cart.
8	`[orderBundle.cartItems.item.quantity.value]` Too high or too low value.

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

Request for order registration with pre-authorization, shopping cart, Online Lending (registerPreAuth.do)

Request 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