returnPayment method — [Archive] Payment solution protocol for merchants

returnPayment method

This is an old version of the API. Switch to the YooMoney API.

Description

Refunding a successful payment to the payer’s account.

Availability of the refund option depends on the date the order was registered with YooMoney (orderCreatedDatetime in order verification notification):

for all payment methods except SberPay: the transfer can be returned only within three years from the date of registration of the order with YooMoney;
for SberPay: refunds can only be made within one year since the order was registered;
for bank cards, Mir Pay: acquirers may refuse to return transfers for orders registered more than 15 months ago for technical reasons.

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.

For some payment methods, refunds using returnPayment are not possible.

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:

the cryptographic message is sent in the body of a POST request. MIME type: application/pkcs7-mime;
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

Parameter	Type	Description
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.
requestDT	dateTime	Time when the request to perform the operation was formed, according to the merchant’s system.
invoiceId	long	Transaction number of the transfer being refunded. A successful payment can only be refunded within three years since the date of order registration (`orderCreatedDatetime` in order verification notification).
shopId	long	Store ID issued by YooMoney.
amount	CurrencyAmount	The amount to refund to the Payer’s account.
currency	CurrencyCode	Currency code for the payment being refunded.
cause	string, maximum of 255 characters	Description of the reason for return.
receipt	string	Data 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).

Parameter	Type	Description
customerContact	string, 64 characters	The `customerContact` parameter is now deprecated. You can still use it but we recommend sending the data in the `customer` parameter. 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.

The customerContact parameter is now deprecated. You can still use it but we recommend sending the data in the customer object.

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"
 />