Payment notification (paymentAviso)

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

YooMoney uses this request to tell the merchant that the user’s money was successfully transferred to the merchant’s address. This means that the merchant is obligated to provide the user with the product or service that was paid for.

Request

Method name: paymentAviso

Address for receiving request

avisoURL — The URL in the merchant’s system. Stored on YooMoney. You can set it during activation.

Request parameters

Parameter	Type	Description
requestDatetime	dateTime	Time when request was formed in YooMoney.
paymentDatetime	dateTime	Time when the order payment was registered in YooMoney.
action	normalizedString, maximum 16 characters	Request type. Value: `paymentAviso` When exchanging data in PKCS#7 format, it is passed as the opening tag of an XML document.
md5	normalizedString, exactly 32 uppercase hexadecimal characters	MD5 hash of the payment form parameters (rules for forming it)
shopId	long	Merchant ID issued by YooMoney.
shopArticleId	long	Product ID issued by YooMoney.
invoiceId	long	Unique transaction number in YooMoney.
orderNumber	normalizedString, maximum 64 characters	Order number in merchant’s system. Passed only if it was indicated in the payment form.
customerNumber	normalizedString, maximum 64 characters	Customer ID assigned by merchant (sent in the payment form). For example, the contract number, phone number, etc.
orderCreatedDatetime	dateTime	Time when order was registered in YooMoney.
orderSumAmount	CurrencyAmount	The order total sent in the `sum` parameter in the payment form.
orderSumCurrencyPaycash	CurrencyCode	Currency code for the order amount.
orderSumBankPaycash	CurrencyBank	YooMoney processing center code for order total.
shopSumAmount	CurrencyAmount	Total to be paid into merchant’s account (order total minus YooMoney commission).
shopSumCurrencyPaycash	CurrencyCode	Currency code for `shopSumAmount`.
shopSumBankPaycash	CurrencyBank	YooMoney processing center code for `shopSumAmount`.
paymentPayerCode	YMAccount	YooMoney account number used for payment.
paymentType	normalizedString	Payment method for order. Payment method codes
Parameters for B2B payments (paymentType=2S)
payment_purpose	string	Payment purpose.
vatType	string	Type of VAT. Possible values: `calculated` — taxable, all products have the same rate; `untaxed` — non-taxable; `mixed` — products in the payment are taxed differently.
vatRate	string	VAT rate. Required if `vatType=calculated`. Possible values: `0` — 0% VAT rate; `7` — 7% VAT rate; `10` — 10% VAT rate; `18` — 18% VAT rate; `20` — 20% VAT rate.
vatSum	CurrencyAmount	The VAT amount you sent in the payment form. Shown if `vatType=calculated` or `vatType=mixed`.
Information about the buyer company for B2B payments (`paymentType=2S`)
b2b_full_name	string	Full name of the organization.
b2b_short_name	string	Abbreviated name. Shown if available.
b2b_adress	string	Address.
b2b_inn	string	INN (TIN).
b2b_kpp	string	KPP (TRRC).
b2b_bank	string	Name of the bank.
b2b_bank_office	string	Bank branch.
b2b_bik	string	BIC.
b2b_account	string	Account number.
Any names other than those listed above	string	Parameters added to the payment form by the merchant.

YooMoney requests may contain parameters not described in this document. The merchant should ignore them.
Requests don’t have to contain all the parameters. Only parameters that are needed for calculating the MD5 checksum are required (action, orderSumAmount, orderSumCurrencyPaycash, orderSumBankPaycash, shopId, invoiceId, customerNumber).

Parameters for electronic payment receipt

These parameters are present in the request if you set up interaction with your cloud sales register via YooMoney and transfer parameters for creating a receipt in the payment request. See Sending details for the receipt

Parameter	Type	Value
penReceiptDateTime	string	Date and time of creating the receipt as recorded in the fiscal storage. Format: `dd.MM.yyyy HH:mm:ss`
penReceiptTotal	decimal, 2 digits after the point	Total amount in the receipt.
penFnNumber	string, maximum of 16 characters	Number of the fiscal storage.
penFiscalDocumentNumber	int	Fiscal number of the document.
penFiscalDocumentAttribute	string, maximum of 19 characters	Fiscal feature of the document.

