Request for order registration (registerOrder)

The request used for registering an order is registerOrder.

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

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

merchantOrderNumber

ANS..32

See description

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.

description

ANS..598

Description of the order in any format. Only the first 24 characters of this field are transferred to Sberbank's processing for inclusion in the merchant's financial statements.

To enable sending this field to the processing system, contact the technical support service.

amount

N..12

Yes

Payment amount in minimum currency units.

currency

ISO 4217 code of the payment currency. If not specified, default value is used.

language

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

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.

sessionTimeoutSecs

N..9

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.

bindingId

AN..255

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.

expirationDate

ANS

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.

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

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.

params

See column with the description.

Additional tag with the attributes for passing additional parameters. The fields for additional information and its subsequent storage. These fields can be submitted for processing by the bank for further display in the registers. By default, the order number orderNumber and its description orderDescription are passed to the bank for processing (no more than 99 characters, «%» (percentage), «+» (plus), «\r» (carriage return) and «\n» (line feed) are prohibited for using).

Enabling the functionality is possible upon agreement with the Bank during the integration period. To pass N parameters, a request must contain N params tags, where the name attribute contains the parameter name and value attribute contains its value:

Name	Type	Description
Name `name` Type AN..20 Type2 ANS..255 Type3 A7 Type4 ANS..100 Description REST Name of the additional parameter. REST Online Lending The attribute name, always takes the value of mdOrder. WS Name of the additional parameter. Spasibo Name or the description of an item in any format. Spasibo2 Name of the parameter describing the details of a line item	ANS..255	Name of the additional parameter.
`value`	AN..1024	The value of the additional parameter is up to 1024 characters.

In the app2app and back2app payment scenario, as well as in the initial payment of recurring payments, the following parameters are also 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

See description below

clientId

ANS..255

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

To register an order on behalf of a child Merchant, specify the Merchant login in this parameter.

features

AN..255

Container for the feature parameter, the available values for the parameter are:

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.

AUTO_PAYMENT – if the request for order registration initiates auto-payments.
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.
WITHOUT_FROM_CARD – If a p2p order was registered with such a feature, then on an attempt to execute peform with TransferType.STANDARD will be rejected. With a message that the order was registered with a feature WITHOUT_FROM_CARD
WITHOUT_FROM_CARD – If a p2p order was registered with such a feature, then on an attempt to execute peform with TransferType.STANDARD will be rejected. With a message that the order was registered with a feature WITHOUT_TO_CARD

Below is an example of how to use this parameter.

<features>
      <feature>AUTO_PAYMENT</feature>
</features>

email

ANS..40

Customer's email address.

phone

NS..12

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.

billingPayerData

See description

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:

merchantOrderNumber – order number in the store system;
description – order description (no more than 99 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).

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. The identifier is missing if the 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`	N3	No	Error code.
`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	Wrong order number.
1	An order with this number has already been processed.
3	Unknown currency.
4	The amount is missing.
4	Order number is empty
4	Empty return URL
5	Payments using pre-authorization are forbidden.
5	A parameter value has been specified incorrectly.
5	Access denied.
5	The user must change the password.
7	System error.
13	The merchant does not have the permission to process verification payments.
14	Features are specified incorrectly.

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:registerOrder>
          <order merchantOrderNumber="78ds901234567890" description=" " amount="15000" currency=" " language=" " pageView="MOBILE" sessionTimeoutSecs=" " bindingId=" " expirationDate="2014-09-08T14:14:14">
             <returnUrl>https://server/applicaton_context/finish.html</returnUrl>
             <params name="param1" value="valueParam1"/>
             <params name="param2" value="valueParam2"/>
             <clientId>666</clientId>
             <merchantLogin> </merchantLogin>
             <features>
                   <feature>AUTO_PAYMENT</feature>
             </features>
          </order>
       </mer:registerOrder>
    </soapenv:Body>
 </soapenv:Envelope>

Response example

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
       <ns1:registerOrderResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
          <return orderId="05fcbc62-7ee6-4f1a-b3d5-6ca41a982283" errorCode="0" errorMessage="Successful">
             <formUrl> https://server/application_context/mobile_payment_ru.html?mdOrder=05fcbc62-7ee6-4f1a-b3d5-6ca41a982283 </formUrl>
          </return>
       </ns1:registerOrderResponse>
    </soap:Body>
 </soap:Envelope>

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

Request for order registration (registerOrder)

Request parameters

Name

Type

Type2

Type3

Type4

Description

REST

REST Online Lending

WS

Spasibo