YooMoney API
Old versions of the API
Help
Sign up for YooMoney
returnPayment method
 
Description
Refunding a successful payment to the payer’s account. A successful payment can only be refunded within three years since the date of order registration in YooMoney (orderCreatedDatetime in order verification notification). For payments with the SB (SberPay) payment method, refunds can only be made within one year since the order was registered.
A refund on the same day the payment was made (before 23:59 Moscow Standard Time) is considered a cancellation of the payment. In this case, YooMoney doesn’t take a commission for the transaction, and payment data is not entered in the Report on accepted payments and reports on services provided.
Request
Address for calling the operation
https://shop.yookassa.ru/webservice/mws/api/returnPayment
The format of requests to return a successful transfer (returnPayment) differs from other methods. These types of requests must be sent as a cryptographic message.
These are the steps involved in making a request to the YooMoney server:
Step 1. Forming a document order to execute the operation
The document is formed according to the XML 1.0 standard (Fifth Edition). The document must be UTF‑8 encoded.
Step 2. Forming a cryptographic message
The prepared document is put in a PKCS#7 cryptographic message container. The cryptographic message container must contain a digital signature (equivalent to a handwritten signature). The cryptographic message container must not contain certificate authority chains. Data compression is not used. Encryption is not used. The cryptographic message must be encoded in PEM format (OpenSSL). The certificate used for preparing the cryptographic message must conform to the X.509 Version 3 standard.
Step 3. Forming and passing a request to YooMoney
The merchant generates a POST request according to the HTTP/1.1 protocol (RFC 2616, RFC 2618). The cryptographic message can be transmitted in one of two ways:
  1. the cryptographic message is sent in the body of a POST request. MIME type: application/pkcs7-mime;
  2. the cryptographic message is sent as a multipart/form-data message attachment. MIME type: application/pkcs7-mime. The POST request must have only one part — the attachment. The cryptographic message is attached as a file. This type of request may be sent to the server from a standard HTML File Upload Form (see RFC 2388).
To authorize requests, YooMoney verifies the digital signature of the cryptographic message.
Request parameters
ParameterTypeDescription
clientOrderId
ClientTransactionNumber
Unique ID of the refund operation. Provides protection from repeating operations by mistake. Recommended values: linearly increasing decimal integers.
If a request was sent with a previously processed operation number (clientOrderId) and all the request parameters other than requestDT (the request date and time in the merchant’s time) match the previous attempt, then YooMoney returns the result of the previously sent request.
If the request was sent with a previously processed operation number (clientOrderId) and all the parameters have different values from the first attempt, then YooMoney declines this request and returns status=3, error=405 in the response.
requestDTdateTimeTime when the request to perform the operation was formed, according to the merchant’s system.
invoiceId
long
Transaction number of the transfer being refunded.
shopIdlongStore ID issued by YooMoney.
amountCurrencyAmountThe amount to refund to the Payer’s account.
currencyCurrencyCodeCurrency code for the payment being refunded.
causestring,
maximum of 255 characters
Description of the reason for return.
receiptstringData for creating a receipt. Optional parameter: only transmitted if the store works with its online sales register via YooMoney.
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-----
Request example
XML
<returnPaymentRequest
        clientOrderId="12345"
        requestDT="2011-07-02T20:38:00.000Z"
        invoiceId="2000000123"
        shopId="6689"
        amount="10.00"
        currency="643"
        cause="User refused to accept the order"
/>
Parameters for the receipt
These parameters are required (and are mandatory for transmitting) if you set up interaction with your online sales register via YooMoney. See Description of payment process with receipt data transmission
Parameters for the receipt must be transmitted only if the receipts' contents are altered:
  • a partial refund took place;
  • the payment to be returned was executed without transmitting parameters for the receipt.
In this case, the receipt parameter is added to the request. Details for the receipt are transmitted in this parameter (about the products money for which are being returned).
Full refunds do not require transmitting parameters for the receipts (if the fiscal data were transmitted together with the payment).
ParameterTypeDescription
customerContact
string,
64 characters
Buyer’s phone number or email address.
Restrictions:
  • phone number in the format +792100000000 or email address (we check it);
  • you should only transmit one piece of information: either email address or phone number;
  • you should not transmit several email addresses or phone numbers.
Required if customer is not specified.
taxSystem
int
Store’s Tax System (STS). The parameter is only required if you use several tax systems. Otherwise, the parameter is not transmitted.
Possible values — a number from 1 to 6:
  • 1 — general tax system;
  • 2 — simplified tax system (income);
  • 3 — simplified tax system (income less expenses);
  • 4 — unified imputed income tax;
  • 5 — unified agricultural tax;
  • 6 — patent tax system.
