API ЮKassa
Помощь
Подключить ЮKassa
Уведомление о переводе (paymentAviso)
Этим запросом ЮKassa сообщает магазину, что перевод денег пользователя в адрес магазина прошел успешно. Это значит, что магазин обязан выдать пользователю товар или оказать оплаченную услугу.
Запрос
Имя метода: paymentAviso
Адрес для получения запроса
avisoURL
 — URL в системе магазина, фиксируется на стороне ЮKassa. Можно указать при подключении.
Входные параметры
ПараметрТипОписание
requestDatetimedateTimeМомент формирования запроса в ЮKassa.
paymentDatetimedateTimeМомент регистрации оплаты заказа в ЮKassa.
actionnormalizedString,
до 16 символов
Тип запроса. Значение: paymentAviso
При обмене данными в формате PKCS#7 передается в качестве открывающего тега XML-документа.
md5normalizedString,
ровно 32 шестнадцатеричных символа, в верхнем регистре
MD5-хэш параметров платежной формы (правила формирования)
shopIdlongИдентификатор магазина, который выдала ЮKassa.
shopArticleIdlongИдентификатор товара, который выдала ЮKassa.
invoiceIdlongУникальный номер транзакции в ЮKassa.
orderNumbernormalizedString,
до 64 символов
Номер заказа в системе магазина. Передается, только если был указан в платежной форме.
customerNumbernormalizedString,
до 64 символов
Идентификатор плательщика (присланный в платежной форме) на стороне магазина.
Например: номер договора, мобильного телефона и т. п.
orderCreatedDatetimedateTimeМомент регистрации заказа в ЮKassa.
orderSumAmountCurrencyAmountСумма заказа, присылается в платежной форме в параметре sum.
orderSumCurrencyPaycashCurrencyCodeКод валюты для суммы заказа.
orderSumBankPaycashCurrencyBankКод процессингового центра ЮKassa для суммы заказа.
shopSumAmountCurrencyAmountСумма к выплате на счет магазина (сумма заказа минус комиссия ЮKassa).
shopSumCurrencyPaycashCurrencyCodeКод валюты для shopSumAmount.
shopSumBankPaycashCurrencyBankКод процессингового центра ЮKassa для shopSumAmount.
paymentPayerCodeYMAccountНомер кошелька ЮMoney, с которого производится оплата.
paymentTypenormalizedStringСпособ оплаты заказа. Коды способов оплаты
Параметры для B2B-платежей (paymentType=2S)
payment_purposestringНазначение платежа.
vatTypestring
Тип НДС. Возможные значения:
  • calculated — облагается налогом, у всех товаров одинаковая ставка;
  • untaxed — не облагается;
  • mixed — товары в платеже облагаются налогом по-разному.
vatRatestring
Ставка НДС. Обязательно, если vatType=calculated.
Возможные значения:
  • 0 — ставка НДС 0%;
  • 7 — ставка 7%;
  • 10 — ставка 10%;
  • 18 — ставка 18%;
  • 20 — ставка 20%.
