API ЮKassa
Помощь
Подключить ЮKassa
Параметры для формирования чека
Параметры для передачи фискальных данных добавляются в стандартную платежную форму. Они обязательно передаются, если вы настраиваете взаимодействие со своей онлайн-кассой через ЮKassa (для этого необходимо подключить онлайн-кассу одного из наших партнеров и выставить соответствующие настройки в личном кабинете, см. Оплата по 54-ФЗ).
В форму добавляется один дополнительный параметр ym_merchant_receipt (тип string), в котором передаются все нужные данные в формате JSON.
Формат данных для чека
Данные для чека передаются в JSON. Параметры customer и taxSystem (необязательный) передаются в формате «ключ»—«значение». Вместе с ними передается массив товаров, в который входят товары с характеристиками. Характеристики товара отправляются в одном объекте, для каждого товара формируется свой объект.
Пример данных в JSON
JSON
{
    "customer": {
        "email": "user@example.com"
    },
    "taxSystem": 1,
    "items": [{
        "quantity": 1.154,
        "price": {
            "amount": 300.23
        },
        "tax": 3,
        "text": "Зеленый чай \"Юн Ву\", кг",
        "paymentMethodType": "full_prepayment ",
        "paymentSubjectType": "commodity"
    },
    {
        "quantity": 2,
        "price": {
            "amount": 200.00
        },
        "tax": 3,
        "text": "Кружка для чая, шт., скидка 10%",
        "paymentMethodType": "full_prepayment",
        "paymentSubjectType": "commodity"
    }]
}
Параметры для чека
ПараметрТипОписание
customerОбъект
Информация о пользователе.
Обязательный, если не передан customerContact
customerContactstring, 64 символа
Телефон или эл. почта покупателя.
Ограничения:
  • номер телефона в формате +79210000000 или адрес электронной почты (проверяется соответствие);
  • следует передавать что-то одно: только адрес почты или только телефон;
  • не следует передавать несколько адресов или телефонов.
Обязательный, если не передан customer
taxSystemint
Система налогообложения магазина (СНО). Параметр необходим, только если у вас несколько систем налогообложения. В остальных случаях не передается.
Возможные значения — число от 1 до 6:
  • 1 — общая СН;
  • 2 — упрощенная СН (доходы);
  • 3 — упрощенная СН (доходы минус расходы);
  • 4 — единый налог на вмененный доход;
  • 5 — единый сельскохозяйственный налог;
  • 6 — патентная СН.
Важно: товары с разным значением taxSystem необходимо передавать в разных чеках.
Необязательный
itemsОбъект
Товары
Обязательный
Параметры вложенных объектов
ПараметрТипОписание
Пользователь (customer)
fullNamestring, не более 256 символов
Для юрлица — название организации, для ИП и физического лица — ФИО. Если у физлица отсутствует ИНН, в этом же параметре передаются паспортные данные.
Необязательный
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, АТОЛ Онлайн.
innstring
ИНН пользователя (10 или 12 цифр). Если у физического лица отсутствует ИНН, необходимо передать паспортные данные в параметре customer.fullName.
Необязательный
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, АТОЛ Онлайн.
emailstring
Электронная почта пользователя для отправки чека.
Обязательный, если не передан phone или customerContact.
phonestring
Телефон пользователя для отправки чека. Указывается в формате ITU-T E.164, например +79000000000.
Обязательный, если не передан email или customerContact.
Товар (items)
quantityДесятичное число. Максимально возможное значение и максимальное количество знаков после точки зависят от модели вашей онлайн-кассы
Количество товара. Описывает количество товаров в заказе или количество весового товара.
Обязательный
priceОбъект
Цена товара.
Обязательный
amountCurrencyAmount (десятичное число с точностью до 2 символов после точки)
Цена за единицу товара.
Обязательный
currencyCurrencyCode
Код валюты: RUB (рубль РФ).
Необязательный
taxint
Ставка НДС. Возможные значения — число от 1 до 6:
  • 1 — без НДС;
  • 2 — ставка НДС 0%;
  • 3 — ставка 10%;
  • 4 — ставка 20%;
  • 5 — расчетная ставка 10/110;
  • 6 — расчетная ставка 20/120.
