ANNEX 3 PROTOCOL OF CANCELS AND REFUNDS
Yandex.Money Merchant Web Services
Version 3.2.1 from 27 March 2015
CONTENTS
1.
Overview ........................................................................................................ 2
1.1. Purpose of This Document ............................................................................. 2
1.2. Onboarding of the Counterparty ..................................................................... 2
2.
Format for Interaction ...................................................................................... 2
2.1. Request Format ........................................................................................... 2
2.2. Response Format ......................................................................................... 3
2.3. Rules for Processing Requests ....................................................................... 3
3.
Information Requests ....................................................................................... 3
3.1. Request for Orders List ................................................................................. 3
3.1.1.
Request of the Counterparty ................................................................. 4
3.1.2.
Response Format ................................................................................ 6
3.2. Request for List of Refunds (listReturns) ........................................................ 10
4.
Financial Operations ........................................................................................ 12
4.1. Request for Refund (returnPayemt) .............................................................. 12
4.2. Request for Confirmation of a Deferred Payment (confirmPayment) .................. 14
4.3. Request for Cancelation of a Deferred Payment (cancelPayment) ...................... 15
4.4. Request for Repeating Payment by Bank Card (repeatCardPayment) ................. 16
5.
Appendices..................................................................................................... 17
5.1. HTTP Response Codes ................................................................................. 17
5.2.
Common Response Parameters .................................................................... 17
5.3. Request Status Codes ................................................................................. 18
5.4. Data Types ................................................................................................ 18
5.5 Error Codes ................................................................................................. 21
5.6. Status Codes for Notification of Transfer ..............Error! Bookmark not defined.
1. Overview
1.1. Purpose of This Document
This document describes the operating principals of Merchant Web Services (“MWS”). MWS is an
interface used for secure interaction between the Counterparty’s information system (“IS”) and
NBCO Yandex.Money LLC (“Operator”, “Yandex.Money”) via the internet, in real time mode.
MWS allows the Counterparty to receive information on customers’ successful orders and refunds,
to refund successful payments, to confirm or to cancel deferred payments, and to repeat payments
by card (with the payer’s prior authorization).
Formats for the corresponding requests are specified in Sections 3 “Information Requests” and 4
“Financial Operations”.
1.2. Onboarding of the Counterparty
Before using MWS, the Counterparty needs to implement the information exchange protocol for
performing transfers with the Operator (“Protocol 3.0”, see the document “Yandex.Money to
Merchant Integration Protocol: HTTP and Email Notifications”), which involves a number of
restrictions/particularities depending on the scheme by which the Counterparty chooses to
integrate with the Operator. These restrictions/particularities are described in the corresponding
sections, which detail MWS requests.
The implementation scheme the Counterparty chooses and the terms and conditions of its
agreement with the Operator determine which MWS requests are available to the Counterparty.
The Operator’s settings also affect which MWS requests are available to the Counterparty. Repeat
payments by card (repeatCardPayment) are only available if the parties have entered into the
agreement on debiting funds from a card as initiated by the Counterparty.
Please note: to work with deferred payments (requests confirmPayment and cancelPayment), a
separate store should be registered in the Operator’s system.
The Counterparty can contact its account manager for more detailed information about integration
process.
2. Format for Interaction
The Counterparty and the Operator interact via the HTTPS protocol. To work with the MWS, the
Counterparty should obtain an X.509 certificate issued by the Operator’s certification authority, by
which the Counterparty shall form requests to the Operator. The procedure of issuing the certificate
is described in the document “Client Certificate Request Procedure”.
2.1.
Request Format
Information from the Counterparty's IS is transmitted to the Operator via HTTP/1.1 protocol using
POST-request method. The message’s parameters are packed as a set of POST-request parameters
in the form of the pairs “name=value”. Content-Type: application/x-www-form-urlencoded,
character set – UTF-8.
Please note: requests for refunds (returnPayment) should be sent as encoded cryptographic
messages. Section 4.1 “Request for Refund (returnPayment)” contains an explicit description of this
request’s format.
2.2.
Response Format
Results of processing the Counterparty’s request returns as an XML document under the standard
XML 1.0 (Fifth Edition) published at http://www.w3.org/TR/xml/. Content-Type: application/xml.
Character set – UTF-8.
Possible HTTP response codes are listed in Section 5.1 “HTTP Response Codes”.
2.3.
Rules for Processing Requests
1. The Operator processes the incoming request immediately. If the request is not processed
within a few seconds, the response “in progress” (status=1) is returned. In this case the
Counterparty’s IS should repeat the request with the same parameters to get a definitive
response. It is recommended that the Counterparty use the following schedule for repeating
requests: first repeat attempt after 1 minute, the next three attempts at 5-minute intervals, and
any successive attempts no less than 30 minutes apart.
2. If there is no response or an unclear response (e.g. HTTP status 500 or status=1), the request
should be repeated with the same parameters to get a definitive response. The recommended
schedule for repeating requests is specified in point 1.
3. If the status of an operation is “in progress” (status=1), then its status can be changed to “success”
as well as to “refused”.
4. If the request is refused by the Operator, the response will contain status=3 and error= with the
reason for refusal. In some cases, the response may contain an additional text field techMessage
with a detailed description in free format. This text is meant for analysis by technical specialists
and should not be displayed on any user interface.
5. Every request for refund (returnPayment) and for repeat of payment by a card
(repeatCardPayment) must be sent with a unique operation identifier (clientOrderId).
 If the request is sent with an operation identifier (clientOrderId) that has already been
processed, and if the values of all other request parameters except requestDT (the request
date and time by the hour of the Counterparty’s IS) are the same as the request parameters
of the previous attempt, the Operator returns the processed results of the request that was
already sent.
 If the request is sent with an operation identifier (clientOrderId) that has been processed
