Оплата жилищно-коммунальных услуг

С помощью ЮKassa вы можете принимать платежи за жилищно-коммунальные услуги (ЖКУ), например платежи за содержание жилого помещения, холодную и горячую воду, взносы на капитальный ремонт и т.д. При оплате ЖКУ необходимо передавать сведения о платеже в Государственную информационную систему жилищно-коммунального хозяйства (ГИС ЖКХ).

В этой статье описано, как принимать платежи за ЖКУ через ЮKassa.

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

В каждом запросе на создание платежа вы передаете объект payment_order с данными платежного поручения. Это сведения о платеже, которые нужны для формирования распоряжения на перевод денег поставщику ЖКУ и регистрации сведений о платеже в ГИС ЖКХ. Когда ЮKassa получит оплату от пользователя, она отправит платежное поручение в ГИС ЖКХ и дождется его обработки.

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

Есть особенности:

Данные платежного поручения (payment_order) нужны только в запросе на создание платежа, остальные запросы стандартные.
Платеж можно проводить только в одну стадию (параметр capture со значением true).
Если отправляете данные для чеков через ЮKassa, подойдут только эти решения:
- Чеки от ЮKassa
- Сторонняя онлайн-касса, сценарий Платеж и чек одновременно
- Сторонняя онлайн-касса, сценарий Сначала платеж, потом чек

Объект payment_order нужно передавать в каждом запросе на создание платежа. Если этого не сделать, ЮKassa вернет ошибку. Если хотите принимать не только платежи за ЖКУ, но и обычные платежи, где не нужно передавать данные платежного поручения, сообщите об этом вашему менеджеру ЮKassa. Вам настроят магазин для приема разных видов платежей.

Особенности регистрации сведений в ГИС ЖКХ

ЮKassa отправляет платежное поручение в ГИС ЖКХ после успешного завершения платежа (объект платежа в статусе succeeded). Срок обработки платежного поручения зависит от ГИС ЖКХ. В среднем эта операция занимает от нескольких минут до одних суток.

Регистрация платежного поручения никак не влияет на проведение платежа. Как только платеж перешел в статус succeeded, вы можете сообщить пользователю, что оплата принята. Статус платежа больше не изменится.

Общий сценарий и схема проведения платежа

В этом разделе описан общий сценарий проведения платежа на примере Умного платежа. Если вы используете другие сценарии интеграции, последовательность действий может незначительно отличаться.

Общая схема проведения платежа (на примере Умного платежа)

Как проходит платеж:

Пользователь переходит к оплате.
Вы создаете платеж — отправляете ЮKassa POST-запрос с данными для формирования платежного поручения в объекте payment_order.
ЮKassa возвращает вам созданный объект платежа в статусе pending и со ссылкой на платежную форму (параметр confirmation_url в объекте платежа).
Вы перенаправляете пользователя на страницу оплаты.
Пользователь выбирает способ оплаты, вводит данные и подтверждает платеж.
ЮKassa проводит платеж.
ЮKassa перенаправляет пользователя на URL возврата (return_url в запросе).
Если у вас настроены уведомления, ЮKassa присылает уведомление об изменении статуса платежа.
Вы запрашиваете информацию о платеже — отправляете ЮKassa GET-запрос с идентификатором платежа.
ЮKassa возвращает вам созданный объект платежа в актуальном статусе.
Вы сообщаете пользователю результат проведения платежа.
Если платеж завершен успешно (объект платежа в статусе succeeded), ЮKassa передает платежное поручение в ГИС ЖКХ.
ГИС ЖКХ обрабатывает запрос и возвращает результат.

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

Шаг 1. Создайте платеж : отправьте ЮKassa запрос с данными для аутентификации, ключом идемпотентности и данными для платежа:

параметр amount с суммой и валютой платежа;
параметры для выбранного сценария интеграции;
параметр description с описанием платежа, которое пользователь увидит при оплате;
параметр capture со значением true, чтобы платеж автоматически перешел в статус succeeded после оплаты;
объект payment_order с данными для формирования платежного поручения .

Что учесть при подготовке данных платежного поручения для payment_order:

Обязательно добавьте в запрос как минимум один параметр из этого списка: payment_document_id , payment_document_number , account_number , unified_account_number , service_id .
Назначение платежа (payment_purpose ) должно быть не больше 210 символов.
Сформируйте назначение платежа с учетом рекомендаций из Письма Банка России № ИН-04-45|12 от 22.02.2018. Пример: Оплата ЖКХ;ЕЛС 80KX478547;ПРД 12.2024;Иванов Иван;г.Москва, ул.Флотская, д.1, кв.1

Пример запроса с данными платежного поручения (на примере Умного платежа)

cURL
curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Store ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.example.com/return_url"
        },
        "capture": true,
        "description": "Order No. 37",
        "payment_order": {
          "type": "utilities",
          "amount": {
            "currency": "RUB",
            "value": "2.00"
          },
          "recipient": {
            "name": "ПАО \"ЖЭУ №2\"",
            "inn": "1234567890",
            "kpp": "123451234",
            "bank": {
              "name": "АРХАНГЕЛЬСКОЕ ОТДЕЛЕНИЕ N 8637 ПАО СБЕРБАНК",
              "bic": "041117601",
              "account": "12345678901234567890",
              "correspondent_account": "12345678901234567890"
            }
          },
          "payment_period": {
            "month": "9",
            "year": "2024"
          },
          "payment_purpose": "Оплата по счёту 00000000001 за 09/2024, г.Архангельск, ул.Комсомольская, д.40 корп.1, кв.29 плательщик не идентифицирован, НДС не облагается",
          "service_id": "80KX478547-13",
          "payment_document_id": "80KX478547-13-4091",
          "payment_document_number": "123456789",
          "account_number": "56400023214",
          "unified_account_number": "80KX478547"
        }
      }'

В объекте платежа объект payment_order не возвращается.

Пример созданного объекта платежа

JSON
{
    "id": "23d93cac-000f-5000-8000-126628f15141",
    "status": "pending",
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "description": "Order No. 37",
    "recipient":{
        "account_id":"100500",
        "gateway_id":"100700"
    },
    "created_at": "2024-12-04T12:39:42.778Z",
    "confirmation": {
        "type": "redirect",
        "confirmation_url": "https://yoomoney.ru/api-pages/v2/payment-confirm/epl?orderId=23d93cac-000f-5000-8000-126628f15141"
    },
    "test": false,
    "paid": false,
    "refundable": false,
    "metadata": {}
}

Шаг 2. Проведите платеж в соответствии с выбранным сценарием интеграции.

Шаг 3. Дождитесь успешного завершения платежа: подождите, когда придет уведомление от ЮKassa, или периодически отправляйте запросы, чтобы получить информацию о платеже .

Пример объекта платежа в статусе succeeded

JSON
{
    "id": "23d93cac-000f-5000-8000-126628f15141",
    "status": "succeeded",
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "income_amount": {
        "value": "1.93",
        "currency": "RUB"
    },
    "description": "Order No. 37",
    "recipient":{
        "account_id":"100500",
        "gateway_id":"100700"
    },
    "payment_method": {
        "type": "mobile_balance",
        "id": "23d93cac-000f-5000-8000-126628f15141",
        "saved": false
    },
    "captured_at": "2024-12-04T14:25:28.775Z",
    "created_at": "2024-12-04T12:39:42.778Z",
    "test": false,
    "refunded_amount": {
        "value": "0.00",
        "currency": "RUB"
    },
    "paid": true,
    "refundable": false,
    "metadata": {}
}

Шаг 4. Отобразите пользователю результат проведения платежа (успех или неудача) в зависимости от статуса платежа.

Готово!