Чеки отражают статус взаиморасчетов между вами и пользователем и подтверждают, что пользователь внес оплату, а вы предоставили ему предмет расчета, например товар. Если оплата и выдача товара разнесены по времени, например при доставке товара курьером, вам нужно будет сформировать дополнительный чек при выдаче товара.
- Выберите сценарий отправки чека.
- Сформируйте чек прихода в запросе на создание платежа или отдельным запросом (зависит от выбранного сценария отправки чека).
- Если в чеке прихода были товары с предоплатой, при их выдаче сформируйте чек зачета предоплаты.
Если вы отправляете чеки по одному из сценариев: Платеж и чек одновременно или Сначала чек, потом платеж, данные для формирования чека необходимо передавать при создании платежа и при частичном подтверждении (в случае двухстадийной оплаты).
Чтобы сформировать чек, создайте платеж и передайте в запросе объект
receipt
с данными для онлайн-кассы.Пример запроса на оплату с параметрами для чека
curl https://api.yookassa.ru/v3/payments \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "value": "600.00", "currency": "RUB" }, "confirmation": { "type": "redirect", "return_url": "https://www.example.com/return_url" }, "receipt": { "customer": { "full_name": "Иванов Иван Иванович", "phone": "79000000000" }, "items": [ { "description": "Наименование товара 1", "quantity": "2.00", "amount": { "value": "250.00", "currency": "RUB" }, "vat_code": "2", "payment_mode": "full_prepayment", "payment_subject": "commodity" }, { "description": "Наименование товара 2", "quantity": "1.00", "amount": { "value": "100.00", "currency": "RUB" }, "vat_code": "2", "payment_mode": "full_prepayment", "payment_subject": "commodity" } ] } }'
В ответ вернется созданный объект платежа .
Если вы используете сценарий Платеж и чек одновременно, то вы можете узнать, сформировался ли чек, по значению параметра
receipt_registration
. Если что-то пойдет не так, сформируйте чек вручную в своей онлайн-кассе.Если вы используете сценарий Сначала чек, потом платеж, то платеж может вернуться в статусе
pending
и будет находиться в нём до тех пор, пока онлайн-касса не сообщит об успешной регистрации чека. Если за пять минут ответ не придет, ЮKassa отменит платеж (он перейдет в статус canceled
) и вернет деньги пользователю.Пример тела ответа
{ "id": "227cf565-000f-5000-8000-1c9d1c6000fb", "status": "succeeded", "paid": true, "amount": { "value": "600.00", "currency": "RUB" }, "authorization_details": { "rrn": "10000000000", "auth_code": "000000", "three_d_secure": { "applied": true } }, "captured_at": "2018-05-03T10:17:31.487Z", "created_at": "2018-05-03T10:17:09.337Z", "metadata": {}, "payment_method": { "type": "bank_card", "id": "227cf565-000f-5000-8000-1c9d1c6000fb", "saved": false, "card": { "first6": "411111", "last4": "1111", "expiry_month": "01", "expiry_year": "2020", "card_type": "Visa", "issuer_country": "RU", "issuer_name": "Sberbank" }, "title": "Bank card *1111" }, "receipt_registration": "pending", "recipient": { "account_id": "100500", "gateway_id": "100700" }, "refundable": true, "refunded_amount": { "value": "0.00", "currency": "RUB" } }
Если после оплаты пользователем платеж перейдет в статус
canceled
, ЮKassa автоматически передаст онлайн-кассе данные для формирования чека возврата.Если вы проводите платежи в две стадии, то при частичном подтверждении платежа будет формироваться два новых чека: один — для возврата предыдущего платежа, второй — для платежа с учетом скорректированных данных. Поэтому если вы хотите подтвердить платеж частично, в запросе на подтверждение вам необходимо передать объект
receipt
с данными для формирования нового чека.Пример запроса с частичным подтверждением
curl https://api.yookassa.ru/v3/payments/:id/capture \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "value": "500.00", "currency": "RUB" }, "receipt": { "customer": { "full_name": "Иванов Иван Иванович", "phone": "79000000000" }, "items": [ { "description": "Наименование товара 1", "quantity": "2.00", "amount": { "value": "250.00", "currency": "RUB" }, "vat_code": "2", "payment_mode": "full_prepayment", "payment_subject": "commodity" } ] } }'
Если вы подтверждаете всю сумму целиком, данные для чека передавать не нужно.
Если вы отправляете чеки по сценарию Сначала платеж, потом чек, данные для формирования чека прихода нужно передавать отдельным запросом.
Чек прихода необходимо формировать для платежа, который ожидает вашего подтверждения (объект платежа в статусе
waiting_for_capture
) или уже успешно завершен (объект платежа в статусе succeeded
). Для одного платежа можно создать не более 15 чеков.Чтобы сформировать чек прихода, отправьте ЮKassa запрос на создание чека . В запросе передайте идентификатор платежа (
payment_id
), для которого формируете чек, параметр type
со значением payment
и другие необходимые параметры.Пример запроса на создание чека отдельно от платежа
curl https://api.yookassa.ru/v3/receipts \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ "customer": { "full_name": "Иванов Иван Иванович", "email": "email@email.ru", "phone": "7100000000", "inn": "6321000014" }, "payment_id": "24b94598-000f-5000-9000-1b68e7b15f3f", "type": "payment", "send": "true", "items": [ { "description": "Наименование товара 1", "quantity": "2.00", "amount": { "value": "250.00", "currency": "RUB" }, "vat_code": "2", "payment_mode": "full_prepayment", "payment_subject": "commodity", "country_of_origin_code": "CN" }, { "description": "Наименование товара 2", "quantity": "1.00", "amount": { "value": "100.00", "currency": "RUB" }, "vat_code": "2", "payment_mode": "full_prepayment", "payment_subject": "commodity", "country_of_origin_code": "CN" } ], "settlements": [ { "type": "cashless", "amount": { "value": "600.00", "currency": "RUB" } } ] }'
В ответ ЮKassa отправит объект чека .
Пример тела ответа
{ "id": "rt_1da5c87d-0984-50e8-a7f3-8de646dd9ec9", "type": "payment", "payment_id": "24b94598-000f-5000-9000-1b68e7b15f3f", "status": "pending", "items": [ { "description": "Наименование товара 1", "quantity": 2.000, "amount": { "value": "250.00", "currency": "RUB" }, "vat_code": "2", "payment_mode": "full_prepayment", "payment_subject": "commodity", "country_of_origin_code": "CN" }, { "description": "Наименование товара 2", "quantity": 1.000, "amount": { "value": "100.00", "currency": "RUB" }, "vat_code": "2", "payment_mode": "full_prepayment", "payment_subject": "commodity", "country_of_origin_code": "CN" } ], "settlements": [ { "type": "cashless", "amount": { "value": "600.00", "currency": "RUB" } } ] }
Если вы принимаете оплату в две стадии, то после частичного подтверждения платежа нужно сформировать два новых чека: чек возврата прихода первоначального платежа (на полную сумму) и чек прихода с учетом скорректированных данных.
Если вы подтверждаете всю сумму целиком, нужно сформировать только один чек прихода, когда платеж перейдет в статус
waiting_for_capture
.Чек зачета предоплаты нужен только в случае, если вы принимали предоплату или аванс за товары. Способ и порядок формирования чека зачета предоплаты не зависит от выбранного сценария отправки чеков.
Чтобы сформировать чек зачета предоплаты, отправьте запрос на создание чека прихода (
type
со значением payment
). Все товары в этом чеке должны содержать признак способа расчета «Полный расчет». Укажите в объекте settlements
сумму всех совершенных расчетов. Например, если было несколько частичных предоплат, нужно передать общую сумму с типом расчета «Предоплата (аванс)».Пример запроса на создание чека
curl https://api.yookassa.ru/v3/receipts \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ "customer": { "full_name": "Иванов Иван Иванович", "email": "email@email.ru", "phone": "79211234567", "inn": "6321341814" }, "payment_id": "24b94598-000f-5000-9000-1b68e7b15f3f", "type": "payment", "send": "true", "items": [ { "description": "Наименование товара 1", "quantity": "2.00", "amount": { "value": "250.00", "currency": "RUB" }, "vat_code": "2", "payment_mode": "full_payment", "payment_subject": "commodity", "country_of_origin_code": "CN" }, { "description": "Наименование товара 2", "quantity": "1.00", "amount": { "value": "100.00", "currency": "RUB" }, "vat_code": "2", "payment_mode": "full_payment", "payment_subject": "commodity", "country_of_origin_code": "CN" } ], "settlements": [ { "type": "prepayment", "amount": { "value": "600.00", "currency": "RUB" } } ] }'
В ответ на запрос придет объект чека .
{ "id": "rt_1da5c87d-0984-50e8-a7f3-8de646dd9ec9", "type": "payment", "payment_id": "24b94598-000f-5000-9000-1b68e7b15f3f", "status": "pending", "items": [ { "description": "Наименование товара 1", "quantity": 2.000, "amount": { "value": "250.00", "currency": "RUB" }, "vat_code": "2", "payment_mode": "full_payment", "payment_subject": "commodity", "country_of_origin_code": "CN" }, { "description": "Наименование товара 2", "quantity": 1.000, "amount": { "value": "100.00", "currency": "RUB" }, "vat_code": "2", "payment_mode": "full_payment", "payment_subject": "commodity", "country_of_origin_code": "CN" } ], "settlements": [ { "type": "prepayment", "amount": { "value": "600.00", "currency": "RUB" } } ] }
Проверьте, что вы корректно передаете данные для чеков в объекте
receipt
:- данные переданы в соответствующем запросе (зависит от сценария отправки чеков);
- переданы все обязательные параметры;
- значения параметров переданы в нужном формате;
- в чеке не более 100 товаров;
- сумма платежа в
amount
совпадает с общей суммой чека вreceipt
(чтобы определить сумму чека, для каждого товара умножьтеquantity
наamount
и просуммируйте получившиеся значения по всем товарам); - все суммы в чеке положительные.
Если что-то будет не так, ЮKassa вернет ошибку.
Проверьте, что передаваемые данные соответствуют требованиям 54-ФЗ и ограничениям онлайн-касс:
- параметр
excise
только у товаров с признаком предмета расчета «Подакцизный товар»; - для товаров, продаваемых в кредит, создан отдельный чек: нельзя, чтобы в одном чеке были товары с признаком способа расчета «Кредит» и товары с другими признаками способа расчета;
- параметры
product_code
,country_of_origin_code
,customs_declaration_number
только у товаров с признаками предмета расчета «Товар», «Подакцизный товар», «Несколько вариантов», «Другое».
Если что-то будет не так, онлайн-касса не сформирует чек — информация об ошибке отобразится в истории платежей. Статус платежа будет зависеть от сценария отправки чеков: в сценарии Сначала чек, потом платеж ЮKassa отменит платеж и автоматически сформирует чек возврата прихода; в других сценариях платеж пройдет.
Основы проведения платежейПолучение информации о платежеКоды ответа (состояния) HTTPВыгрузка данных по чекам