Чеки при платежах
В этой статье описано, как сформировать чек прихода при проведении платежа и чек зачета предоплаты при выдаче товара (если в заказе были товары с предоплатой).
Как это работает
Для регистрации чека вам нужно подготовить данные о товарах или услугах и контактные данные пользователя — адрес электронной почты, куда ЮKassa отправит ссылку на зарегистрированный чек.
ЮKassa доставляет чек только на электронную почту. Отправка чека в смс недоступна.
Проведение платежа
При проведении платежа вы передаете данные для чека в объекте
receipt
в том же запросе, что и данные для платежа. Это нужно делать при проведении каждого платежа.Порядок действий зависит от того, как вы проводите платеж — в одну или в две стадии.
Платеж в одну стадию
Данные для чека необходимо передавать при создании платежа.
Проведение платежа в одну стадию
Платеж в две стадии
Данные для чека необходимо передавать при создании платежа.
Создание платежа в две стадии
При подтверждении платежа:
- Если списываете полную сумму, данные для чека не нужны. При полном подтверждении состав заказа не меняется, поэтому новый чек не нужен.
- Если списываете только часть суммы, то в запросе на подтверждение платежа необходимо дополнительно передать данные для чека. ЮKassa сформирует два чека: чек возврата предыдущего заказа и новый чек прихода. Для чека возврата ЮKassa использует те данные, которые вы передали в запросе на создание платежа, а для нового чека прихода — те данные, которые вы передадите в запросе на подтверждение платежа.
- Если отменяете платеж, данные для чека не нужны. ЮKassa создаст чек возврата на основе тех данных, которые вы передали в запросе на создание платежа.
Full payment capture
Partial payment capture
Payment cancelation
Полное подтверждение платежа
Чек зачета предоплаты
Если в чеке прихода были товары с предоплатой, при их выдаче вы формируете чек зачета предоплаты. Данные для этого чека необходимо передать отдельным запросом на создание чека. Подробнее о чеке зачета предоплаты
Создание чека зачета предоплаты
Статус регистрации чека
При проведении платежа статус регистрации чека вернется в объекте платежа в параметре
receipt_registration
, при создании чека зачета предоплаты — в объекте чека в параметре status
. Также статус отображается в личном кабинете ЮKassa в истории платежей.Если чек зарегистрировать не удалось (статус чека
canceled
) или если в течение трех дней с момента создания платежа чек не сформируется (чек останется в статусе pending
), обратитесь в техническую поддержку ЮKassa.Чеки при создании платежа
Чтобы провести платеж вместе с отправкой чека, создайте платеж : отправьте ЮKassa запрос с данными для аутентификации, ключом идемпотентности, с данными о платеже (сумма платежа, данные для выбранного сценария интеграции и другие параметры) и с данными для чека в объекте
receipt
:customer
object with the user's email and other user information, if necessary;items
array with information about products or services;- if necessary,
receipt_industry_details
parameters with industry attribute of the receipt andreceipt_operational_details
with transactional receipt details.
Пример запроса на оплату с параметрами для чека
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments \ -X POST \ -u <Shop ID>:<Secret Key> \ -H 'Idempotence-Key: <Idempotence Key>' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "value": "1250.00", "currency": "RUB" }, "confirmation": { "type": "redirect", "return_url": "https://www.example.com/return_url" }, "capture": true, "description": "Order No. 37", "metadata": { "order_id": "37" }, "receipt": { "customer": { "email": "user@example.com" }, "items": [ { "description": "Tailoring service", "quantity": 1.000, "amount": { "value": "250.00", "currency": "RUB" }, "vat_code": 1, "payment_mode": "full_prepayment", "payment_subject": "commodity" }, { "description": "Knitted top", "quantity": 2.000, "amount": { "value": "500.00", "currency": "RUB" }, "vat_code": 4, "payment_mode": "full_prepayment", "payment_subject": "marked", "mark_mode": 0, "mark_code_info": { "gs_1m": "DFGwNDY0MDE1Mzg2NDQ5MjIxNW9vY2tOelDFuUFwJh05MUVFMDYdOTJXK2ZaMy9uTjMvcVdHYzBjSVR3NFNOMWg1U2ZLV0dRMWhHL0UrZi8ydkDvPQ==" }, "measure": "piece" } ] } }'
В ответ вернется созданный объект платежа . Актуальный статус регистрации чека прихода можно узнать по значению параметра
receipt_registration
.Пример тела ответа
JSON
{ "id": "28646d50-000f-5000-a000-1fe4f81e5e88", "status": "succeeded", "paid": true, "amount": { "value": "1250.00", "currency": "RUB" }, "authorization_details": { "rrn": "10000000000", "auth_code": "000000", "three_d_secure": { "applied": true } }, "captured_at": "2023-05-22T21:44:55.506Z", "created_at": "2022-05-22T21:43:44.794Z", "description": "Order No. 37", "income_amount": { "value": "1205.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": "Mir", "card_product": { "code": "MCP", "name": "MIR Privilege" }, "issuer_country": "RU" }, "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
PHP
Python
curl https://api.yookassa.ru/v3/payments/{payment_id}/capture \ -X POST \ -u <Shop ID>:<Secret Key> \ -H 'Idempotence-Key: <Idempotence Key>' \ -H 'Content-Type: application/json'
В ответ вернется объект платежа в актуальном статусе.
Частичное подтверждение платежа
Чтобы списать только часть суммы, в запросе на подтверждение платежа вам необходимо передать объект
receipt
с данными для формирования нового чека. В чеке необходимо указать данные о тех товарах и услугах, которые пользователь в итоге приобрел.Пример запроса для частичного подтверждения платежа
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments/:id/capture \ -X POST \ -u <Shop ID>:<Secret Key> \ -H 'Idempotence-Key: <Idempotence Key>' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "value": "500.00", "currency": "RUB" }, "receipt": { "customer": { "email": "user@example.com" }, "items": [ { "description": "Knitted top", "quantity": 1.000, "amount": { "value": "500.00", "currency": "RUB" }, "vat_code": 4, "payment_mode": "full_prepayment", "payment_subject": "marked", "mark_mode": 0, "mark_code_info": { "gs_1m": "DFGwNDY0MDE1Mzg2NDQ5MjIxNW9vY2tOelDFuUFwJh05MUVFMDYdOTJXK2ZaMy9uTjMvcVdHYzBjSVR3NFNOMWg1U2ZLV0dRMWhHL0UrZi8ydkDvPQ==" }, "measure": "piece" } ] } }'
ЮKassa создаст чек возврата на основе тех данных, которые вы передали при создании платежа, и зарегистрирует новый чек прихода с теми данными, которые вы указали в запросе на подтверждение платежа.
В ответ вернется объект платежа в актуальном статусе. Актуальный статус регистрации чека прихода можно узнать по значению параметра
receipt_registration
.Отмена платежа
Если вы отменяете платеж, данные для чека передавать не нужно. Отправьте стандартный запрос на отмену платежа .
Пример запроса на отмену платежа
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments/{payment_id}/cancel \ -X POST \ -u <Shop ID>:<Secret Key> \ -H 'Idempotence-Key: <Idempotence Key>' \ -H 'Content-Type: application/json' \ -d '{ }'
При отмене платежа ЮKassa автоматически сформирует чек возврата на основе тех данных, которые вы передали в запросе на создание платежа.
В ответ вернется объект платежа в актуальном статусе. Актуальный статус регистрации чека возврата прихода можно узнать по значению параметра
receipt_registration
.Чек зачета предоплаты
Чек зачета предоплаты нужен только в случае, если вы принимали предоплату или аванс за товары.
Чтобы сформировать чек зачета предоплаты, создайте чек : отправьте ЮKassa запрос с данными для аутентификации, ключом идемпотентности и данными для чека:
- параметр
type
со значениемpayment
(чек прихода); - параметр
payment_id
с идентификатором платежа, для которого создаете чек зачета предоплаты; - объект
customer
с электронной почтой пользователя и при необходимости другими данными о пользователе; - массив
items
с данными о товарах или услугах; все товары должны содержать содержать признак способа расчета «Полный расчет»; - параметр
send
со значениемtrue
; - массив
settlements
с суммой всех совершенных расчетов; например, если было несколько частичных предоплат, нужно передать общую сумму с типом расчета «Предоплата (аванс)»; - при необходимости параметры
receipt_industry_details
с отраслевым реквизитом чека иreceipt_operational_details
с операционным реквизитом чека.
Пример запроса на создание чека
cURL
PHP
Python
curl https://api.yookassa.ru/v3/receipts \ -X POST \ -u <Shop ID>:<Secret Key> \ -H 'Idempotence-Key: <Idempotence Key>' \ -H 'Content-Type: application/json' \ -d '{ "customer": { "email": "user@example.com" }, "payment_id": "28646d50-000f-5000-a000-1fe4f81e5e88", "type": "payment", "send": "true", "items": [ { "description": "Tailoring service", "quantity": 1.000, "amount": { "value": "250.00", "currency": "RUB" }, "vat_code": 1, "payment_mode": "full_payment", "payment_subject": "commodity" }, { "description": "Knitted top", "quantity": 2.000, "amount": { "value": "500.00", "currency": "RUB" }, "vat_code": 4, "payment_mode": "full_payment", "payment_subject": "marked", "mark_mode": 0, "mark_code_info": { "gs_1m": "DFGwNDY0MDE1Mzg2NDQ5MjIxNW9vY2tOelDFuUFwJh05MUVFMDYdOTJXK2ZaMy9uTjMvcVdHYzBjSVR3NFNOMWg1U2ZLV0dRMWhHL0UrZi8ydkDvPQ==" }, "measure": "piece" } ], "settlements": [ { "type": "prepayment", "amount": { "value": "1250.00", "currency": "RUB" } } ] }'
В ответ на запрос придет объект чека .
JSON
{ "id": "rt-2bf4503f-0001-0050-0e94-761f7451b8a6", "type": "payment", "payment_id": "28646d50-000f-5000-a000-1fe4f81e5e88", "status": "pending", "items": [ { "description": "Tailoring service", "quantity": 1.000, "amount": { "value": "250.00", "currency": "RUB" }, "vat_code": 1, "payment_subject": "service", "payment_mode": "full_payment", "payment_subject_industry_details": [] }, { "description": "Knitted top (milk) (S)", "quantity": 2.000, "amount": { "value": "500.00", "currency": "RUB" }, "vat_code": 4, "payment_subject": "marked", "payment_mode": "full_payment", "mark_code_info": { "gs_1m": "DFGwNDY0MDE1Mzg2NDQ5MjIxNW9vY2tOelDFuUFwJh05MUVFMDYdOTJXK2ZaMy9uTjMvcVdHYzBjSVR3NFNOMWg1U2ZLV0dRMWhHL0UrZi8ydkDvPQ==" }, "measure": "piece", "payment_subject_industry_details": [], "mark_mode": "0" } ], "settlements": [ { "type": "cashless", "amount": { "value": "1250.00", "currency": "RUB" } } ], "receipt_industry_details": [] }
Памятка по подготовке данных для чеков
Проверьте, что вы корректно передаете данные для чеков в объекте
receipt
:- переданы все обязательные параметры;
- во всех параметрах непустые значения;
- значения параметров переданы в нужном формате;
- в чеке не более 100 товаров;
- сумма платежа в
amount
совпадает с общей суммой чека вreceipt
(чтобы определить сумму чека, для каждого товара умножьтеquantity
наamount
и просуммируйте получившиеся значения по всем товарам); - все суммы в чеке положительные;
- в данных для чека нет подакцизных товаров;
- в данных для чека нет товаров с частичной предоплатой, авансом или кредитом.
Если что-то будет не так, ЮKassa вернет ошибку.
Проверьте, что вы передали в объекте
customer
электронную почту пользователя. Отправка чека в смс недоступна.See also