Чеки от ЮKassa: чеки при платежах — Прием платежей по API ЮKassa

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

При проведении платежа статус регистрации чека вернется в объекте платежа в параметре 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 and receipt_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 электронную почту пользователя. Отправка чека в смс недоступна.