Чеки при платежах
В этой статье описано, как проводить платежи с автоматической регистрацией чеков в сервисе Мой налог.
Как это работает
Для регистрации чека вам нужно подготовить данные о товарах или услугах и контактные данные пользователя — адрес электронной почты или номер телефона, куда ЮKassa отправит ссылку на зарегистрированный чек. Эти данные нужно передавать в объекте
receipt
в том же запросе, что и данные для платежа. Порядок действий зависит от того, как вы проводите платеж — в одну или в две стадии.
Платеж в одну стадию
Данные для чека необходимо передавать при создании платежа.
Платеж в две стадии
Данные для чека необходимо передавать при создании платежа.
При подтверждении платежа:
  • Если списываете полную сумму, данные для чека не нужны. При полном подтверждении ваш зарегистрированный доход не меняется, поэтому новый чек не нужен.
  • Если списываете только часть суммы, то в запросе на подтверждение платежа необходимо дополнительно передать данные для чека. ЮKassa аннулирует старый чек и зарегистрирует новый с теми данными, которые вы передадите в запросе.
  • Если отменяете платеж, данные для чека не нужны. ЮKassa аннулирует чек прихода, новый чек не нужен.
Если вы создали платеж до включения автоотправки чеков, а подтверждаете его или отменяете уже после включения опции, то откорректировать или аннулировать чек вам нужно самостоятельно. Управлять этими чеками по API не получится.
Чеки при создании платежа
Чтобы сформировать чек, создайте платеж  и передайте в запросе объект
receipt
с данными для чека: объект
customer
с электронной почтой пользователя или его номером телефона и массив
items
с данными о товарах или услугах (максимум 6 товаров).
Какие данные необходимо передать для каждого товара:
  • параметр
    description
    с названием товара или услуги;
  • параметр
    amount
    с суммой за единицу товара;
  • параметр
    quantity
    с указанием количества товара (только целые числа, например
    1
    );
  • параметр
    vat_code
    с фиксированным значением
    1
    (стоимость без НДС).
Другие данные передавать не нужно.
Пример запроса на оплату с параметрами для чека
cURL
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 в истории платежей. Если что-то пойдет не так, сформируйте чек вручную в сервисе Мой налог и самостоятельно пришлите пользователю ссылку на чек.
Пример тела ответа
JSON
{
    "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
PHP
Python
curl https://api.yookassa.ru/v3/payments/{payment_id}/capture \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json'
Частичное подтверждение платежа
Чтобы списать только часть суммы, в запросе на подтверждение платежа  вам необходимо передать объект
receipt
с данными для формирования нового чека. В чеке необходимо указать данные о тех товарах и услугах, которые пользователь в итоге приобрел.
Пример запроса для частичного подтверждения платежа
cURL
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
PHP
Python
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
    и просуммируйте получившиеся значения по всем товарам);
  • все суммы в чеке положительные.
Что почитать еще
Основы проведения платежейПолучение информации о платежеКоды ответа (состояния) HTTP