Request for refund in full amount in monetary funds, shopping cart (refundOrder)

The request used for a full refund is refundOrder. Upon this request, the funds for the specified order are to be returned to the payer. The request will end with an error if the funds have not been debited for this order.

This operation in available for the users who have the corresponding permissions in the system.

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


In a refund request, the cart is specified in the refundItems block.

  • In case of a full refund, passing the cart of items data is optional.
  • When making a refund for an amount that differs from the amount that has been charged (except for passing the «0» value), the data about the cart of items must be mandatory passed.
  • In case of making several refunds for orders with carts, all of those refunds must be performed using the algorithm for making a refund with the cart data passed.
  • The refund amount (in money) in the cart must not exceed the confirmed amount of the original order (for autoRefund requests, the composite sums of money and points are compared).
  • Prices of all the items in the cart must be specified in the same currency (if the currency of items is to be specified) and must match the currency of the original order. For Sberbank «Spasibo» the order currency must be Russian rubles (643-RUB).
  • Line items missing in the original order are forbidden for passing in the cart. A check is carried out whether given item in the refund cart is present in the original order. The positionId, name, and itemCode must match. If at least one value does not coincide, it is considered that the line item is missing from the original order.
  • The value of quantity elements in the completion request cart must not exceed the value of the same parameter in the registration order cart.
  • The itemAmount parameter value of the items block must not exceed the value of the same parameter in the original order. For autoRefund request the system compares the value of itemAmount in items block with the amount of money and points for the same position in the original order.
  • All cart parameters are checked for compliance with the required format (length).

If at least one of the above conditions is not met, the order refund request is considered to be incorrectly generated and the payment gateway must refund an error.

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

Name Type Mandatory Description

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.

refundAmount

N..12

Yes

The refund amount in the order currency. The amount can be equal to or less than the order remaining amount.

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.

additionalOfdParams

Data block for transferring additional parameters of the OFD

Yes

Some parameters of additionalOfdParams block duplicate parameters of cartItems.items.itemAttributes block. The additionalOfdParams block is included for all line items of the order, whereas cartItems.items.itemAttributes applies to individual items. If the additionalOfdParams and cartItems.items.itemAttributes and additionalOfdParams blocks pass different values, then the priority value will be the one that was passed in cartItems.items.itemAttributes, that is, for an individual position.

The transfer of this block is possible only when using the following OFDs:

  • ATOL;
  • Business.Ru;
  • Evotor.

(Go to description.)

additionalOfdParams

additionalOfdParams contains the following elements.

Name Type Mandatory Description FFD version

agent_info.type

N..2

Mandatory if agent_info object is passed.

Agent type. The following values are available:

  • 1 – banking payment agent;
  • 2 – banking payment subagent;
  • 3 – payment agent;
  • 4 – payment subagent;
  • 5 – attorney;
  • 6 – commission agent;
  • 7 – other agent.

1.05 and later versions.

agent_info.paying.operation

ANS..24

No

Name of the transaction of the paying agent.

1.05 and later versions.

agent_info.paying.phones

array ANS..19

No

Phone numbers array of the payments agent in +N format.

1.05 and later versions.

agent_info.paymentsOperator.phones

Array ANS..19

No

Phone numbers array of the payments operator in +N format.

1.05 and later versions.

agent_info.MTOperator.address

ANS..256

No

Money Transfer operator address.

1.05 and later versions.

agent_info.MTOperator.inn

N10..12

No

Money Transfer operator TIN.

1.05 and later versions.

agent_info.MTOperator.name

ANS..64

No

Money Transfer operator name.

1.05 and later versions.

agent_info.MTOperator.phones

array ANS..19

No

An array of Money Transfer operator phone numbers in +N format.

1.05 and later versions.

supplier_info.phones

Array ANS..19

No

An array of supplier phone numbers in +N format.

1.05 and later versions.

cashier

A..256

No

Full name of the cashier

When requesting a refund, the value of this parameter may differ from that given during the registration of the order.

