Архив
 
Уведомление о переводе (paymentAviso)
Это старая версия API. Переходите на API ЮKassa.
Этим запросом Ю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Параметры, добавленные магазином в платежную форму.
  • Запросы могут содержать параметры, не описанные в этом документе. Магазину следует их игнорировать.
  • Запрос может содержать не все параметры. Обязательно присутствуют только параметры, которые нужны для расчета контрольной суммы MD5 (
    action
    ,
    orderSumAmount
    ,
    orderSumCurrencyPaycash
    ,
    orderSumBankPaycash
    ,
    shopId
    ,
    invoiceId
    ,
    customerNumber
    ).
 
Параметры для электронного чека
Эти параметры присутствуют в запросе, если вы настроили взаимодействие со своей облачной кассой через Ю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 не совпадает с результатом расчета хэш-функции"
/>