vatSumCurrencyAmountСумма НДС, которую вы передали в платежной форме. Присутствует, если vatType=calculated или vatType=mixed.
Реквизиты организации-покупателя для B2B-платежей (paymentType=2S)
b2b_full_namestringПолное наименование организации.
b2b_short_namestringСокращенное наименование. Присутствует, если есть.
b2b_adressstringАдрес.
b2b_innstringИНН.
b2b_kppstringКПП.
b2b_bankstringНаименование банка.
b2b_bank_officestringОтделение банка.
b2b_bikstringБИК.
b2b_accountstringНомер счета.
Любые названия, отличные от перечисленных вышеstringПараметры, добавленные магазином в платежную форму.
Параметры для электронного чека
Эти параметры присутствуют в запросе, если вы настроили взаимодействие со своей облачной кассой через ЮKassa и отправляете в запросе на оплату параметры для формирования чека. См. Отправка данных для чека
ПараметрТипЗначение
penReceiptDateTimestring
Дата и время формирования чека из фискального накопителя.
Формат: dd.MM.yyyy HH:mm:ss
penReceiptTotaldecimal,
2 символа после точки
Итоговая сумма в чеке.
penFnNumberstring,
до 16 символов
Номер фискального накопителя.
penFiscalDocumentNumberintФискальный номер документа.
penFiscalDocumentAttributestring,
до 19 символов
Фискальный признак документа.
Если уведомление о переводе не доставлено (магазин не отвечает на многократные запросы paymentAviso или выдает технические ошибки), по умолчанию платеж считается неуспешным. Это значит, что ЮKassa прекращает попытки доставки уведомления, помечает платеж как недоставленный и не помещают его в реестр принятых переводов. Сумма неуспешного перевода будет автоматически возвращена плательщику. Магазин может обнаружить «потерянные» уведомления путем сверки с использованием методов Управления заказами (MWS).
Вы можете выбрать другой вариант обработки недоставленных уведомлений и считать такие платежи успешными. В таком случае ЮKassa прекращает попытки доставки уведомления и помечают перевод как успешный. Перевод будет включен в реестр принятых переводов согласно времени последней попытки доставки paymentAviso. Магазин может обнаружить «потерянные уведомления» путем сверки с реестром или с использованием методов Управления заказами (MWS).
Поменять обработку этой ситуации можно по запросу. Если вы хотите считать недоставленные уведомления успешными, сообщите об этому менеджеру ЮKassa.
При оплате через B2B-платежи (paymentType=2S) платеж считается успешным в любом случае — независимо от вашего ответа на уведомление о переводе.
Примеры запроса
Пример запроса с использованием контрольной суммы MD5
POST /path_to_paymentAviso HTTP/1.1
Host: someshop.ru
Content-Type: application/x-www-form-urlencoded
Параметры запроса (пример):
  • 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: Дополнительное поле, добавленное магазином
Пример запроса в формате PKCS#7
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="Дополнительное поле 1"></param>
    <param key="additionalField2" val="Дополнительное поле 2"></param>
</paymentAvisoRequest>
Ответ
Параметры ответа
ПараметрТипОписание
performedDatetimedateTime
Момент обработки запроса по часам в ЮKassa.
Обязательный
codeint
Код результата обработки. Список допустимых значений приведен в таблице ниже.
Обязательный
shopIdlong
Идентификатор магазина. Соответствует значению параметра shopId в запросе.
Обязательный
invoiceIdlong
Идентификатор транзакции в ЮKassa. Соответствует значению параметра invoiceId в запросе.
Обязательный
orderSumAmountCurrencyAmount
Сумма заказа в валюте, определенной параметром запроса orderSumCurrencyPaycash.
Необязательный
messagestring,
до 255 символов
Текстовое пояснение в случае отказа принять платеж.
Необязательный
techMessagestring,
до 64 символов
Дополнительное текстовое пояснение ответа магазина.
Как правило, используется как дополнительная информация об ошибках. Необязательное поле.
Необязательный
Коды результата обработки запроса
КодЗначениеОписание ситуации
0УспешноМагазин дал согласие и готов принять перевод.
1Ошибка авторизацииНесовпадение значения параметра md5 с результатом расчета хэш-функции. Окончательная ошибка.
200Ошибка разбора запросаМагазин не в состоянии разобрать запрос. Окончательная ошибка.
Примеры ответа
Пример ответа при успехе обработки
XML
<paymentAvisoResponse
  performedDatetime="2011-05-04T20:38:11.000+04:00"
  code="0"
  invoiceId="1234567"
  shopId="13"
/>
Пример ответа при ошибке
XML
<paymentAvisoResponse
  performedDatetime="2011-05-04T20:38:11.000+04:00"
  code="1"
  message="Значение параметра md5 не совпадает с результатом расчета хэш-функции"
/>