Уведомление о переводе (paymentAviso) — [Архив] Протокол приема платежей через ЮKassa

Уведомление о переводе (paymentAviso)

Это старая версия API. Переходите на API ЮKassa.

Этим запросом ЮKassa сообщает магазину, что перевод денег пользователя в адрес магазина прошел успешно. Это значит, что магазин обязан выдать пользователю товар или оказать оплаченную услугу.

Запрос

Имя метода: paymentAviso

Адрес для получения запроса

avisoURL

— URL в системе магазина, фиксируется на стороне ЮKassa. Можно указать при подключении.

Входные параметры

Параметр	Тип	Описание
requestDatetime	dateTime	Момент формирования запроса в ЮKassa.
paymentDatetime	dateTime	Момент регистрации оплаты заказа в ЮKassa.
action	normalizedString, до 16 символов	Тип запроса. Значение: `paymentAviso` При обмене данными в формате PKCS#7 передается в качестве открывающего тега XML-документа.
md5	normalizedString, ровно 32 шестнадцатеричных символа, в верхнем регистре	MD5-хэш параметров платежной формы (правила формирования)
shopId	long	Идентификатор магазина, который выдала ЮKassa.
shopArticleId	long	Идентификатор товара, который выдала ЮKassa.
invoiceId	long	Уникальный номер транзакции в ЮKassa.
orderNumber	normalizedString, до 64 символов	Номер заказа в системе магазина. Передается, только если был указан в платежной форме.
customerNumber	normalizedString, до 64 символов	Идентификатор плательщика (присланный в платежной форме) на стороне магазина. Например: номер договора, мобильного телефона и т. п.
orderCreatedDatetime	dateTime	Момент регистрации заказа в ЮKassa.
orderSumAmount	CurrencyAmount	Сумма заказа, присылается в платежной форме в параметре `sum`.
orderSumCurrencyPaycash	CurrencyCode	Код валюты для суммы заказа.
orderSumBankPaycash	CurrencyBank	Код процессингового центра ЮKassa для суммы заказа.
shopSumAmount	CurrencyAmount	Сумма к выплате на счет магазина (сумма заказа минус комиссия ЮKassa).
shopSumCurrencyPaycash	CurrencyCode	Код валюты для `shopSumAmount`.
shopSumBankPaycash	CurrencyBank	Код процессингового центра ЮKassa для `shopSumAmount`.
paymentPayerCode	YMAccount	Номер кошелька ЮMoney, с которого производится оплата.
paymentType	normalizedString	Способ оплаты заказа. Коды способов оплаты
Параметры для B2B-платежей (paymentType=2S)
payment_purpose	string	Назначение платежа.
vatType	string	Тип НДС. Возможные значения: `calculated` — облагается налогом, у всех товаров одинаковая ставка; `untaxed` — не облагается; `mixed` — товары в платеже облагаются налогом по-разному.
vatRate	string	Ставка НДС. Обязательно, если `vatType=calculated`. Возможные значения: `0` — ставка НДС 0%; `7` — ставка 7%; `10` — ставка 10%; `18` — ставка 18%; `20` — ставка 20%.
vatSum	CurrencyAmount	Сумма НДС, которую вы передали в платежной форме. Присутствует, если `vatType=calculated` или `vatType=mixed`.
Реквизиты организации-покупателя для B2B-платежей (`paymentType=2S`)
b2b_full_name	string	Полное наименование организации.
b2b_short_name	string	Сокращенное наименование. Присутствует, если есть.
b2b_adress	string	Адрес.
b2b_inn	string	ИНН.
b2b_kpp	string	КПП.
b2b_bank	string	Наименование банка.
b2b_bank_office	string	Отделение банка.
b2b_bik	string	БИК.
b2b_account	string	Номер счета.
Любые названия, отличные от перечисленных выше	string	Параметры, добавленные магазином в платежную форму.

Запросы могут содержать параметры, не описанные в этом документе. Магазину следует их игнорировать.
Запрос может содержать не все параметры. Обязательно присутствуют только параметры, которые нужны для расчета контрольной суммы MD5 (action, orderSumAmount, orderSumCurrencyPaycash, orderSumBankPaycash, shopId, invoiceId, customerNumber).

Параметры для электронного чека

Эти параметры присутствуют в запросе, если вы настроили взаимодействие со своей облачной кассой через ЮKassa и отправляете в запросе на оплату параметры для формирования чека. См. Отправка данных для чека

Параметр	Тип	Значение
penReceiptDateTime	string	Дата и время формирования чека из фискального накопителя. Формат: `dd.MM.yyyy HH:mm:ss`
penReceiptTotal	decimal, 2 символа после точки	Итоговая сумма в чеке.
penFnNumber	string, до 16 символов	Номер фискального накопителя.
penFiscalDocumentNumber	int	Фискальный номер документа.
penFiscalDocumentAttribute	string, до 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>

Ответ

Параметры ответа

Параметр	Тип	Описание
performedDatetime	dateTime	Момент обработки запроса по часам в ЮKassa. Обязательный
code	int	Код результата обработки. Список допустимых значений приведен в таблице ниже. Обязательный
shopId	long	Идентификатор магазина. Соответствует значению параметра `shopId` в запросе. Обязательный
invoiceId	long	Идентификатор транзакции в ЮKassa. Соответствует значению параметра `invoiceId` в запросе. Обязательный
orderSumAmount	CurrencyAmount	Сумма заказа в валюте, определенной параметром запроса `orderSumCurrencyPaycash`. Необязательный
message	string, до 255 символов	Текстовое пояснение в случае отказа принять платеж. Необязательный
techMessage	string, до 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 не совпадает с результатом расчета хэш-функции"
/>