Обязательный
text
string, 128 символов
кириллица или латиница
Название товара.
Ограничения: специальные символы (например, кавычки) необходимо экранировать по правилам JSON. Пример: "text": "Зеленый чай \"Юн Ву\", кг"
Обязательный
paymentSubjectTypestring, 128 символов
Признак предмета расчета — категория этого товара для налоговой.
Возможные значения:
  • commodity — товар;
  • excise — подакцизный товар;
  • job — работа;
  • service — услуга;
  • gambling_bet — ставка в азартной игре;
  • gambling_prize — выигрыш в азартной игре;
  • lottery — лотерейный билет;
  • lottery_prize — выигрыш в лотерею;
  • intellectual_activity — результаты интеллектуальной деятельности;
  • payment — платеж;
  • agent_commission — агентское вознаграждение;
  • property_right — имущественные права;
  • non_operating_gain — внереализационный доход;
  • insurance_premium — страховой сбор;
  • sales_tax — торговый сбор;
  • resort_fee — курортный сбор;
  • composite — несколько вариантов;
  • another — другое.
Необязательный
paymentMethodTypestring, 128 символов
Признак способа расчета — категория способа оплаты для налоговой.
Возможные значения:
  • full_prepayment — полная предоплата;
  • partial_prepayment — частичная предоплата;
  • advance — аванс;
  • full_payment — полный расчет;
  • partial_payment — частичный расчет и кредит;
  • credit — кредит;
  • credit_payment — выплата по кредиту.
Необязательный
productCodestring
Код товара — уникальный номер, который присваивается экземпляру товара при маркировке.
Формат: число в шестнадцатеричном представлении с пробелами. Максимальная длина — 32 байта. Пример: 00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00.
Обязательный параметр, если товар нужно маркировать.
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, АТОЛ Онлайн.
countryOfOriginCodestring
Код страны происхождения товара по общероссийскому классификатору стран мира (ОК (МК (ИСО 3166) 004-97) 025-2001). Пример: RU.
Необязательный
Онлайн-кассы, которые поддерживают этот параметр: Orange Data.
customsDeclarationNumberstring, от 1 до 32 символов
Номер таможенной декларации.
Необязательный
Онлайн-кассы, которые поддерживают этот параметр: Orange Data.
excisestring, десятичное число с точностью до 2 символов после точки
Сумма акциза товара с учетом копеек.
Необязательный
Онлайн-кассы, которые поддерживают этот параметр: Orange Data.
Пояснения
Контакты покупателя
  • Чтобы платеж прошел, необходимо передать контактные данные пользователя для отправки чека — синтаксически корректный номер телефона или адрес электронной почты. Эти данные нужно передать в объекте customer или в параметре customerContact.
  • Чек покупателю доставляет ОФД (условия доставки зависят от вашего ОФД). Чеки приходят на мобильные номера российских операторов (они начинаются с +7). На иностранный мобильный номер чек может не дойти.
Количество товаров, вес, цена
  • В поле amount указывается цена за единицу товара, в поле quantity — количество. Если в amount указана цена за один товар, следует передавать количество штук (quantity=2, например два одинаковых пирога). Если в amount указана цена за кг, следует передавать вес товара (quantity=1.253, например пирог весом 1 кг 253 г).
  • Цена указывается без учета налогов.
  • Общая сумма, которую вы передаете в ym_merchant_receipt, должна совпадать с суммой в sum. Если они не совпадают, чек не сформируется, оплата может не пройти.
  • В ym_merchant_receipt можно передать не больше 100 товаров — то есть не больше 100 таких блоков: {"quantity": 1.154,"price": {"amount": 300.23},"tax": 3,"text": "Товар А"}
  • Информацию о скидке или предоплате можно добавить в название товара. Пример: "text": "Предоплата 30%, настольная игра \"Tea Time\""}
Пример платежной формы
Пример платежной формы с параметрами для чека
HTML
<form action="https://yoomoney.ru/eshop.xml" method="post">
        <input name="shopId" value="1234" type="hidden"/>
        <input name="scid" value="4321" type="hidden"/>
        <input name="sum" value="746.47" type="hidden" />
        <input name="customerNumber" value="abc000" type="hidden"/>
        <input name="paymentType" value="AC" type="hidden"/>
        <input name="orderNumber" value="abc1111111" type="hidden"/>
        <input name="cps_phone" value="+79123456543" type="hidden"/>
        <input name="cps_email" value="user@domain.com" type="hidden"/>
        <input name="ym_merchant_receipt" value='{"customerContact": "+79001231212","taxSystem": 1, "items":[{"quantity": 1.154, "price": {"amount": 300.23},  "tax": 3,"text": "Зеленый чай \"Юн Ву\", кг","paymentMethodType": "full_prepayment ","paymentSubjectType": "commodity"},{"quantity": 2, "price": {"amount": 200.00},  "tax": 3,"text": "Кружка для чая, шт., скидка 10%","paymentMethodType": "full_prepayment ","paymentSubjectType": "commodity"}]}'
        type="hidden"/>
        <input type="submit" value="Заплатить"/>
</form>
Что почитать еще
Оплата по 54-ФЗОтправка данных для чека