Объекты API v1.1.0

Кошелёк Pay API

Документация перемещена

Информация на этой странице не обновляется и может быть устаревшей. Наиболее полная и актуальная версия документации для разработчиков доступна по новому адресу:

https://developers.koshelek.app

1. Объект CheckoutInvoice

Объект содержит данные о пречеке.

Поле	Тип	Обязательно	Значение
orderId	String	Да	Номер пречека (идентификатор покупки в системе ТСП). До 36 символов.
totalAmount	Number	Да	Сумма к оплате (итоговая сумма) с учетом скидки в копейках. Неотрицательное целое число, не более 10 цифр. Недопустимые символы: пробел.
currency	Enum	Нет	Трехбуквенный код валюты в формате ISO-4217: RUB — значение по умолчанию, если параметр отсутствует или значение пустое. Если значение отлично от RUB, кассовое ПО получит отказ с сообщением о доступности только RUB.
discountAmount	Number	Нет	Сумма скидки в копейках. Неотрицательное целое число, не более 10 цифр. Недопустимые символы: пробел.
subTotalAmount	Number	Нет	Полная сумма без учета скидки в копейках (включая НДС). Неотрицательное целое число, не более 10 цифр. Недопустимые символы: пробел.
items	Array of Item	Да	Массив товаров, включенных в покупку (каждый товар — объект Item).

2. Объект Item

Объект описывает отдельное товарное наименование, оплаченное с помощью Кошелёк Pay.

Поле	Тип	Обязательно	Значение
name	String	Да	Наименование товара.
article	String	Да	Артикул.
price	Number	Да	Цена за единицу товара в копейках.
currency	String	Нет	Трехбуквенный код валюты в формате ISO-4217: RUB — значение по умолчанию, если параметр отсутствует или значение пустое. Если значение отлично от RUB, кассовое ПО получит отказ с сообщением о доступности только RUB.
quantity	Number	Да	Количество товара: число с плавающей точкой и 1 знак после разделителя; дробные значения запрещены. ✅ Допустимо: measure = GRAM quantity = 1125.0 ИЛИ quantity = 1125 ❌Недопустимо: measure = KILOGRAM quantity = 1.125
measure	Enum	Нет	Единица измерения: PIECE — штука, единица товара (значение по умолчанию, если параметр отсутствует или значение пустое). GRAM — грамм. KILOGRAM — килограмм. TON — тонна. CENTIMETER — сантиметр. DECIMETER — дециметр. METER — метр. SQUARE_CENTIMETER — квадратный сантиметр. SQUARE_DECIMETER — квадратный дециметр. SQUARE_METER — квадратный метр. MILLILITER — миллилитр. LITER — литр. CUBIC_METER — кубический метр. KILOWATT_HOUR — киловатт-час. GIGACALORIE — гигакалория. DAY — сутки. HOUR — час. MINUTE — минута. SECOND — секунда. KILOBYTE — килобайт. MEGABYTE — мегабайт. GIGABYTE — гигабайт. TERABYTE — терабайт. OTHER — другая единица измерения.
totalAmount	Number	Да	Сумма к оплате (итоговая) в копейках. Недопустимые символы: пробел.
discountAmount	Number	Нет	Сумма скидки в копейках. Недопустимые символы: пробел.
subTotalAmount	Number	Нет	Полная сумма без учета скидки в копейках. Недопустимые символы: пробел.
tax	Enum	Да	Ставка налога: none — без НДС. vat0 —НДС по ставке 0%. vat10 — НДС чека по ставке 10%. vat20 — НДС чека по ставке 20%. vat110 — НДС чека по расчетной ставке 10/110. vat120 — НДС чека по расчетной ставке 20/120.

3. Объект User

Объект содержит данные о пользователе (клиенте, совершающем покупку).

Поле	Тип	Обязательно	Значение
loyaltyId	String	Да	Идентификатор клиента в программе лояльности (ключ карты лояльности). До 36 символов.

4. Объект PaymentTypeAvailabilityInfo

Объект содержит сведения о провайдере платежей.

Поле	Тип	Обязательно	Значение
paymentType	String	Да	Наименование провайдера платежей (до 36 символов).
available	Boolean	Да	Доступность провайдера платежей: true - доступен. false - недоступен.
message	String	Нет	Дополнительная информация о провайдере.

5. Объект Slip

Объект содержит данные о проведенной банковской операции.