previously, and if the values of the other request parameters differ from that of the first
attempt, the Operator declines such a request and returns in response status=3, error=405.
6. If the Counterparty integrates deferred payments and repeated payments by banks cards, then
the repeated payments will be executed like deferred payments. I.e. after the request to repeat
a payment by bank card (repeatCardPayment), the Counterparty must execute either a request
for confirmation (confirmPayment) or a request for cancelation of the deferred payment
(cancelPayment).
7. If the Counterparty has implemented the Protocol 3.0 by the HTTP-scheme, then when it sends
a request for payment repeat (repeatCardPayment), it receives requests “Check order”
(checkOrder), and then “Notification of Payment” (paymentAviso). If the Counterparty
implements the protocol via the email scheme, it receives no additional requests.
Section 5 “Appendices” contains a full list of HTTP response codes, request statuses, operation
errors.
3. Information Requests
3.1. Request for Orders List (listOrder)
The request for orders list allows the Counterparty to receive a list of orders and their properties.
Operation address: https://server:port/webservice/mws/api/listOrders
The request and response parameters are listed in Tables 3.1.1.1. “Request Parameters for listOrders”
and 3.1.2.1. “Response Parameters for listOrder”. The description of protocol data types are in the
Section 5.4 “Data Types”. Some parameters may be omitted in the request, in which case the
parameter’s default value is used. If a parameter is present in the request but has a null value, the
default value is not applied to the parameter. The errors that may occur while executing a request are
listed in Section 5.5 “Error Codes”.
Please note: a response may be in CSV or XML format. The response format is defined by the request
input parameters outputFormat and csvDelimiter (value delimiter for CSV format).
3.1.1. Request of the Counterparty
Table Error! No text of specified style in document..1.1. Request Parameters for listOrders
Parameter
Type
Description
requestDT
xs:dateTime
outputFormat
xs:normalize
dString
Date and time of the request according to the time of the
Counterparty’s IS. Mandatory parameter.
Format for displaying request result. Possible values –
“XML” or “CSV”. Optional parameter: default value is “XML”.
csvDelimiter
xs:string, 1
symbol
Value delimiter for CSV format. Cannot be “”” (quotation
mark). Optional parameter: default value “;”.
shopId
xs:long
orderCreatedDatetime
GreaterOrEqual
xs:dateTime
orderCreatedDatetime
LessOrEqual
xs:dateTime
paid
xs:boolean
paymentDatetimeGre
aterOrEqual
xs:dateTime
paymentDatetimeLess
OrEqual
xs:dateTime
invoiceId
xs:long
The identifier of the Counterparty whose orders list is
requested.
If the parameter is not specified, orders are returned by all
the shopId’s for which the current MWS user has rights to
receive orders lists.
The lower boundary of the order creation time. Orders
created at the time indicated by this parameter or later are
returned.
The upper boundary of the order creation time. Orders
created at the time indicated by this parameter or earlier
are returned.
If the parameter value is “true”, only paid orders are
returned.
If the parameter value is “false”, only unpaid orders are
returned.
If the parameter is not specified, both paid and unpaid
orders are returned.
The lower boundary of the order payment time.
Selection of orders that were paid for at the time indicated
by this parameter or later.
The upper boundary of time order payment time.
Selection of orders that were paid for at the time indicated
by this parameter or earlier.
Unique transaction number in the Operator’s IS.
orderNumber
xs:string, up
to 64
symbols
Unique order number in the Counterparty’s IS.
The parameter can only be used if the Operator receives
and stores order numbers from the Counterparty.
Parameter
Type
Description
outputFields
xs:string, up
to 4,000
symbols
A list of the order properties to be displayed in the
response.
Delimiter for items in the list is the symbol “;” (without
quotation marks).
Default value:
“shopId;shopName;articleId;articleName;invoiceId;orderNu
mber;paymentSystemOrderNumber;customerNumber;creat
edDatetime;paid;orderSumAmount;
orderSumCurrencyPaycash;orderSumBankPaycash;paidSum
Amount;
paidSumCurrencyPaycash;paidSumBankPaycash;receivedSu
mAmount;
receivedSumCurrencyPaycash;receivedSumBankPaycash;
shopSumAmount;shopSumCurrencyPaycash;shopSumBankP
aycash;
paymentDatetime;paymentAuthorizationTime;payerCode;
payerAddress;payeeCode;paymentSystemDatetime;
avisoReceivedDatetime;avisoStatus” (without quotation
marks).
Table Error! No text of specified style in document..2.1.
“Response Parameters for listOrder” contains the full list of
order properties.
Please note: At least one of the following conditions must be given in the parameters of a request for an
orders list:
 Transaction number (invoiceId) and the Counterparty’s identifier (shopId);
 Order number (orderNumber) and the Counterparty’s identifier (shopId);
 Time interval for order creation (orderCreatedDatetimeGreaterOrEqual and/or
orderCreatedDatetimeLessOrEqual);
 Time interval for order payment (paymentDatetimeGreaterOrEqual and/or
paymentDatetimeLessOrEqual).
When requests are made by the transaction number (invoiceId) or by the order number (orderNumber),
such requests must contain the Counterparty’s identifier (shopId).
Please note: The following rules are applied to requests for selection of orders limited by the time of
creation or by the time of payment:
 if only one bound is given for the time of order creation or order payment, then the second
bound is taken by default. The default value for the upper bound is the current time of the
Operator. The default value for the lower bound is the time of the upper bound in the request
minus 24-hours;
 if the time interval for order payment is set, then the “paid” parameter must be given in the
request and must have the value “true” (without quotation marks);
 the requested time interval must not exceed 31 days;
 the number of entries in the resulting response cannot exceed 10,000.
