Request for recurrent payments (recurrentPayment)

The request used for registering an order is recurrentPayment

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

Order number in the store system.

language

Language in the ISO 639-1 encoding. If the language is not specified, the default language defined in the store settings is used.

bindingId

AN..255

Yes

Identifier of the binding created earlier.

amount

N..12

Yes

Payment amount in minimum currency units.

clientId

ANS..255

Yes

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.

currency

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

description

ANS..512

Description of the order in free form.

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

additionalParameters

Not applicable

Additional parameters of the order that are stored in the merchant personal account for the subsequent viewing. For each additional parameter, use the entry block which includes the following nested parameters.

Name	Type	Description
`key`	String	The name of the optional parameter.
`value`	AN..1024	The value of the additional parameter is up to 1024 characters.

Below is an example of how to use this parameter.

<entry>
    <key>parameter_1</key>
    <value>value_1</value>
</entry>
<entry>
    <key>parameter_2</key>
    <value>value_2</value>
</entry>

If the merchant has fiscalization set up, when indicating email (the buyer's email address) and/or phone (the buyer's cell phone number) as additional parameters, these parameters are first used to send the fiscal receipt.

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

Response parameters

The response parameters are given in table below.

Name	Type	Mandatory	Description
`success`	A..5	Yes	Designates a successful request. The following values are available: true – request is processed successfully; false – request failed.
`data` block (returned only if the request was successful)
`orderId`	ANS36	Yes	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.
`error` block (returned only if the request resulted in an error)
`code`	N3	Yes	Error code.
description	ANS..512	Yes	A detailed technical explanation of the error – the contents of this parameter is not to be displayed to the customer.
`message`	AN..512	Yes	Comprehensive error description – it is intended for displaying to the user.

Error codes

Error code	Error text
0	The request has been processed without system errors.
1	The funds on the card are not sufficient.
1	Wrong order number.
2	The binding is not found.
4	Invalid binding identifier `[bindingId]`.
5	Using binding is disabled.
5	Invalid amount `[amount]`.
5	Incorrect login.
5	Incorrect password
5	Authentication error
7	System error.
10	An order with this number has already been registered.
10	Incorrect value of [currency]
10	Incorrect value of [language]
10	Duplicate order number
10	Incorrect value of [orderNumber]
10	Incorrect value of [orderDescription]. Links in the order description are not allowed

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:recurrentPayment>
         <arg0>
            <orderNumber>123123</orderNumber>
            <bindingId>binding_id</bindingId>
            <amount>123</amount>
            <description>description</description>
            <additionalParameters>
               <entry>
                  <key>firstParamName</key>
                  <value>firstParamName</value>
               </entry>
            </additionalParameters>
         </arg0>
      </mer:recurrentPayment>
   </soapenv:Body>
</soapenv:Envelope>

Example of successful payment

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:recurrentPaymentResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
         <return>
            <success>true</success>
            <data>
               <orderId>134561314642</orderId>
            </data>
            <orderStatus errorCode="0"/>
         </return>
      </ns1:recurrentPaymentResponse>
   </soap:Body>
</soap:Envelope>

Example of unsuccessful payment

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:recurrentPaymentResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
         <return>
            <success>false</success>
            <error>
               <code>10</code>
               <description>An order with this number has already been registered.</description>
            </error>
            <orderStatus errorCode="0"/>
         </return>
      </ns1:recurrentPaymentResponse>
   </soap:Body>
</soap:Envelope>

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