Поле	Тип	Обязательно	Значение
id	String	Да	Внутренний идентификатор объекта Slip в системе Кошелька.
paymentType	Enum	Да	Механизм оплаты: SBP — СБП. DOLYAME — Долями.
storeId	String	Да	Идентификатор торговой точки (см. Подключение к API).
terminalId	String	Да	Идентификатор кассы.
orderId	String	Да	Номер пречека (идентификатор покупки в системе ТСП).
paymentTransactionId	String	Да	Идентификатор транзакции (покупки в системе Кошелька).
refundTransactionId	String	Нет	Идентификатор транзакции возврата.
merchantId	String	Да (для paymentType = SBP)	Идентификатор ТСП, выданный банком-получателем. Обязателен для оплаты через СБП.
kzo	String	Нет	Контрольное значение операции СБП. Передается только для успешных операций, выполненных через СБП.
operationDateTime	Date	Да	Дата транзакции в формате: yyyy-MM-dd'T'HH:mm:ss.SSSZ Часовой пояс всегда равен Z (+0).
operationId	String	Нет	Уникальный идентификатор транзакции возврата, присвоенный провайдером платежей (используйте значение trxId от провайдера СБП или refundId от Долями).
qrcId	String	Да (для paymentType = SBP)	Идентификатор транзакции, зарегистрированный в СБП. Обязателен для оплаты через СБП.
totalAmount	Number	Да	Оплаченная сумма (в копейках). Недопустимые символы: пробел.
currency	Enum	Да	Трехбуквенный код валюты в формате ISO-4217: RUB — значение по умолчанию, если параметр отсутствует или значение пустое. Если значение отлично от RUB, кассовое ПО получит отказ с сообщением о доступности только RUB.

6. Объект PaymentMethod

Объект описывает используемый способ оплаты.

Поле	Тип	Обязательно	Значение
type	Enum	Да	Механизм оплаты: SBP — СБП. DOLYAME — Долями.
meta	Object	Нет	Объект, содержащий дополнительные поля, например: скидки, бонусы и т.д. (набор пар "ключ-значение").
paymentPurpose	String	Нет	Назначение платежа. Может быть передано для type = SBP. Если передано, будет использовано при передаче в СБП в приоритетном порядке, даже если при подключении ТСП по умолчанию было установлено иное значение.

7. Объект Invoice

Объект содержит сведения о фискальном чеке.

Поле	Тип	Обязательно	Значение
orderId	String	Да	Номер пречека (до 36 символов).
receiptId	String	Да	Номер чека (до 36 символов).
merchantName	String	Да	Полное наименование ТСП (до 999 символов).
merchantAddress	String	Да	Адрес ТСП (до 999 символов)
inn	String	Да	ИНН ТСП (ровно 12 цифр; для ЮЛ - 2 первых нуля)..
dateTime	Datetime	Да	Формат даты: YYYY-MM-DDTHH24:MI:SS+GMT
shift	String	Да	Смена (до 32 символов).
cashier	String	Да	ФИО или номер кассира (до 256 символв).
taxation	Enum	Нет	Система налогообложения. Перечисление с возможными значениями: osn – общая СН; usn_income – упрощенная СН (доходы); usn_income_outcome – упрощенная СН (доходы минус расходы); envd – единый налог на вмененный доход; esn – единый сельскохозяйственный налог; patent – патентная СН.
kktRegNumber	String	Нет	Регистрационный номер ККТ (до 64 символов).
fnNumber	String	Нет	Номер фискального накопителя (до 64 символов).
fpd	String	Нет	Фискальный признак документа (до 64 символов).
fdNumber	String	Нет	Номер фискального документа (до 64 символов).
website	String	Нет	Сайт для проверки данных чека (например, nalog.ru), (до 64 символов).
receiptType	Enum	Да	Признак расчета. Перечисление с возможными значениями: debit - приход; credit - расход; refund - возврат.
totalAmount	Number	Да	Сумма к оплате (итоговая сумма) в копейках, неотрицательное целое число, до 10 цифр. Недопустимые символы: пробел.
currency	String	Нет	Трехбуквенный код валюты в формате ISO-4217: RUB — значение по умолчанию, если параметр отсутствует или значение пустое. Если значение отлично от RUB, кассовое ПО получит отказ с сообщением о доступности только RUB.
discountAmount	Number	Нет	Сумма скидки в копейках, неотрицательное целое число, до 10 цифр. Недопустимые символы: пробел.
subTotalAmount	Number	Нет	Полная сумма без учета скидки в копейках, неотрицательное целое число, до 10 цифр. Недопустимые символы: пробел.
taxAmount	Number	Да	Сумма налога в копейках, неотрицательное целое число, до 10 цифр. Недопустимые символы: пробел.
qr	String	Нет	QR-код для загрузки электронной версии чека (до 999 символов).
items	Array of Item	Да	Массив товаров, включенных в покупку (каждый товар - объект Item).