3.1.2. Response Format
Table Error! No text of specified style in
document..2.1. Response Parameters for listOrder
Parameter
Type
Description
orderCount
xs:int
shopId
xs:long
articleId
shopName
xs:long
xs:string, up to 64
symbols
xs:string, up to 128
symbols
xs:long
xs:string, up to 64
symbols
Number of orders in result.
Response heading field. Present when the
orders list selection is successful.
Counterparty’s identifier, assigned by the
Operator.
Article identifier, assigned by the Operator.
Name of the Counterparty
articleName
invoiceId
orderNumber
paymentSystemOrderNumber
customerNumber
xs:string, up to 40
symbols
xs:string, up to 64
symbols
createdDatetime
xs:dateTime
paid
xs:boolean
paymentDatetime
xs:dateTime
paymentAuthorizationTime
xs:long
payerCode
YMAccount
payerAddress
payeeCode
xs:string, up to 33
symbols
YMAccount
paymentSystemDatetime
xs:dateTime
Name of the article
Operator’s unique transaction number.
Order number in the Counterparty’s IS.
If the Operator receives and stores order
numbers from the Counterparty’s IS, then this
parameter contains the order number in the
Counterparty’s IS. Otherwise, the parameter
contains the transaction number in the
Operator’s IS.
Transfer identifier in the Operator’s system.
Only present for paid orders.
Payer’s identifier in the Counterparty’s IS (sent
in the payment form). The identifier can be
the payer’s mobile phone number, contract
number, username, etc. It is a unique
identifier in the Counterparty’s IS.
Time when order was registered in the
Operator’s IS.
The value is “true” if the order is paid.
Otherwise, the value is “false”.
Time when the order was paid for according
to the time of the Operator’s IS.
The value is only present for paid orders.
Order number in the Operator’s processing
center.
The value is only present for paid orders.
Payer’s account number.
The value is only present for paid orders.
The payer’s IP, if known.
The value is only present for paid orders.
Transfer recipient’s account number when
paying for the order.
The value is only present for paid orders.
Time of the registration of order payment in
the Operator’s processing center.
Parameter
Type
avisoReceivedDatetime
xs:dateTime
avisoStatus
xs:int
avisoRegistryId
xs:long
orderSumAmount
orderSumCurrencyPaycash
orderSumBankPaycash
contractAmount
CurrencyAmount
CurrencyCode
CurrencyBank
CurrencyAmount
contractCurrency
paidSumAmount
CurrencyCode
CurrencyAmount
paidSumCurrencyPaycash
CurrencyCode
paidSumBankPaycash
CurrencyBank
shopSumAmount
CurrencyAmount
shopSumCurrencyPaycash
shopSumBankPaycash
receivedSumAmount
CurrencyCode
CurrencyBank
CurrencyAmount
receivedSumCurrencyPaycash
CurrencyCode
receivedSumBankPaycash
CurrencyBank
paymentFormParams
xs:string
paymentType
PaymentType
Description
The value is only present for paid orders.
Time of the order payment registration in the
Counterparty’s IS.
The value is only present, if the Counterparty
has received a notification of payment
(paymentAviso) by the time of request.
Status code for notification of payment.
The notification statuses are described in
Section Error! Reference source not found.
“Status Codes for Notification of Payment”.
Number of the payment report that contains
this order.
Order amount.
Currency code for orderSumAmount.
Processing center code for orderSumAmount .
Amount to be paid in the currency of the
payer’s account.
Currency code of the payer’s account.
The amount paid by the payer.
The value is only present for paid orders.
The currency code for paidSumAmount.
The value is only present for paid orders.
Processing center code for paidSumAmount.
The value is only present for paid orders.
Amount to be received on the Counterparty's
bank account: the order amount less the
Operator's commission.
Currency code for shopSumAmount
Processing center code for shopSumAmount.
The amount received by the Operator from
the payer.
The value is only present for paid orders.
Currency code for receivedSumAmount.
The value is only present for paid orders.
Processing center code for
receivedSumAmount.
The value is only present for paid orders.
Parameters of the payment form.
The value is only present for the Counterparty
that have the setting “save payment form
parameters” enabled.
Payment method used.
Response in CSV Format
If CSV response format is specified in the request, the heading and the body of the answer will be a set
of strings delimited by string breaks. The first string of the response contains the values of the heading
fields of the request result. The second string contains a list of the names of order properties in the
same order in which the values of those order properties will appear in subsequent strings. Each string
of the response, starting with the third one, contains the properties of only one order.
The value of the request parameter csvDelimeter is used as a delimiter for order properties. If the order
property contains the value delimiter symbol (csvDelimiter request parameter) or the symbol “””
(without surrounding quotation marks), then in the MWS response the value of the property is put in
quotation marks “”” (without surrounding quotation marks). At the same time, the quotation marks
contained in the property’s value are doubled.
If the value of any property cannot be defined (e.g. the time of payment for an unpaid order), the value
of the given property will be null in a CSV-formatted response.
Example of response to listOrders when processing is successful (CSV format, default set of order
properties. Long strings are wrapped; the table rows show where strings start and end):
status=0;error=0;processedDT=2011-08-02T18:28:08.541+04:00;orderCount=2
shopId;articleId;invoiceId;orderNumber;paymentSystemOrderNumber;customerNumb
er;createdDatetime;paid;orderSumAmount;orderSumCurrencyPaycash;orderSumBankP
aycash;paidSumAmount;paidSumCurrencyPaycash;paidSumBankPaycash;receivedSumAm
ount;receivedSumCurrencyPaycash;receivedSumBankPaycash;shopSumAmount;shopSum
CurrencyPaycash;shopSumBankPaycash;paymentDatetime;paymentAuthorizationTime;
payerCode;payerAddress;payeeCode;paymentSystemDatetime;avisoReceivedDatetime
;avisoStatus;avisoRegistryId
1;2;2000000294394;12345670;;;2011-0802T18:28:08.269+04:00;false;2.08;10643;1003;;;;;;;
2.00;10643;1003;;;;;;;;;;
2;3;2000000294386;12345671;334074060091013004;;2011-0802T18:20:58.562+04:00;true;350.00;10643;1002;350.00;10643;1003;350.00;10643;
1003;300.00;10643;1002;
2011-0802T18:21:00.091+04:00;334074060091013004;41003321020;192.168.1.127;410031234
567;
2011-08-02T18:21:00.091+04:00;2011-08-02T18:27:59.448+04:00;81;
Example of response to listOrders when an error occurs, CSV format:
status=3;error=111;processedDT=2011-07-21T13:20:14.869+04:00;
techMessage=”Invalid requestDT parameter value”
Response in XML Format
If the value of any property cannot be defined (e.g. the time of payment for an unpaid order), the
corresponding attribute will be omitted in the XML-formatted response.
Example of response to listOrders when processing is successful, XML format:
<?xml version=”1.0” encoding=”utf-8”?>
<listOrdersResponse status=”0” error=”0”
processedDT=”2011-08-02T20:38:01.000+04:00”
orderCount=”2”>
<order shopId=”1” articleId=”2” invoiceId=”2000000294393”
shopName=”&quot;Mobile&quot; LLC”
articleName=”Payment for mobile phone”
orderNumber=”12345678”
paymentSystemOrderNumber=”334074426144011004”
createdDatetime=”2011-08-02T18:27:05.568+04:00”
paid=”true”
paymentDatetime=”2011-08-02T18:27:06.144+04:00”
paymentAuthorizationTime=”334074426144011004”
payerCode=”41003122233”
payerAddress=”192.168.1.127”
payeeCode=”41003987654”
paymentSystemDatetime=”2011-08-02T18:27:06.144+04:00”
avisoReceivedDatetime=”2011-08-02T18:27:06.144+04:00”
avisoStatus=”1000”
orderSumAmount=”2.08”
orderSumCurrencyPaycash=”643”
orderSumBankPaycash=”1001”
paidSumAmount=”2.08”
paidSumCurrencyPaycash=”643”
paidSumBankPaycash=”1001”
shopSumAmount=”2.07”
shopSumCurrencyPaycash=”643”
shopSumBankPaycash=”1001”
receivedSumAmount=”2.07”
receivedSumCurrencyPaycash=”643”
receivedSumBankPaycash=”1001”
/>
<order shopId=”2” articleId=”3” invoiceId=”2000000294394”
shopName=”&quot;Virtual reality&quot; LLC”
articleName=”Football forever”
orderNumber=”12345679”
createdDatetime=”2011-08-02T18:28:08.269+04:00”
paid=”false”
orderSumAmount=”2.08”
orderSumCurrencyPaycash=”643”
orderSumBankPaycash=”1001”
shopSumAmount=”2.07”
shopSumCurrencyPaycash=”643”
shopSumBankPaycash=”1001”
/>
</listOrdersResponse>
Example of response to listOrders when an error occurs, XML format:
<?xml version="1.0" encoding="UTF-8"?>
<listOrdersResponse
status="3" error="111"
processedDT="2011-07-02T20:38:01.000+04:00"
techMessage="Invalid requestDT parameter value"
/>
3.2. Request for List of Refunds (listReturns)
This request allows the Counterparty to review a select history of refunds.
Operation address: https://server:port/webservice/mws/api/listReturns
Request and response parameters are listed in the Tables 3.2.1. “Request Parameters for listReturns”
and 3.2.2. “Response Parameters for listReturns Operation”. The protocol data types are listed in
Section 5.4 “Data Types”. Some parameters may be omitted in the request. The default value is used for
such parameters. If a parameter with a null value is included in the request, the default value is not used
for such parameters. The errors that may occur while processing a request are listed in Section 5.5
“Error Codes”.
Please note: a response may be in CSV or XML format. The response format is defined by the request
input parameters outputFormat and csvDelimiter (value delimiter for CSV format).
The request parameters “from” and “till” are applied to the response field createdDT (time the request
for refund was registered).
Table Error! No text of specified style in document..2. Request Parameters for listReturns
Parameter
Type
Description
requestDT
xs:dateTime
shopId
xs:long
from
till
status
partial
xs:dateTime
xs:dateTime
xs:int
xs:boolean
outputFormat
xs:normalizedString
csvDelimiter
xs:string, 1 symbol
Date and time of request according to the time of the
Counterparty’s IS. Mandatory parameter.
The Counterparty’s identifier, assigned by the
Operator.
Lower time bound.
Upper time bound.
Operation status (optional parameter).
Optional parameter. Possible values:
 true–the operations for which only a part of