Important: products with different taxSystem must be transmitted in different receipts.
Optional
customer
Object
User information.
Required if customerContact is not specified.
customer.fullName
string,
maximum of 256 characters
For legal entities—company name, for sole proprietors and individuals—full name. If an individual does not have an INN (TIN), this parameter should include passport information.
Optional
Online sales register that support this parameter: Orange Data, ATOL Online.
customer.inn
string
User’s INN (TIN) (10 or 12 digits). If an individual does not have an INN (TIN), the customer.fullName parameter should contain passport information.
Optional
Online sales register that support this parameter: Orange Data, ATOL Online.
customer.email
string
User’s email address for sending the receipt.
Required if phone or customerContact are not specified.
customer.phone
string
User’s phone number for sending the receipt. Set in the ITU-T E.164 format, for example, +79000000000.
Required if email or customerContact are not specified.
items
Object
All products in the order.
Required
item.quantity
Decimal. Maximum possible value and maximum number of digits after the decimal point depend on the model of your online sales register
Product quantity. Defines the quantity of products in the order or quantity of products sold by weight.
Required
item.price
Object
Product price.
Required
item.price.amount
CurrencyAmount
(decimal accurate to the hundredths place)
Price per unit.
Required
item.price.currency
CurrencyCode
Currency code: RUB (Russian ruble).
Optional
item.tax
int
VAT rate. Possible values — a number from 1 to 6:
  • 1 — without VAT;
  • 2 — VAT at the rate of 0%;
  • 3 — VAT of the receipt at the rate of 10%;
  • 4 — VAT of the receipt at the rate of 20%;
  • 5 — VAT of the receipt at the applicable rate of 10/110;
  • 6 — VAT of the receipt at the applicable rate of 20/120.
Required
item.text
string,
128 characters
Product name.
Required
item.paymentSubjectType
string,
128 characters
Payment subject attribute is the product’s category for the Tax Service.
Possible values:
  • commodity — product;
  • excise — excise goods;
  • job — job;
  • service — service;
  • gambling_bet — a bet in gambling;
  • gambling_prize — gambling winnings;
  • lottery — lottery ticket;
  • lottery_prize — lottery winnigs;
  • intellectual_activity — intellectual property;
  • payment — payment;
  • agent_commission — agent’s commission;
  • property_right — property rights;
  • non_operating_gain — non-operating income;
  • insurance_premium — insurance fee;
  • sales_tax — sales tax;
  • resort_fee — resort fee;
  • composite — several subjects;
  • another — other.
Optional
item.paymentMethodType
string,
128 characters
Payment method attribute is the payment method’s category for the Tax Service.
Possible values:
  • full_prepayment — full prepayment;
  • partial_prepayment — partial prepayment;
  • advance — advance payment;
  • full_payment — full payment;
  • partial_payment — partial payment and loan;
  • credit — loan;
  • credit_payment — loan repayment.
Optional
item.productCode
string
Product code is a unique number assigned to a unit of product during marking.
Format: a hexadecimal number with spaces. Maximum length is 32 bytes. Example: 00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00.
Required parameter if the product is to be marked.
Online sales register that support this parameter: Orange Data, ATOL Online.
item.countryOfOriginCode
string
Country of origin code in accordance with the national Russian classifier of world countries (OК (MК (ИСО 3166) 004-97) 025-2001). Example: RU.
Optional
Online sales register that support this parameter: Orange Data.
item.customsDeclarationNumber
string,
1 to 32 characters
Number of the customs declaration.
Optional
Online sales register that support this parameter: Orange Data.
item.excise
string,
decimal accurate to the hundredths place
The amount of excise tax for the goods including kopeks.
Optional
Online sales register that support this parameter: Orange Data.
Example of the request with parameters for the receipt
XML
<returnPaymentRequest clientOrderId="12345"
           requestDT="2011-07-02T20:38:00.000Z"
           invoiceId="2000000123"
           shopId="6689"
           amount="746.47"
           cause="User refused to accept the order">
 <receipt taxSystem="">
 <customer email="user@example.com"/>
 <items>
 <item quantity="1.324" tax="3" text="Product A"
          paymentMethodType="full_prepayment"
          paymentSubjectType="commodity">
          <price amount="300.22"/>
 </item>
 <item quantity="2" tax="3" text="Product B"
         paymentMethodType="full_prepayment"
         paymentSubjectType="commodity">
         <price amount="200.11"/>
 </item>
 </items>
 </receipt>
 </returnPaymentRequest>
Explanations
Buyer’s contact details
  • In order for the payment to be processed, you’ll need to send the user’s contact information for creating a receipt: a syntactically correct phone number or email address. This information must be included in the customer object or in the customerContact parameter.
  • Fiscal Data Operator (OFD) transmits the receipt to the buyer (conditions of this transmitting depend on your OFD). The receipts are sent to mobile phone numbers of Russian carriers (they all begin with +7). The receipt may fail to be delivered to a non-Russian mobile phone number.
Product quantity, weight, price
  • The item.price.amount field should contain a price for one piece of the product; the item.quantity field should contain the quantity of the products. If the item.price.amount field contains a price for one piece of the product, you need to transmit number of pieces (quantity=2, for instance, two pies of one kind). If the item.price.amount field contains a price for one kilogram of the product, you need to transmit the product’s weight (quantity =1.253, for instance, a pie that weights 1 kg 253 g).
  • Total amount in the receipt should match the return amount. Which means that multiplying item.price.amount by item.quantity should equal amount. If these values do not match, the receipt will not be created.
  • Total amount in the receipt after all calculations should be rounded to the second digit after the point. You sometimes cannot get the exact amount: it is either one kopeck more, or one kopeck less. In this case, you need to transmit the version with the amount one kopeck bigger.
Example:
item.quantity = "0.573", item.price.amount = "17.00", amount = "9.75"
0.573*17=9.741, after rounding — 9.74
0.574*17=9.758, after rounding — 9.76
In this case, specify item.quantity = "0.574"
Response
The response contains parameters that are shared for all types of financial transaction request. If the request included the payment ID older than three years, the refund won’t be processed, and an error (error=616) will be returned in response.
Example of the response
XML
<returnPaymentResponse
         clientOrderId="12345"
         status="0" error="0"
         processedDT="2011-07-02T20:38:01.000Z"
 />
See also
Reports on refunded payments Rules for processing requests Error codes Data types