Request for order registration (register.do)

The request used for registering an order is register.do.

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	no (either login/password or token must be specified)	Login issued to the Store upon integration with the Payment Gateway. If a public token (token parameter) is used instead of authentication with the use of login and password, then it is not required to pass the userName parameter.
`password`	AN..30	no (either login/password or token must be specified)	Password issued to the Store upon integration with the Payment Gateway. If an open token (the 'token' parameter) is used instead of login and password authentication, password parameter does not need to be passed.
`token`	AN..30	no (either login/password or token must be specified)	A public key that can be used for authentication when making a request. If login and password are used for authentication during token registration, then the `token` parameter does not need to be passed. To get the public key, contact technical support.
`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.
`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.
`dynamicCallbackUrl`	ANS..512	No	This parameter enables dynamic callback functionality. In it, you can pass the address to which all «payment» callback notifications activated for the merchant will be sent. Payment-related notifications are callback notifications about the following events: successful hold, payment rejected by timeout, cardpresent payment rejected, successful debiting, refund, reversal. Notably, payment-unrelated callbacks that are active for the Merchant (enabling/disabling a binding, binding creation) will be sent to static callback URL.
`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	Additional parameters of the request. Format: {«Name1»: «Value1», «Name2»: «Value2»}. In the app2app and back2app payment scenario, the following parameters are also passed (see the table below). 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 See description below
`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.
`features`	AN..255	No	It is possible to use the following values. `AUTO_PAYMENT` – Payment is made without authentication of the cardholder (without CVC and 3-D Secure). To make such payments, the Merchant must have the respective permissions. `VERIFY` – if this parameter is specified, after the request for order registration, the cardholder is to be verified without debiting funds from the cardholder account. Thus it is possible to pass a zero amount in the request. This verification allows the Merchant to ensure that a card belongs to the cardholder and to debit this card in the future without verifying authentication data (CVC, 3-D Secure) when processing subsequent payments. Even if the payment amount is to be passed in the request, it will not be debited from the account. After the order has been successfully registered, it is put to the REVERSED (cancelled) status. `FORCE_TDS` – Forced payment using 3-D Secure enrollment check. If the card is not enrolled in 3-D Secure, then the payment will take place with ECI = 01/06. `FORCE_SSL` – use of SSL is enforced for the payment (no 3-D Secure). `FORCE_FULL_TDS` – after authentication using 3-D Secure, the PaRes status must only be Y, which guarantees successful user authentication. Otherwise, the transaction will fail.
`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. *In case of `back2app`, the `phone` parameter must be passed. Example: https://3dsec.sberbank.ru/payment/rest/register.do?userName=ЛОГИН-api&password=ПАРОЛЬ&amount=500000&returnUrl=http://yoursite.com&phone=79998887766&jsonParams={"back2app":"true"}
`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 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).

Parameters for app2app payment scenario

Name	Type	Required	Description
`app2app`	Boolean	No	Attribute indicating the payment method through the SBOL application (app2app). The following values are available: `true` `false` To use this parameter, the merchant must have the corresponding permission enabled.
`app.osType`	ANS..32	See description	OS type. The possible values are: `ios`; `android`. Required only if `app2app=true`.
`app.deepLink`	ANS..255	See description	Link to the merchant's application for a return with successful payment. Required only if `app2app=true`.

Parameters for the back2app payment scenario

Name	Type	Mandatory	Description
`back2app`	boolean	No	Attribute indicating a payment method for `back2app` scenario

Recurring payment parameters

In the initial payment of recurring payments, the parameters specified below are passed.

recurringFrequency – the period of recurrent payments in days (an integer from 1 to 28).
recurringExpiry – the expiration date for recurrent payments (in the format YYYYMMDD).

If the request contains only one parameter or at least one parameter does not match the format, the request will fail.

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.
`externalParams`	See description	No	A block of key–value pairs, which is returned along with payment using the app2app and back2app schemes. The following parameters can be used (see table below). Below is an example of a response with an externalParams block for the app2app schema. { "orderId":"a728b310-c3a7-7c27-86fd-dc8100a20c60", "formUrl":"https://localhost:8989/payment/merchants/rbs/payment_ru.html?mdOrder=a728b310-c3a7-7c27-86fd-dc8100a20c60", "externalParams":{ "sbolBankInvoiceId":"a728b310-c3a7-7c27-86fd-dc8100a2", "sbolDeepLink":"https://test.ru" } } Below is an example of a response with an externalParams block for the back2app scheme. { "orderId":"a728b310-c3a7-7c27-86fd-dc8100a20c60", "formUrl":"https://localhost:8989/payment/merchants/rbs/payment_ru.html?mdOrder=a728b310-c3a7-7c27-86fd-dc8100a20c60", "externalParams":{ "sbolBankInvoiceId":"a728b310-c3a7-7c27-86fd-dc8100a2", "sbolInactive":"false" } }

externalParams parameters in app2app payment scenario

Name	Type	Mandatory	Description
`sbolDeepLink`	ANS..1024	No	Link to the Bank's application to complete the payment.
`sbolBankInvoiceId`	ANS..1024	No	Unique order identifier generated by the Bank.
`sbolInactive`	Boolean	No	Attribute informing about the ongoing routine maintenance. Value `true` – if routine maintenance is being carried out Value `false` – if routine maintenance is not carried out The parameter can appear if the merchant has the corresponding permission enabled, and `app2app = true`.

externalParams parameters for back2app payment scenario

Name	Type	Mandatory	Description
`sbolInactive`	Boolean	No	Attribute informing about ongoing routine maintenance Value `true` – if routine maintenance is being carried out Value `false` – if routine maintenance is not carried out
`sbolBankInvoiceId`	ANS..1024	No	Unique order identifier generated by the Bank.

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.
1	Card expired
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 must change the password.
5	`[jsonParams]` is invalid.
7	System error.
13	The merchant does not have the permission to process verification payments.
14	Features are specified incorrectly.

Examples

POST request example

amount=100&currency=643&language=ru&orderNumber=87654321&returnUrl=http://yoursite.com&jsonParams={"orderNumber":1234567890}&pageView=DESKTOP&expirationDate=2014-09-08T14:14:14&merchantLogin=merch_child&features=AUTO_PAYMENT

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

{"orderId":"70906e55-7114-41d6-8332-4609dc6590f4","formUrl":"https://3dsec.sberbank.ru/payment/merchants/test/payment_ru.html?mdOrder=70906e55-7114-41d6-8332-4609dc6590f4"}