В этой статье описано, как проводить платежи с автоматической регистрацией чеков в сервисе Мой налог.
Для регистрации чека вам нужно подготовить данные о товарах или услугах и контактные данные пользователя — адрес электронной почты или номер телефона, куда ЮKassa отправит ссылку на зарегистрированный чек.
Эти данные нужно передавать в объекте
receipt
в том же запросе, что и данные для платежа.
Порядок действий зависит от того, как вы проводите платеж — в одну или в две стадии.Данные для чека необходимо передавать при создании платежа.
Данные для чека необходимо передавать при создании платежа.
При подтверждении платежа:
- Если списываете полную сумму, данные для чека не нужны. При полном подтверждении ваш зарегистрированный доход не меняется, поэтому новый чек не нужен.
- Если списываете только часть суммы, то в запросе на подтверждение платежа необходимо дополнительно передать данные для чека. ЮKassa аннулирует старый чек и зарегистрирует новый с теми данными, которые вы передадите в запросе.
- Если отменяете платеж, данные для чека не нужны. ЮKassa аннулирует чек прихода, новый чек не нужен.
Чтобы сформировать чек, создайте платеж и передайте в запросе объект
receipt
с данными для чека: объект customer
с электронной почтой пользователя или его номером телефона и массив items
с данными о товарах или услугах (максимум 6 товаров).Какие данные необходимо передать для каждого товара:
- параметр
description
с названием товара или услуги; - параметр
amount
с суммой за единицу товара; - параметр
quantity
с указанием количества товара (только целые числа, например1
); - параметр
vat_code
с фиксированным значением1
(стоимость без НДС).
Другие данные передавать не нужно.
Пример запроса на оплату с параметрами для чека
curl https://api.yookassa.ru/v3/payments \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "value": "1000.00", "currency": "RUB" }, "capture": true, "confirmation": { "type": "redirect", "return_url": "https://www.example.com/return_url" }, "description": "Заказ №37", "metadata": { "order_id": "37" }, "receipt": { "customer": { "email": "user@example.com" }, "items": [ { "description": "Ложка", "quantity": "10", "amount": { "value": "50.00", "currency": "RUB" }, "vat_code": "1" }, { "description": "Чашка чайная", "quantity": "2", "amount": { "value": "150.00", "currency": "RUB" }, "vat_code": "1" }, { "description": "Блюдце", "quantity": "2", "amount": { "value": "100.00", "currency": "RUB" }, "vat_code": "1" } ] } }'
В ответ вернется созданный объект платежа .
Вы можете узнать, сформировался ли чек, по значению параметра
receipt_registration
в объекте платежа .
Также статус регистрации чека отображается в личном кабинете ЮKassa в истории платежей.
Если что-то пойдет не так, сформируйте чек вручную в сервисе Мой налог и самостоятельно пришлите пользователю ссылку на чек.Пример тела ответа
{ "id": "28646d50-000f-5000-a000-1fe4f81e5e88", "status": "succeeded", "paid": true, "amount": { "value": "1000.00", "currency": "RUB" }, "authorization_details": { "rrn": "10000000000", "auth_code": "000000", "three_d_secure": { "applied": true } }, "captured_at": "2022-08-22T21:44:55.506Z", "created_at": "2022-08-22T21:43:44.794Z", "description": "Заказ №37", "income_amount": { "value": "964.00", "currency": "RUB" }, "metadata": { "order_id": "37" }, "payment_method": { "type": "bank_card", "id": "28646d50-000f-5000-a000-1fe4f81e5e88", "saved": false, "card": { "first6": "555555", "last4": "4477", "expiry_month": "01", "expiry_year": "2030", "card_type": "MasterCard", "issuer_country": "US" }, "title": "Bank card *4477" }, "receipt_registration": "succeeded", "recipient": { "account_id": "100500", "gateway_id": "100700" }, "refundable": true, "refunded_amount": { "value": "0.00", "currency": "RUB" }, "test": false }
Если после оплаты пользователем платеж перейдет в статус
canceled
, ЮKassa автоматически аннулирует чек в сервисе Мой налог.Если вы подтверждаете платеж полностью, ваш зарегистрированный доход не меняется.
Для списания всей суммы целиком отправьте стандартный запрос на подтверждение платежа .
Объект
receipt
не передавайте.Пример запроса для полного подтверждения платежа
curl https://api.yookassa.ru/v3/payments/{payment_id}/capture \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json'
Чтобы списать только часть суммы, в запросе на подтверждение платежа вам необходимо передать объект
receipt
с данными для формирования нового чека.
В чеке необходимо указать данные о тех товарах и услугах, которые пользователь в итоге приобрел.Пример запроса для частичного подтверждения платежа
curl https://api.yookassa.ru/v3/payments/:id/capture \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "value": "250.00", "currency": "RUB" }, "receipt": { "customer": { "email": "user@example.com" }, "items": [ { "description": "Чашка чайная", "quantity": "1", "amount": { "value": "150.00", "currency": "RUB" }, "vat_code": "1" }, { "description": "Блюдце", "quantity": "1", "amount": { "value": "100.00", "currency": "RUB" }, "vat_code": "1" } ] } }'
ЮKassa аннулирует старый чек, сформированный при создании платежа, и зарегистрирует новый чек с теми данными, которые вы указали в запросе на подтверждение платежа.
Если вы отменяете платеж, данные для чека передавать не нужно. Отправьте стандартный запрос на отмену платежа .
Пример запроса на отмену платежа
curl https://api.yookassa.ru/v3/payments/{payment_id}/cancel \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ }'
При отмене платежа ЮKassa автоматически аннулирует чек прихода.
Проверьте, что вы корректно передаете данные для чеков в объекте
receipt
:- объект
receipt
есть только в запросах на создание платежа и в запросах на частичное подтверждение платежа; - указаны электронная почта или номер телефона пользователя (данные переданы в объекте
customer
); - в
items
не более 6 товаров; - для каждого товара в
items
указаны только эти параметры —description
,amount
,quantity
,vat_code
; других параметров нет; quantity
— только целые числа (без точки и дробной части);vat_code
везде1
;- сумма платежа в
amount
совпадает с общей суммой чека вreceipt
(чтобы определить сумму чека, для каждого товара умножьтеquantity
наamount
и просуммируйте получившиеся значения по всем товарам); - все суммы в чеке положительные.
Если что-то будет не так, ЮKassa вернет ошибку.
Основы проведения платежейПолучение информации о платежеКоды ответа (состояния) HTTP