1.05 and later versions.

additional_check_props

ANS..16

No

Additional check details.

When requesting a refund, the value of this parameter may differ from that given during the registration of the order.

1.05 and later versions.

additional_user_props.name

ANS..24

No

Name of the additional property of the user.

When requesting a refund, the value of this parameter may differ from that given during the registration of the order.

1.05 and later versions.

additional_user_props.value

ANS..24

No

The value of the additional user attribute.

When requesting a refund, the value of this parameter may differ from that given during the registration of the order.

1.05 and later versions.

cashier_inn

N..12

No

Cashier's INN

1.2 and later versions.

client.address

ANS..256

No

Customer address.

1.2 and later versions.

client.birth_date

NS10

No

Customer birth date as dd.mm.yyyy

1.2 and later versions.

client.citizenship

N3

No

Country numeric code of the county of Customer's citizenship. The country code is specified according to All-Russian World Countries Classifier (OKSM)

1.2 and later versions.

client.document_code

N2

No

Identification document type numeric code (for example, 21 stands for Russian Passport).

1.2 and later versions.

client.passport_number

NS11

No

Series and number of the payer's passport: 1111 222222

1.2 and later versions.

client.email

ANS..64

No

Customer's email address. Exactly one of the two fields must be passed: email or phone.

1.2 and later versions.

client.phone

NS..19

No

Customer's phone number. Must be passed with the country code without spaces and additional characters (except for + character). For example, the number «+371 2 1234567» should be passed as «+37121234567»). Exactly one of the two fields must be passed: email or phone.

1.2 and later versions.

client.inn

N12

No

INN of the buyer.

1.2 and later versions.

client.name

ANS..256

No

Customer name.

1.2 and later versions.

operatingCheckProps.name

ANS

No

Operation ID The value is «0» until the value of Russia's Federal Tax Service attribute is determined.

1.2 and later versions.

operatingCheckProps.name

ANS

No

Operation ID The value is «0» until the value of Russia's Federal Tax Service attribute is determined.

1.2 and later versions.

operatingCheckProps.timestamp

NS19

No

Date and time of the operation in dd.mm.yyyy HH:MM:SS format

1.2 and later versions.

operatingCheckProps.value

ANS..64

No

Operation data.

1.2 and later versions.

sectoralCheckProps.date

NS10

No

Date of the legislative act of the federal body of executive power that sets forth the requirements for assigning the value of «sectoral attribute». Format: dd.mm.yyyy.

1.2 and later versions.

sectoralCheckProps.federalId

ANS

No

Identifier of federal body of executive power. Must be one of the values from directory of federal bodies of executive power

1.2 and later versions.

sectoralCheckProps.number

N..32

No

Number of the legislative act of the federal body of executive power that sets forth the requirements for assigning the value of «sectoral attribute».

1.2 and later versions.

sectoralCheckProps.value

ANS..256

No

A set of values defined by the legislative act of the federal body of executive power.

1.2 and later versions.

Response parameters

Name Type Mandatory Description

errorCode

ANS..3

No

Error code.

errorMessage

AN..512

No

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

Error codes

Value Description
0

The request has been processed without system errors.

5

Access denied.

5

The user must change the password.

5

[orderId] not specified.

5

Incorrect amount.

6

Wrong order number.

7

Payment must be in the correct state.

7

The refund amount exceeds the debited amount.

7

System error.

8

Specified completion amount does not match the full amount of the order. The cart data is mandatory to complete the operation with a partial pre-authorization amount.

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:refundOrder>
         <order language="ru" orderId="48b6acc0-4d08-7207-a398-cb140128092a" refundAmount="23500">
           
         </order>
      </mer:refundOrder>
   </soapenv:Body>
</soapenv:Envelope>

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

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:refundOrderResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
         <return errorCode="0" errorMessage="Successful"/>
      </ns1:refundOrderResponse>
   </soap:Body>
</soap:Envelope>