Чеки при платежах

В этой статье описано, как сформировать чек прихода при проведении платежа и чек зачета предоплаты при выдаче товара (если в заказе были товары с предоплатой).

Как это работает

Для регистрации чека вам нужно подготовить данные о товарах или услугах и контактные данные пользователя — адрес электронной почты, куда ЮKassa отправит ссылку на зарегистрированный чек.

ЮKassa доставляет чек только на электронную почту. Отправка чека в смс недоступна.

Проведение платежа

При проведении платежа вы передаете данные для чека в объекте receipt в том же запросе, что и данные для платежа. Это нужно делать при проведении каждого платежа.

Порядок действий зависит от того, как вы проводите платеж — в одну или в две стадии.

Платеж в одну стадию

Данные для чека необходимо передавать при создании платежа.

Проведение платежа в одну стадию

Платеж в две стадии

Данные для чека необходимо передавать при создании платежа.

Создание платежа в две стадии

При подтверждении платежа:

Если списываете полную сумму, данные для чека не нужны. При полном подтверждении состав заказа не меняется, поэтому новый чек не нужен.
Если списываете только часть суммы, то в запросе на подтверждение платежа необходимо дополнительно передать данные для чека. ЮKassa сформирует два чека: чек возврата предыдущего заказа и новый чек прихода. Для чека возврата ЮKassa использует те данные, которые вы передали в запросе на создание платежа, а для нового чека прихода — те данные, которые вы передадите в запросе на подтверждение платежа.
Если отменяете платеж, данные для чека не нужны. ЮKassa создаст чек возврата на основе тех данных, которые вы передали в запросе на создание платежа.

Полное подтверждение платежа

Чек зачета предоплаты

Если в чеке прихода были товары с предоплатой, при их выдаче вы формируете чек зачета предоплаты. Данные для этого чека необходимо передать отдельным запросом на создание чека. Подробнее о чеке зачета предоплаты

Создание чека зачета предоплаты

Статус регистрации чека

При проведении платежа статус регистрации чека вернется в объекте платежа в параметре receipt_registration, при создании чека зачета предоплаты — в объекте чека в параметре status. Также статус отображается в личном кабинете ЮKassa в истории платежей.

Если чек зарегистрировать не удалось (статус чека canceled) или если в течение трех дней с момента создания платежа чек не сформируется (чек останется в статусе pending), обратитесь в техническую поддержку ЮKassa.

Чеки при создании платежа

Чтобы провести платеж вместе с отправкой чека, создайте платеж: отправьте ЮKassa запрос с данными для аутентификации, ключом идемпотентности, с данными о платеже (сумма платежа, данные для выбранного сценария интеграции и другие параметры) и с данными для чека в объекте receipt:

объект customer с электронной почтой пользователя и при необходимости другими данными о пользователе;
массив items с данными о товарах или услугах;
при необходимости параметры receipt_industry_details с отраслевым реквизитом чека и receipt_operational_details с операционным реквизитом чека.

Пример запроса на оплату с параметрами для чека

cURL

PHP

Python

curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H '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": "Заказ №37",
        "metadata": {
            "order_id": "37"
        },
        "receipt": {
          "customer": {
            "email": "user@example.com"
          },
          "items": [
            {
              "description": "Пошив одежды по размеру",
              "quantity": 1.000,
              "amount": {
                "value": "250.00",
                "currency": "RUB"
              },
              "vat_code": 1,
              "payment_mode": "full_prepayment",
              "payment_subject": "commodity"
            },
            {
              "description": "Топ трикотажный",
              "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": "603668680243",
        "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": "Заказ №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 <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json'

В ответ вернется объект платежа в актуальном статусе.

Частичное подтверждение платежа

Чтобы списать только часть суммы, в запросе на подтверждение платежа вам необходимо передать объект receipt с данными для формирования нового чека. В чеке необходимо указать данные о тех товарах и услугах, которые пользователь в итоге приобрел.

Пример запроса для частичного подтверждения платежа

cURL

PHP

Python

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": {
            "email": "user@example.com"
          },
          "items": [
            {
              "description": "Топ трикотажный",
              "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 <Идентификатор магазина>:<Секретный ключ> \
  -H '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 <Идентификатор магазина>:<Секретный ключ> \
  -H '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": "Пошив одежды по размеру",
            "quantity": 1.000,
            "amount": {
              "value": "250.00",
              "currency": "RUB"
            },
            "vat_code": 1,
            "payment_mode": "full_payment",
            "payment_subject": "commodity"
          },
          {
            "description": "Топ трикотажный",
            "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": "Пошив одежды по размеру",
            "quantity": 1.000,
            "amount": {
                "value": "250.00",
                "currency": "RUB"
            },
            "vat_code": 1,
            "payment_subject": "service",
            "payment_mode": "full_payment",
            "payment_subject_industry_details": []
        },
        {
            "description": "Топ из вязаного трикотажа (Молочный) (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:

переданы все обязательные параметры;
во всех параметрах непустые значения;
значения параметров переданы в нужном формате;
в чеке не более 80 товаров;
сумма платежа в amount совпадает с общей суммой чека в receipt (чтобы определить сумму чека, для каждого товара умножьте quantity на amount и просуммируйте получившиеся значения по всем товарам);
все суммы в чеке положительные;
в данных для чека нет подакцизных товаров;
в данных для чека нет товаров с частичной предоплатой, авансом или кредитом.

Если что-то будет не так, ЮKassa вернет ошибку.

Проверьте, что вы передали в объекте customer электронную почту пользователя. Отправка чека в смс недоступна.

Что почитать еще

Основы проведения платежей

Получение информации о платеже

Коды ответа (состояния) HTTP

Выгрузка данных по чекам