the transfer amount was refunded are
returned
 false–the operations for which the whole
transfer amount was refunded are returned
 parameter absent–all operations are returned
Default value: parameter is absent.
Format for displaying results, possible values–“XML”
or “CSV”. Default value: XML.
Value delimiter for CSV format. Cannot be “””
(quotation mark). Optional parameter: default value
“;” (without quotation marks).
Table Error! No text of specified style in document..3. Response Parameters for listReturns
Parameter
Type
Description
returnId
xs:long
Unique identifier of the return operation in the
Yandex.Money service.
invoiceId
xs:long
Operator’s unique transaction number.
shopId
xs:long
The Counterparty’s identifier, assigned by the
Operator.
amount
CurrencyAmount
Refund amount.
currency
CurrencyCode
Currency code.
cause
xs:string, up to 255
symbols
Description of the reason for return.
status
xs:int
Code of the request status.
error
xs:int
Error code.
createdDT
xs:dateTime
Time the request for refund was registered.
processedDT
xs:dateTime
Actual time when funds were returned to the payer.
The field is only present for successful refunds.
sender
xs:string
Sender of the request for refund. The parameter
contains the CN field of the X509 certificate used for
signing the request for refund (returnPayment).
articleAmount
CurrencyAmount
Amount of refund in the article’s currency.
articleCurrency
CurrencyCode
Code of the article's currency.
orderNumber
xs:string, up to 64
symbols
Unique order number for the given shopId in the
Counterparty’s IS.
Response in CSV Format
Example of the response to listReturns, when processing is successful, CSV format:
status=0;error=0;processedDT=2011-07-02T20:38:01.000Z
123;0;0;2000000123;6689;10.00;643;2011-07-02T20:38:01.000Z;2011-0702T20:38:01.000Z;"buyer declined to receive the
article";shopName;10.00;643;12345
124;3;506; 2000000125;6689;12.00;643;2011-07-02T20:38:01.000Z;;"buyer
declined to receive the article";shopName;12.00;643;12346
Example of the response to listReturns, when an error occurs, CSV format:
status=3;error=113;processedDT=2011-07-02T20:38:01.000Z
Please note: if a parameter is missing, a null field is given.
Response in XML Format
Example of response to listReturns, when processing is successful, XML format:
<?xml version="1.0" encoding="UTF-8"?>
<listReturnsResponse
status="0" error="0"
processedDT="2011-07-02T20:38:01.000Z">
<returnPayment
returnId="123"
status="0" error="0"
invoiceId="2000000123"
shopId="6689"
amount="10.00"
currency="643"
createdDT="2011-07-02T20:38:01.000Z"
processedDT="2011-07-02T20:38:01.000Z"
cause="buyer declined to receive the article"
sender="shopName"
articleAmount="10.00"
articleCurrency="643"
orderNumber="12345"
/>
<returnPayment
returnId="124"
status="3" error="506"
invoiceId="2000000125"
shopId="6689"
amount="12.00"
currency="643"
createdDT="2011-07-02T20:38:01.000Z"
cause="buyer declined to receive the article"
sender="shopName"
articleAmount="12.00"
articleCurrency="643"
orderNumber="12346"
/>
</listReturnsResponse>
Example of the response to listReturns, when an error occurs, XML format:
<?xml version="1.0" encoding="UTF-8"?>
<listReturnsResponse
status="3" error="113"
processedDT="2011-07-02T20:38:01.000Z"/>
4. Financial Operations
4.1.
Request for Refund (returnPayemt)
This request allows the Counterparty to return a successful payment to the payer’s account. Successful
payments can be refunded fully or partially.
Operation address: https://server:port/webservice/mws/api/returnPayment
The request parameters are listed in Table 4.1.1. “Request Parameters for returnPayment”. All
parameters are mandatory. The protocol’s data types are described in Section 5.4 “Data Types”.
The response includes common parameters listed in Section 5.2 “Common Response Parameters”.
Section 5.5 “Error codes” contains the errors that may occur while processing a request.
Please note: To make a request to the Operator’s server, the following steps should be taken:
1. Create operation request document in accordance with XML 1.0 standard (Fifth Edition),
published here: http://www.w3.org/TR/xml/. Character set is UTF-8 in accordance with standard:
http://www.ietf.org/rfc/rfc2279.txt.
2. Put XML document into cryptographic message in PKCS#7 format in accordance with standard:
http://www.ietf.org/rfc/rfc5652.txt. PKCS#7 message must contain digital signature of request
document (equivalent of handwritten signature). PKCS#7 message should not contain any
certification authority chains. Data compression is not used. Data encryption is not used. PKCS#7
message must be encoded in PEM format (used by OpenSSL). X.509 certificate used to make
digital
signature
must
comply
with
the
X.509
Version
3
standard
(http://www.ietf.org/rfc/rfc2459.txt).
3. Create and transfer of request to the Operator. The Counterparty’s IS creates POST request using
HTTP/1.1 protocol (http://www.ietf.org/rfc/rfc2616.txt, http://www.ietf.org/rfc/rfc2618.txt).
PKCS#7 message can be transferred by one of these methods:
a. PKCS#7 message put into POST-body, Content-Type: application/pkcs7-mime
b. PKCS#7 message put into multipart-data attach. Content-Type: application/pkcs7-mime.
POST request must have only one 'part', PKCS#7 message must be attached as a file. Such a
request may be sent by the standard HTML File Upload Form. See
http://www.ietf.org/rfc/rfc2388.txt
The Operator authorizes requests by verifying the digital signature of the PKCS#7 message.
Protection from erroneous repeat operations is guaranteed by unique operation numbers (clientOrderId).
HTTP request example
POST /webservice/mws/api/returnPayment HTTP/1.1
Content-Type: application/pkcs7-mime
Content-Length: 906
-----BEGIN PKCS7----MIAGCSqGSIb3DQEHAqCAMIACAQExCzAJBgUrDgMCGgUAMIAGCSqGSIb3DQEHAaCA
JIAEgbE8P3htbCB2ZXJzaW9uPSIxLjAiIGVuY29kaW5nPSJVVEYtOCI/Pg0KPG1h
a2VEZXBvc2l0aW9uUmVzcG9uc2UgY2xpZW50T3JkZXJJZD0iMTI5MTExNjIzNDUy
OCIgc3RhdHVzPSIwIiBlcnJvcj0iMCIgcHJvY2Vzc2VkRFQ9IjIwMTAtMTEtMzBU
MTE6MjM6NTQuNjI0WiIgYmFsYW5jZT0iNTQxNDYuNzMiIC8+DQoAAAAAAAAxggF8
MIIBeAIBATB3MGoxCzAJBgNVBAYTAlJVMQ8wDQYDVQQIEwZSdXNzaWExFjAUBgNV
BAcTDVN0LlBldGVyc2J1cmcxITAfBgNVBAoTGEludGVybmV0IFdpZGdpdHMgUHR5
IEx0ZDEPMA0GA1UEAxMGc2VydmVyAgkAy2xbdQckXjIwCQYFKw4DAhoFAKBdMBgG
CSqGSIb3DQEJAzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTEwMTEzMDEx
MjM1NVowIwYJKoZIhvcNAQkEMRYEFEYNh8glwqIXGR/n6oYrApa8DaO5MA0GCSqG
SIb3DQEBAQUABIGAHlgGsYK30RXWBvuQao0V73KIPQEx2hH/9GY6Iag/xlmZ3rBB
kFpszF/O2fB+t84pCHfV15ErZQEkAqIotkEYEgA3hAddEW5+RWUzp+3npHpW5OY7
h3niP5Pj+r0P8EDgHe2j0Zb3dzj2mbwOshZD+FP1IcR8AmiTV3u35C6KAEsAAAAA
AAA=
-----END PKCS7-----
Table Error! No text of specified style in document..4. Request Parameters for returnPayment
Parameter
Type
Description
clientOrderId
ClientTransactionNu
mber
Unique identifier of the refund operation.
Recommended values: positive decimal integers of
incrementally increasing value.
requestDT
xs:dateTime
Date and time the request for executing the operation
was created according to the time of the
Counterparty’s IS.
invoiceId
xs:long
Transaction number of the source order.
shopId
xs:long
Counterparty’s identifier, assigned by the Operator.
amount
CurrencyAmount
Amount to be returned to payer’s account.
currency
xs:string, 3 symbols
Alphabetic currency code of returned payment.
Specified in accordance with ISO 4217:2008.
сause
xs:string, up to 255
symbols
Description of reason for return.
Example of returnPayment request:
<?xml version="1.0" encoding="UTF-8"?>
<returnPaymentRequest
clientOrderId="12345"
requestDT="2011-07-02T20:38:00.000Z"
invoiceId="2000000123"
shopId="6689"
amount="10.00"
currency="RUB"
cause="User declined the order"
/>
Example of returnPayment response:
<?xml version="1.0" encoding="UTF-8"?>
<returnPaymentResponse
clientOrderId="12345"
status="0" error="0"
processedDT="2011-07-02T20:38:01.000Z"
/>
4.2.
Request for Confirmation of a Deferred Payment (confirmPayment)
If the Counterparty has a store that is set up such that deferred payments can be executed, then all
payments to the Counterparty will be deferred. I.e. payments will be executed in two steps: first, funds
will be reserved on the payer’s bank card and then the funds will be debited from the card. The amount
that is debited may be less than the sum reserved in the first step.
The request for confirmation of a deferred payment (confirmPayment) allows the Counterparty to
complete deferred payments to the Counterparty’s account.
Operation address: https://server:port/webservice/mws/api/confirmPayment
The request parameters are listed in Table Error! No text of specified style in document..5. “Request
Parameters for confirmPayment”; all parameters are mandatory. The protocol’s data types are described
in Section Error! Reference source not found. “Error! Reference source not found.”.
Responses contain common parameters listed in the Section Error! Reference source not found. “Error!
Reference source not found.”.
The errors that may occur when requesting confirmation of a deferred payment (confirmPayment) are
listed in Section 0. “5.5 ”.
Please note: if confirmation time for deferred payment expires, the response will return an error even if
the request parameters are valid. The confirmation time is determined by the bank that processes the
operation and is unique to each bank.
Table Error! No text of specified style in document..5. Request Parameters for confirmPayment
Parameter
Data Type
Description
requestDT
xs:dateTime
Date and time the request for operation execution
was created according to the time of the
Counterparty’s IS.
orderId
xs:long
Transaction number of the deferred payment.
amount
CurrencyAmount
Payment sum.
currency
xs:string, 3 symbols
Alphabetic currency code of the payment. Specified in
accordance with ISO 4217:2008.
Example of confirmPayment request:
requestDT="2011-07-02T20:38:00.000Z"&orderId="12345"&amount="10.00"&
currency="RUB"
Example of confirmPayment response:
<?xml version="1.0" encoding="UTF-8"?>
<confirmPaymentResponse
orderId="12345"
status="0" error="0"
processedDT="2011-07-02T20:38:01.000Z"
/>
4.3.
Request for Cancelation of a Deferred Payment (cancelPayment)
This request allows the Counterparty to cancel a deferred payment to the Counterparty’s account.
Operation address: https://server:port/webservice/mws/api/cancelPayment
The request contains the parameters requestDT (time and date the request for operation execution was
created according to the time of the Counterparty’s IS) and orderId (transaction number of the deferred
payment). These parameters are listed in Table Error! No text of specified style in document..5. “Request
Parameters for confirmPayment”.
The response contains common parameters described in Section Error! Reference source not found.
“Error! Reference source not found.”.
The errors that may occur when requesting cancelation of a deferred payment (cancelPayment) are listed
in Section 0. “5.5 ”.
Example of cancelPayment request:
<?xml version="1.0" encoding="UTF-8"?>
<cancelPaymentRequest
requestDT="2011-07-02T20:38:00.000Z"
orderId="12345"
/>
Example of cancelPayment response:
<?xml version="1.0" encoding="UTF-8"?>
<cancelPaymentResponse
orderId="12345"
status="0" error="0"
processedDT="2011-07-02T20:38:01.000Z"
/>
4.4.
Request for Repeating Payment by Card (repeatCardPayment)
This request allows the Counterparty to repeat payment using a payer’s card credentials (with the payer’s
consent), for paying for the same good (or service) but for a different amount.
Please note: to make a request for repeating a payment by a card (repeatCardPayment), the Counterparty
must be using the HTTP implementation scheme (see “Protocol 3.0 “Yandex.Money to Merchant
Integration Protocol: HTTP and Email Notifications”). When the Counterparty implements Protocol 3.0,
the Operator may add the following parameter to the request “Notification of Payment (paymentAviso)”:
Parameter
Type
Description
rebillingOn
xs:boolean
If the payer authorized payment by their card in the
course of payment, the parameter is given the value
“true”; otherwise, the parameter is not given.
Operation address: https://server:port/webservice/mws/api/repeatCardPayment
The request parameters are listed in Table Table Error! No text of specified style in document..6. “Request
Parameters for repeatCardPayment”. Protocol data types are described in Section Error! Reference
source not found. “Error! Reference source not found.”.
The request contains common parameters listed in Section Error! Reference source not found. “Error!
Reference source not found.”.
The errors that may occur when executing the request are listed in Section 0. “5.5 ”.
Please note: if the Counterparty uses the orderNumber parameter (order number in the Counterparty’s
IS) in requests, then it should take into account that the value of that parameter must be unique. I.e. it
should differ from orderNumber of the payment to be repeated.
Table Error! No text of specified style in document..6. Request Parameters for repeatCardPayment
Parameter
Type
Description
clientOrderId
ClientTransactionNu
mber
Unique operation identifier. Recommended values:
positive decimal integer with incrementally increasing
value.
invoiceId
xs:long
Transaction number of transfer to be repeated.
amount
CurrencyAmount
Amount to be paid (the currency is the same as the
article’s currency).
orderNumber
xs:string
Order number in the Counterparty’s IS (may be
omitted).
cvv
xs:string
The card’s CVC/CVV2 authorization code; may be
omitted.
Example of repeatCardPayment request:
<?xml version="1.0" encoding="UTF-8"?>
<repeatCardPaymentRequest
clientOrderId="123456789"
invoiceId="2000000123"
amount="10.00"
cvv="643"
/>
Example of repeatCardPayment response:
<?xml version="1.0" encoding="UTF-8"?>
<repeatCardPaymentResponse
clientOrderId="123456789"
status="0" error="0"
processedDT="2011-07-02T20:38:01.000Z"
techMessage=""
/>
5. Appendices
5.1.
HTTP Response Codes
Table Error! No text of specified style in document..7. Possible HTTP Response Codes
HTTP Code
Description
200 OK
Request has been accepted for processing. Response sent in accordance
with this protocol.
Request has been refused. Request body was corrupted, server unable
to parse client request.
400 Bad Request
Possible reasons:

403 Forbidden
404 Not Found
500 Internal Server Error
501 Not Implemented
5.2.
Unable to parse request
 Wrong MIME type (Content-Type header value)
Not enough rights to execute operation.
Invalid URI in request or the operation is not available at the moment.
Technical issues on Yandex.Money’s end.
Request sent with method other than POST
Common Response Parameters
Table Error! No text of specified style in document..8. Common Response Parameters
Parameter
Type
Description
status
xs:int
Result of operation. By the value of this field, the
Counterparty should make a decision on the status
of the operation. See the Section Error! Reference
source not found.. “Error! Reference source not
found.”.
error
xs:int
Error code of the request (see the Section 0. “5.5 ”).
Additional description to the status field. Optional
field.
clientOrderId
ClientTransactionNumber
processedDT
xs:dateTime
techMessage
xs:string
5.3.
Copy of the clientOrderId request parameter. Used
for financial operations.
Time and date the request was processed according
to the time of the Operator’s IS.
Optional field. May contain additional descriptive
text in addition to the server's response. This text
contains technical information and should not be
displayed on any user interface.
Request Status Codes
Table Error! No text of specified style in document..9. Request Status Codes
Status Code
Description
0
1
Success. Processing complete. Request successfully executed.
In Progress. Request processing in progress. Returns if request processing
has timed out. Counterparty is required to repeat the request to refine the
final status
Declined. Processing complete. Request refused. The reason for refusal is
shown in the “error” parameter.
3
5.4.
Data Types
Table Error! No text of specified style in document..10. Protocol Data Types Definition
Type
Description
xs:int
32-bit integer. Int32, as defined in the standard:
http://www.w3.org/TR/xmlschema-2/#int
64-bit integer. Int64, as defined in the standard:
http://www.w3.org/TR/xmlschema-2/#long
Fixed-point decimal, as defined in the standard:
http://www.w3.org/TR/xmlschema-2/#decimal
Logical value (true/false), as defined in the standard:
http://www.w3.org/TR/xmlschema-2/#boolean
Text string as defined in the standard:
http://www.w3.org/TR/xmlschema-2/#string
Text string as defined in the standard:
http://www.w3.org/TR/xmlschema-2/#normalizedString
Timestamp of the format according to the recommendations of:
xs:long
xs:decimal
xs:boolean
xs:string
xs:normalizedString
xs:dateTime

http://www.w3.org/TR/xmlschema-2/#dateTime

ISO8601:2004
Format is defined as:
YYYY-MM-DDThh:mm:ss.fZZZZZ
Format breakdown:
YYYY year, precisely 4 digits
MM
month, precisely 2 digits (01=January, etc.)
DD
day of the month, precisely 2 digits (from 01 to 31)
T
Latin letter “T”, uppercase only
hh
hours, precisely 2 digits (24-hours format, from 00 to 23)
mm
ss
f
minutes, precisely 2 digits (from 00 to 59)
seconds, precisely 2 digits (from 00 to 59)
fraction of a second (1 to 6 digits),
ZZZZZ
can be omitted, in which case the delimiter “.” should also be
omitted
Time zone attribute, mandatory parameter, possible values:
Z – UTC, “Z”, uppercase only
+hh:mm or -hh:mm, deviation from UTC (GMT) (shows that the
local time is specified, which is ahead of or behind UTC by the
given number of hours and minutes.)
All elements listed are mandatory except for fractions of a second (if this
element is omitted the delimiter “.” should also be omitted). If only the
date is required, the time should be specified as 00:00:00.
Examples:
2011-07-24T19:00:00+04:00 – 19 hours 00 minutes 24 July 2011, time
zone – UTC +4 hours.
2011-07-24T15:00:00Z – the same moment in time as above in canonical
format.
ClientTransactionNumber
2011-07-24T15:00:00.666Z – the same moment in time as above, plus
666 milliseconds.
Unique transaction identifier. Must be unique for the Counterparty
throughout its entire history of operations. The value of this parameter
should be a string from 1 to 24 characters in length. Acceptable symbols
for this string: 0-9 A-Z a-z . , \ | / - + = # ~ ( ) { } [ ] : ; Recommended values:
incrementally increasing positive decimal integers.
<xs:simpleType name="ClientTransactionNumber">
<xs:restriction base="xs:normalizedString">
<xs:minLength value="1"/>
<xs:maxLength value="24"/>
<xs:pattern value="[0-9A-Za-z.,\\|/\+=#~(){}\[\]:;]+"/>
</xs:restriction>
</xs:simpleType>
YMAccount
A virtual account number in the Operator’s IS, a string of decimal integers
(from 11 to 33 symbols in length).
<xs:simpleType name="YMAccount">
<xs:restriction base="xs:normalizedString">
<xs:minLength value="11"/>
<xs:maxLength value="33"/>
<xs:pattern value="[0-9]+"/>
</xs:restriction>
</xs:simpleType>
CurrencyAmount
Amount. Positive fixed-point decimal, with precisely 2 place values after
the decimal point.
<xs:simpleType name="CurrencyAmount">
<xs:restriction base="xs:decimal">
<xs:minExclusive value="0"/>
<xs:maxInclusive value="9999999999999"/>
<xs:fractionDigits value="2"/>
</xs:restriction>
</xs:simpleType>
CurrencyCode
Currency code. Possible values:
 643 – Russian ruble
 10643 – test currency (demo-rubles of Yandex.Money demosystem)
<xs:simpleType name="CurrencyCode">
<xs:restriction base="xs:int">
</xs:restriction>
</xs:simpleType>
CurrencyBank
Operator’s processing center code. Possible values:
 1001 – EcomBank
 1003 – DemoBank of the Yandex.Money demo-system
<xs:simpleType name="CurrencyBank">
<xs:restriction base="xs:int">
</xs:restriction>
</xs:simpleType>
PaymentType
Payment method used. String, two symbols.
 PC – payment from a Yandex.Money e-wallet.
 AC – payment by any bank card.
 MC – payment from mobile phone balance.
 GP – payment in cash via retailers and payment kiosks.
 WM – payment from a WebMoney e-wallet.

SB – payment via Sberbank: payment by text messages or
Sberbank Online.
 MP – payment via mobile point of sale (mPOS).
 AB – payment via Alfa-Click.
 MA – payment via MasterPass
 PB – payment via Promsvyazbank
List of possible values may be expanded.
<xs:simpleType name="PaymentType">
<xs:restriction base="xs: normalizedString">
<xs:minLength value="2"/>
<xs:maxLength value="2"/>
</xs:restriction>
</xs:simpleType>
5.5 Error Codes
Table Error! No text of specified style in document..11. Error Codes
Code
Description
Comments
Common Errors
0
No errors
10
Unable to parse XML document. Possible reasons:


XML syntax error
Mandatory XML elements are missing
50
Unable to read PKCS#7 cryptographic message, data integrity
error.
51
Digital signature verification failed. (Digital signature does not
match the document in the cryptographic message.)
53
Request signed with certificate unknown to the Operator’s IS
55
The Counterparty’s certificate has expired
110
The Counterparty is not authorized to execute the operation
with the parameters requested.
For example, the user is not authorized to view
orders lists for the shopId specified.
Common Errors in Request Parameters
111
Invalid value for the requestDT parameter
112
Invalid value for the invoiceId parameter
113
Invalid value for the shopId parameter
114
Invalid value for the orderNumber parameter
115
Invalid value for the clientOrderId parameter
117
Invalid value for the status parameter
118
Invalid value for the from parameter
119
Invalid value for the till parameter
120
Invalid value for the orderId parameter
Errors in Parameters of Information Requests
200
Invalid value for the outputFormat parameter
Allowed values: XML, CSV.
201
Invalid value for the csvDelimiter parameter
202
Invalid value for the orderCreatedDatetimeGreaterOrEqual
parameter
203
Invalid value for the orderCreatedDatetimeLessOrEqual
parameter
204
Invalid value for the paid parameter
205
Invalid value for the paymentDatetimeGreaterOrEqual
parameter
206
Invalid value for the paymentDatetimeLessOrEqual parameter
207
Invalid value for the outputFields
208
The time interval for order creation specified in the request is
null
The upper bound
(orderCreatedDatetimeLessOrEqual) is less than or
equal to the lower bound
(orderCreatedDatetimeGreaterOrEqual).
209
The time interval for order creation specified in the request is
too long
The time interval specified by parameters
orderCreatedDatetimeGreaterOrEqual and
orderCreatedDatetimeLessOrEqual is greater than 31
days.
210
The time interval for order payment specified in the request is
null
The upper bound (paymentDatetimeLessOrEqual) is
less than or equal to the lower bound
(paymentDatetimeGreaterOrEqual).
211
The time interval for order payment specified in the request is
too long
The time interval specified by parameters
paymentDatetimeGreaterOrEqual and
paymentDatetimeLessOrEqual is greater than 31
days.
212
Logical contradiction between the time interval for order
payment and the “paid" flag
The time interval for order payment is specified in
the request, but the “paid” parameter is missing or
has a value other than “true”.
213
No conditions for limiting the selection were specified
214
Counterparty’s ID (shopId) was not specified in the request by
order number (orderNumber)
215
Counterparty’s ID (shopId) is not specified in the request by
transaction number (invoiceId)
216
Result contains too many elements
The error arises when the resulting selection
contains more than 10,000 records. The request
parameters should be changed so that the time
interval limiting the selection is shorter.
217
Invalid value for the partial parameter
Acceptable values: true, false
Errors in Requests for Financial Operations
402
Invalid value for the amount parameter
403
Invalid value for the currency parameter
404
Invalid value for the cause parameter
Parameter missing or contains too many symbols.
405
Operation ID is not unique
Another operation with the same clientOrderId was
already processed by the system.
410
Order not paid. Unable to refund payment.
The payer has not completed payment for the order.
411
Delivery of the notification of transfer returned unsuccessful
status
Notification of transfer was not delivered to the
Counterparty’s IS.
412
Transfer currency does not match the currency specified in
the request
“Currency” request parameter contains currency
different from the currency of the performed
transfer.
413
Refund amount exceeds order amount.
The amount specified in the request for return
exceeds the initial transfer amount, when earlier
refunds are taken into consideration.
414
Transfer has already been refunded
The full amount of transfer has already been
returned to the payer’s account.
415
Order with specified transaction number (invoiceId) does not
exist
416
Insufficient funds for executing the operation
417
Payer’s account closed. Refund is not possible.
418
Payer’s account blocked. Refund is not possible.
601
Repeating card payments to store is forbidden
602
Repeating the given payment is forbidden
603
orderNumber is mandatory for this operation
604
Invalid CVV value
The Counterparty’s account lacks the funds to
execute the refund operation.
Other Errors
1000
5.6.
Technical error
Status Codes for Notification of Payment
Table Error! No text of specified style in document..12. Status Codes for Notification of Payment
Notification
Status
Description
-1
81
100
103
1000
1010
Fund transfer notification has not been created yet.
Notification awaiting sending.
Notification was delivered, but the Counterparty rejected it.
Notification delivery canceled.
The Counterparty was successfully notified of the transfer.
Notification not delivered to the Counterparty, but deemed successfully
processed.
Notification delivered successfully. The payment was refunded to the payer.
Notification delivered successfully. Part of the payment was refunded to the
payer.
1020, 1021
1022