returnPayment method

Description

Refunding a successful payment to the payer's account.

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, Yandex.Checkout 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.

Restriction. 

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

Address for calling the returnPayment operation

https://server:port/webservice/mws/api/returnPayment
Note. 

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 Yandex.Checkout server:

  1. Forming a document order to execute the operation The document is formed according to the XML 1.0 standard (Fifth Edition), which is published at: http://www.w3.org/TR/xml/. The document must be UTF-8 encoded, according to the standard http://www.ietf.org/rfc/rfc2279.txt.
  2. Forming a cryptographic message The prepared document is put in a PKCS#7 cryptographic message container conforming to the http://www.ietf.org/rfc/rfc5652.txt standard. 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 (http://www.ietf.org/rfc/rfc2459.txt).
  3. Forming and passing a request to Yandex.Checkout The merchant generates a POST request according to the HTTP/1.1 protocol (http://www.ietf.org/rfc/rfc2616.txt, http://www.ietf.org/rfc/rfc2618.txt). 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 http://www.ietf.org/rfc/rfc2388.txt).

To authorize requests, Yandex.Checkout verifies the digital signature of the cryptographic message.

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

Note. 
  • 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 Yandex.Checkout 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 Yandex.Checkout 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.

shopId

long

Store ID issued by Yandex.Checkout.

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

Parameters for the receipt

These parameters are required (and are mandatory for transmitting) if you set up interaction with your online sales register via Yandex.Checkout. See Description of payment process where data for the receipt are transmitted

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

NecessityDescription

customerContact

string, 64 characters

Mandatory

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.

taxSystem

int

Optional

Store's Tax System (STS). The parameters is only required if you user several tax systems. If not, 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.

items

Object

Mandatory

All products in the order.

item.quantity

Decimal accurate to the thousandth place

Mandatory

Product quantity. Defines the quantity of products in the order or quantity of products sold by weight.

item.price

Object

Mandatory

item.price.amount

CurrencyAmount (decimal accurate to the hundredths place)

Mandatory

Price per unit.

item.price.currency

CurrencyCode

Optional

Currency code: 643 (Russian ruble).

item.tax

int

Mandatory

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 18%

5—VAT of the receipt at the applicable rate of 10/110

6—VAT of the receipt at the applicable rate of 18/118.

text

string, 128 characters

Mandatory

Product name.

Explanations

Buyer's contact details

  • The customerContact field is mandatory. In this field, you need to transmit syntactically correct phone number or email address. If the field is empty or contains incorrect data, the operation won't come through.
  • 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 you need to transmit item.quantity = "0.574"

Output parameters

The response contains parameters that are shared for all types of financial transaction request.

Examples

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
<returnPaymentRequest
        clientOrderId="12345"
        requestDT="2011-07-02T20:38:00.000Z"
        invoiceId="2000000123"
        shopId="6689"
        amount="10.00"
        currency="643"
        cause="User declined the order"
        />
Example of the request with parameters for the receipt
<returnPaymentRequest clientOrderId="12345"
 requestDT="2011-07-02T20:38:00.000Z"
 invoiceId="2000000123"
 shopId="6689"
 amount="746.47"
 cause="User declined the order">
 <receipt customerContact="+79123456543" taxSystem=""> 
 <items>
 <item quantity="1.324" tax="3" text="Product A">
 <price amount="300.22"/>
 </item>
 <item quantity="2" tax="3" text="Product B">
 <price amount="200.11"/>
 </item>
 </items>
 </receipt>
 </returnPaymentRequest>
Response example
<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