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:
|
vatRate | string | VAT rate. Required if vatType=calculated .Possible values:
|
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 не совпадает с результатом расчета хэш-функции" />