YooMoney API
Old versions of the API
Help
Sign up for YooMoney
Payment notification (paymentAviso)
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
ParameterTypeDescription
requestDatetimedateTimeTime when request was formed in YooMoney.
paymentDatetimedateTimeTime 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.
md5normalizedString,
exactly 32 uppercase hexadecimal characters
MD5 hash of the payment form parameters (rules for forming it)
shopIdlongMerchant ID issued by YooMoney.
shopArticleIdlongProduct ID issued by YooMoney.
invoiceIdlongUnique transaction number in YooMoney.
orderNumbernormalizedString,
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.
orderCreatedDatetimedateTimeTime when order was registered in YooMoney.
orderSumAmountCurrencyAmountThe order total sent in the sum parameter in the payment form.
orderSumCurrencyPaycashCurrencyCodeCurrency code for the order amount.
orderSumBankPaycashCurrencyBankYooMoney processing center code for order total.
shopSumAmountCurrencyAmountTotal to be paid into merchant’s account (order total minus YooMoney commission).
shopSumCurrencyPaycashCurrencyCodeCurrency code for shopSumAmount.
shopSumBankPaycashCurrencyBankYooMoney processing center code for shopSumAmount.
paymentPayerCodeYMAccountYooMoney account number used for payment.
paymentTypenormalizedStringPayment method for order. Payment method codes
Parameters for B2B payments (paymentType=2S)
payment_purposestringPayment 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.
vatSumCurrencyAmountThe 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_namestringFull name of the organization.
b2b_short_namestringAbbreviated name. Shown if available.
b2b_adressstringAddress.
b2b_innstringINN (TIN).
b2b_kppstringKPP (TRRC).
b2b_bankstringName of the bank.
b2b_bank_officestringBank branch.
b2b_bikstringBIC.
b2b_accountstringAccount number.
Any names other than those listed abovestringParameters added to the payment form by the merchant.
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
ParameterTypeValue
penReceiptDateTime
string
Date and time of creating the receipt as recorded in the fiscal storage.
Format: dd.MM.yyyy HH:mm:ss
penReceiptTotaldecimal,
2 digits after the point
Total amount in the receipt.
penFnNumberstring,
maximum of 16 characters
Number of the fiscal storage.
penFiscalDocumentNumberintFiscal number of the document.
penFiscalDocumentAttributestring,
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
ParameterTypeDescription
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
CodeValueDescription
0SuccessfulThe merchant agreed and is ready to accept the transfer.
1Authorization errormd5 parameter does not match result of calculating hash function. Fatal error.
200Request parsing errorMerchant 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 не совпадает с результатом расчета хэш-функции"
/>