Инструкции
Помощь
Подключить ЮKassa
Чеки при платежах
В этой статье описано, как проводить платежи с автоматической регистрацией чеков в сервисе Мой налог.
Как это работает
Для регистрации чека вам нужно подготовить данные о товарах или услугах и контактные данные пользователя — адрес электронной почты или номер телефона, куда ЮKassa отправит ссылку на зарегистрированный чек. Эти данные нужно передавать в объекте receipt в том же запросе, что и данные для платежа. Порядок действий зависит от того, как вы проводите платеж — в одну или в две стадии.
Платеж в одну стадию
Данные для чека необходимо передавать при создании платежа.
Платеж в две стадии
Данные для чека необходимо передавать при создании платежа.
При подтверждении платежа:
  • Если списываете полную сумму, данные для чека не нужны. При полном подтверждении ваш зарегистрированный доход не меняется, поэтому новый чек не нужен.
  • Если списываете только часть суммы, то в запросе на подтверждение платежа необходимо дополнительно передать данные для чека. ЮKassa аннулирует старый чек и зарегистрирует новый с теми данными, которые вы передадите в запросе.
  • Если отменяете платеж, данные для чека не нужны. ЮKassa аннулирует чек прихода, новый чек не нужен.
Чеки при создании платежа
Чтобы сформировать чек, создайте платеж  и передайте в запросе объект 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 и просуммируйте получившиеся значения по всем товарам);
  • все суммы в чеке положительные.
Если что-то будет не так, ЮKassa вернет ошибку.
Что почитать еще
Основы проведения платежейПолучение информации о платежеКоды ответа (состояния) HTTP