If the payment notification was not delivered (the merchant does not respond to repeated paymentAviso requests, or returns technical errors), the payment is considered unsuccessful by default. This means that YooMoney stops attempting to deliver notifications, marks the payment as undelivered, and does not enter it in the report of accepted payments. The amount of the unsuccessful payment will be automatically returned to the payer. The merchant can find “lost” notifications by using payment management (MWS) methods for cross-checking.

If you want these payments to be considered successful, you can choose a different processing option for undelivered notifications. In this case, YooMoney stops attempting to deliver notifications and marks the transfer as successful. The payment will be included in the accepted payments report according to the time of the last attempt to deliver the paymentAviso request. The merchant can then find these “lost notifications” by checking the report or by using payment management (MWS) methods.

You can change how this situation is handled on request. If you want to consider undelivered notifications successful, inform your YooMoney manager.

When paying via B2B payments (paymentType=2S) the payment is considered successful in any case, regardless of your response to the notification of payment.

Request examples

Request example using an MD5 checksum

POST /path_to_paymentAviso HTTP/1.1
Host: someshop.ru
Content-Type: application/x-www-form-urlencoded

Request parameters (example):

requestDatetime: 2011-05-04T20:38:00.000+04:00
action: paymentAviso
md5: 45125C95A20A7F25B63D58EA304AFED2
shopId: 13
shopArticleId: 456
invoiceId: 1234567
customerNumber: 8123294469
orderCreatedDatetime: 2011-05-04T20:38:00.000+04:00
orderSumAmount: 87.10
orderSumCurrencyPaycash: 643
orderSumBankPaycash: 1001
shopSumAmount: 86.23
shopSumCurrencyPaycash: 643
shopSumBankPaycash: 1001
paymentDatetime: 2011-05-04T20:38:10.000+04:00
paymentPayerCode: 42007148320
paymentType: AC
additionalField: Additional field added by the merchant

Request example in PKCS#7 format

POST /path_to_paymentAviso HTTP/1.1
Host: someshop.ru
Content-Type: application/pkcs7-mime
<?xml version="1.0" encoding="UTF-8"?>
<paymentAvisoRequest
        requestDatetime="2011-05-04T20:38:00.000+04:00"
        invoiceId="1234567"
        shopId="13"
        shopArticleId="456"
        customerNumber="8123294469"
        orderCreatedDatetime="2011-05-04T20:38:00.000+04:00"
        paymentPayerCode="42007148320"
        orderSumAmount="87.10"
        orderSumCurrencyPaycash="643"
        orderSumBankPaycash="1001"
        shopSumAmount="86.23"
        shopSumCurrencyPaycash="643"
        shopSumBankPaycash="1001"
        paymentDatetime="2011-05-04T20:38:10.000+04:00"
        paymentType="AC">
    <param key="additionalField1" val="Additional field 1"></param>
    <param key="additionalField2" val="Additional field 2"></param>
</paymentAvisoRequest>

Response

Response parameters

Parameter	Type	Description
performedDatetime	dateTime	Time in merchant’s system when request was processed. Required
code	int	Code of the processing result. The table below lists possible values. Required
shopId	long	Store ID. Must match the `shopId` field in the request. Required
invoiceId	long	YooMoney transaction ID. Must match the `invoiceId` field in the request. Required
orderSumAmount	CurrencyAmount	The amount of the order in the currency defined by the `orderSumCurrencyPaycash` request parameter. Optional
message	string, maximum of 255 characters	Text explanation if the payment is not accepted. Optional
techMessage	string, maximum of 64 characters	Explanation of the merchant’s response. This is usually used for more detailed information about errors. Optional field. Optional

Request processing result codes

Code	Value	Description
0	Successful	The merchant agreed and is ready to accept the transfer.
1	Authorization error	`md5` parameter does not match result of calculating hash function. Fatal error.
200	Request parsing error	Merchant is not able to parse request. Fatal error.

Response examples

Response example for successful processing

XML
<paymentAvisoResponse
  performedDatetime="2011-05-04T20:38:11.000+04:00"
  code="0"
  invoiceId="1234567"
  shopId="13"
/>

Response example with error

XML
<paymentAvisoResponse
  performedDatetime="2011-05-04T20:38:11.000+04:00"
  code="1"
  message="Значение параметра md5 не совпадает с результатом расчета хэш-функции"
/>