Old versions of the API
Help
Sign up for YooMoney
Оплата жилищно-коммунальных услуг
С помощью ЮKassa вы можете принимать платежи за жилищно-коммунальные услуги (ЖКУ), например платежи за содержание жилого помещения, холодную и горячую воду, взносы на капитальный ремонт и т.д. При оплате ЖКУ необходимо передавать сведения о платеже в Государственную информационную систему жилищно-коммунального хозяйства (ГИС ЖКХ).
В этой статье описано, как принимать платежи за ЖКУ через ЮKassa.
Как это работает
В каждом запросе на создание платежа вы передаете объект payment_order с данными платежного поручения. Это сведения о платеже, которые нужны для формирования распоряжения на перевод денег поставщику ЖКУ и регистрации сведений о платеже в ГИС ЖКХ. Когда ЮKassa получит оплату от пользователя, она отправит платежное поручение в ГИС ЖКХ, дождется его обработки и сообщит вам результат.
Для проведения платежа можно использовать любой сценарий интеграции. Доступны все способы оплаты, кроме электронных сертификатов и наличных.
Есть особенности:

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

Особенности регистрации сведений в ГИС ЖКХ
Регистрация платежного поручения в ГИС ЖКХ занимает от нескольких минут до одних суток.
ЮKassa отправляет платежное поручение в ГИС ЖКХ после успешного получения оплаты от пользователя. Пока ГИС ЖКХ не зарегистрирует данные, объект платежа будет в статусе pending, параметр paid будет со значением true. Вы можете сообщить пользователю, что оплата принята.
Когда ГИС ЖКХ обработает операцию и сообщит об этом ЮKassa, объект платежа перейдет в статус succeeded. Это значит, что платеж успешно завершен. Деньги будут перечислены на ваш расчетный счет в соответствии с вашим договором с ЮKassa. Это финальный и неизменяемый статус.
В крайних случаях, если по техническим причинам не получится зарегистрировать платежное поручение в ГИС ЖКХ, объект платежа перейдет в статус canceled. Деньги вернутся пользователю. Это финальный и неизменяемый статус.

Если прошло больше 25 часов, а объект платежа всё еще находится в статусе pending с paid=true или после оплаты статус изменился на canceled, обратитесь в техническую поддержку ЮKassa.

Общий сценарий и схема проведения платежа
В этом разделе описан общий сценарий проведения платежа на примере Умного платежа. Если вы используете другие сценарии интеграции, последовательность действий может незначительно отличаться.
Общая схема проведения платежа (на примере Умного платежа)
Общая схема проведения платежа (на примере Умного платежа)
Как проходит платеж:
  1. Пользователь переходит к оплате.
  2. Вы создаете платеж — отправляете ЮKassa POST-запрос с данными для формирования платежного поручения в объекте payment_order.
  3. ЮKassa возвращает вам созданный объект платежа в статусе pending и со ссылкой на платежную форму (параметр confirmation_url в объекте платежа).
  4. Вы перенаправляете пользователя на страницу оплаты.
  5. Пользователь выбирает способ оплаты, вводит данные и подтверждает платеж.
  6. ЮKassa проводит платеж.
  7. ЮKassa перенаправляет пользователя на URL возврата (return_url в запросе).
  8. Вы запрашиваете информацию о платеже — отправляете ЮKassa GET-запрос с идентификатором платежа.
  9. ЮKassa возвращает вам созданный объект платежа в актуальном статусе. Если оплата прошла успешно, параметр paid вернется со значением true.
  10. Вы сообщаете пользователю результат проведения платежа.
  11. ЮKassa передает платежное поручение в ГИС ЖКХ.
  12. ГИС ЖКХ обрабатывает запрос и возвращает результат.
  13. Если у вас настроены уведомления, ЮKassa присылает уведомление о переходе платежа в статус succeeded.
  14. Вы запрашиваете информацию о платеже — отправляете ЮKassa GET-запрос с идентификатором платежа.
  15. ЮKassa возвращает вам созданный объект платежа в актуальном статусе.
Проведение платежа
Шаг 1. Создайте платеж : отправьте ЮKassa запрос с данными для аутентификации, ключом идемпотентности и данными для платежа:
  • параметр amount с суммой и валютой платежа;
  • параметры для выбранного сценария интеграции;
  • параметр description с описанием платежа, которое пользователь увидит при оплате;
  • параметр capture со значением true, чтобы платеж автоматически перешел в статус succeeded после оплаты;
  • объект payment_order с данными для формирования платежного поручения .
Что учесть при подготовке данных платежного поручения для payment_order:
Пример запроса с данными платежного поручения (на примере Умного платежа)
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. Дождитесь, когда параметр paid примет значение true. Это значит, что оплата прошла успешно. Для этого периодически отправляйте запрос на получение информации о платеже .
Пример объекта платежа в статусе pending (paid=true)
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": true,
    "refundable": false,
    "metadata": {}
}
Шаг 5. Отобразите пользователю результат проведения платежа:
  • Успех: платеж в статусе succeeded или в статусе pending и paid=true;
  • Неудача: платеж в статусе canceled.
Шаг 4. Если вы получили платеж в статусе pending и с paid=true, дождитесь, когда платеж перейдет в статус succeeded. Для этого подождите, когда придет уведомление от Ю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": {}
}
Готово!
Особенности формирования реестров
ЮKassa ежедневно формирует реестры успешных операций (платежей и возвратов). В них попадают только успешные платежи и возвраты в статусе succeeded.

Если оплата принята, но платежное поручение еще не обработано в ГИС ЖКХ (объект платежа в статусе pending и с paid=true), платеж в реестр не попадет.

See also
Integration scenarios
Legal information
Terms and Conditions of the YooMoney ServiceElectronic Document Flow Agreement
+7 (495) 974-35-86
Ask a questionHelp
© 2024, "YooMoney", NBCO LLC