Параметры для формирования чека — [Архив] Протокол приема платежей через ЮKassa

Параметры для формирования чека

Это старая версия API. Переходите на API Ю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	Объект	Информация о пользователе. См. Параметры вложенных объектов — customer Обязательный, если не передан `customerContact`
customerContact	string, 64 символа	Параметр `customerContact` устарел. Его всё еще можно использовать, но рекомендуется передавать данные в параметре `customer`. Телефон или эл. почта покупателя. Ограничения: номер телефона в формате `+79210000000` или адрес электронной почты (проверяется соответствие); следует передавать что-то одно: только адрес почты или только телефон; не следует передавать несколько адресов или телефонов. Обязательный, если не передан `customer`
taxSystem	int	Система налогообложения магазина (СНО). Параметр необходим, только если у вас несколько систем налогообложения. В остальных случаях не передается. Возможные значения — число от 1 до 6: `1` — общая СН; `2` — упрощенная СН (доходы); `3` — упрощенная СН (доходы минус расходы); `4` — единый налог на вмененный доход; `5` — единый сельскохозяйственный налог; `6` — патентная СН. Важно: товары с разным значением `taxSystem` необходимо передавать в разных чеках. Необязательный
items	Объект	Товары См. Параметры вложенных объектов — items Обязательный

Параметры вложенных объектов

Параметр	Тип	Описание
Пользователь (customer)
fullName	string, не более 256 символов	Для юрлица — название организации, для ИП и физического лица — ФИО. Если у физлица отсутствует ИНН, в этом же параметре передаются паспортные данные. Необязательный Онлайн-кассы, которые поддерживают этот параметр: Orange Data, АТОЛ Онлайн.
inn	string	ИНН пользователя (10 или 12 цифр). Если у физического лица отсутствует ИНН, необходимо передать паспортные данные в параметре `customer.fullName`. Необязательный Онлайн-кассы, которые поддерживают этот параметр: Orange Data, АТОЛ Онлайн.
email	string	Электронная почта пользователя для отправки чека. Обязательный, если не передан `phone` или `customerContact`.
phone	string	Телефон пользователя для отправки чека. Указывается в формате ITU-T E.164, например `+79000000000`. Обязательный, если не передан `email` или `customerContact`.
Товар (items)
quantity	Десятичное число. Максимально возможное значение и максимальное количество знаков после точки зависят от модели вашей онлайн-кассы	Количество товара. Описывает количество товаров в заказе или количество весового товара. Обязательный
price	Объект	Цена товара. Обязательный
amount	CurrencyAmount (десятичное число с точностью до 2 символов после точки)	Цена за единицу товара. Обязательный
currency	CurrencyCode	Код валюты: `RUB` (рубль РФ). Необязательный
tax	int	Ставка НДС. Возможные значения — число от 1 до 6: `1` — без НДС; `2` — ставка НДС 0%; `3` — ставка 10%; `4` — ставка 20%; `5` — расчетная ставка 10/110; `6` — расчетная ставка 20/120. Обязательный
text	string, 128 символов кириллица или латиница	Название товара. Ограничения: специальные символы (например, кавычки) необходимо экранировать по правилам JSON. Пример: `"text": "Зеленый чай \"Юн Ву\", кг"` Обязательный
paymentSubjectType	string, 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` — другое. Необязательный
paymentMethodType	string, 128 символов	Признак способа расчета — категория способа оплаты для налоговой. Возможные значения: `full_prepayment` — полная предоплата; `partial_prepayment` — частичная предоплата; `advance` — аванс; `full_payment` — полный расчет; `partial_payment` — частичный расчет и кредит; `credit` — кредит; `credit_payment` — выплата по кредиту. Необязательный
productCode	string	Код товара — уникальный номер, который присваивается экземпляру товара при маркировке. Формат: число в шестнадцатеричном представлении с пробелами. Максимальная длина — 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, АТОЛ Онлайн.
countryOfOriginCode	string	Код страны происхождения товара по общероссийскому классификатору стран мира (ОК (МК (ИСО 3166) 004-97) 025-2001). Пример: `RU`. Необязательный Онлайн-кассы, которые поддерживают этот параметр: Orange Data.
customsDeclarationNumber	string, от 1 до 32 символов	Номер таможенной декларации. Необязательный Онлайн-кассы, которые поддерживают этот параметр: Orange Data.
excise	string, десятичное число с точностью до 2 символов после точки	Сумма акциза товара с учетом копеек. Необязательный Онлайн-кассы, которые поддерживают этот параметр: Orange Data.

Пояснения

Контакты покупателя

Чтобы платеж прошел, необходимо передать контактные данные пользователя для отправки чека — синтаксически корректный номер телефона или адрес электронной почты. Эти данные нужно передать в объекте customer или в параметре customerContact.
Чек покупателю доставляет ОФД (условия доставки зависят от вашего ОФД). Чеки приходят на мобильные номера российских операторов (они начинаются с +7). На иностранный мобильный номер чек может не дойти.

Параметр customerContact устарел. Его всё еще можно использовать, но рекомендуется передавать данные в объекте customer.

Количество товаров, вес, цена

В поле 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-ФЗ Отправка данных для чека