Docs

YooMoney API
Guides
Old versions of the API
Help
Sign in
Sign up for YooMoney
Reference
YooMoney API
YooKassa API
Old versions of the API
Help
Sign in | Sign up for YooMoney
Русский
Выплаты самозанятым
С помощью ЮKassa вы можете делать выплаты самозанятым с автоматической регистрацией чека в сервисе Мой налог.

Выплаты самозанятым можно делать только на банковские карты и кошельки ЮMoney.

Как это работает
Чтобы при выплатах ЮKassa автоматически регистрировала чеки, нужно получить от самозанятого ИНН и разрешение для ЮMoney на взаимодействие с сервисом Мой налог от имени самозанятого.
Для этого вам необходимо получить ИНН самозанятого или номер его телефона, привязанный к сервису Мой налог, и передать эти данные ЮKassa. ЮKassa создаст в сервисе Мой налог заявку на выдачу прав и вернет вам ссылку для подтверждения заявки. Вам необходимо перенаправить самозанятого по этой ссылке и дождаться, когда он выдаст разрешение. Если вы передавали номер телефона, ЮKassa также вернет вам ИНН самозанятого.
При проведении выплаты самозанятому в запросе на создание выплаты нужно дополнительно передавать данные для регистрации чека в сервисе Мой налог. При проведении выплат самозанятым ЮKassa проверяет следующее:
  • получатель выплаты имеет статус самозанятого;
  • годовой доход получателя с учетом текущей выплаты не превышает 2,4 миллиона рублей (иначе получатель потеряет статус самозанятого);
  • получатель выплаты разрешил ЮMoney регистрировать за него чеки в сервисе Мой налог.
Если хотя бы одно из этих условий не выполняется, выплата не пройдет. В этом случае необходимо зачислять перевод получателю выплаты как обычному физическому лицу: без регистрации чека и с отдельного шлюза ЮKassa.

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

Если вы хотите, чтобы в выписках из реестра выплат отображалась информация о получателе выплаты (например, для госорганов), перед проведением выплаты сохраните данные о получателе в ЮKassa и затем передайте идентификатор сохраненных данных в запросе на создание выплаты. Подробнее о передаче данных получателя выплаты для выписок
Общий сценарий проведения выплат самозанятым
Сначала нужно получить от самозанятого его ИНН и разрешение для ЮMoney, после этого можно проводить выплаты с автоматической регистрацией чеков в сервисе Мой налог.
Запрос прав на регистрацию чеков в сервисе Мой налог
В этом разделе описан общий сценарий проведения выплаты для случая, когда самозанятый зарегистрирован в сервисе Мой налог и у ЮMoney нет разрешения на регистрацию чеков от имени самозанятого.
Подробнее о других возможных ответах ЮKassa в случаях, когда пользователь не зарегистрирован в сервисе Мой налог, потерял статус самозанятого или уже выдал ЮMoney разрешение, читайте в разделе Обработка результатов запроса.
Запрос прав на регистрацию чеков в сервисе Мой налог
  1. Вы запрашиваете у пользователя данные для его идентификации в сервисе Мой налог: ИНН или номер телефона, привязанного к сервису.
  2. Пользователь сообщает вам данные.
  3. Вы создаете объект самозанятого — отправляете ЮKassa POST-запрос с теми данными, которые получили от пользователя.
  4. ЮKassa отправляет сервису Мой налог запрос на получение прав для автоматической регистрации чеков за пользователя.
  5. Сервис Мой налог возвращает ЮKassa информацию о самозанятом.
  6. ЮKassa возвращает вам объект самозанятого в статусе pending со ссылкой для подтверждения запроса.
  7. Вы перенаправляете пользователя в сервис Мой налог по полученной ссылке.
  8. Пользователь в сервисе Мой налог подтверждает выдачу прав.
  9. Вы узнаете результат — отправляете ЮKassa GET-запрос для получения статуса объекта самозанятого.
  10. ЮKassa запрашивает в сервисе Мой налог статус заявки.
  11. Сервис Мой налог сообщает статус.
  12. ЮKassa возвращает вам объект самозанятого в статусе confirmed (права выданы) или canceled (пользователь отказался выдать права).
Если объект вернется в статусе confirmed, то можно делать выплаты с автоматической регистрацией чеков. Выданное разрешение будет действовать, пока получатель выплаты не отзовет его или не потеряет статус самозанятого.
Проведение выплат самозанятому

Самозанятым доступны только выплаты на банковские карты и кошельки ЮMoney.

Проведение выплаты самозанятому
  1. Вы запрашиваете у пользователя данные о способе получения выплаты.
  2. Пользователь сообщает вам необходимые данные.
  3. Вы создаете выплату — отправляете ЮKassa POST-запрос с данными для выплаты на выбранный способ получения выплаты и с данными для регистрации чека.
  4. ЮKassa отправляет в сервис Мой налог данные для регистрации чека.
  5. Мой налог сообщает результат регистрации чека.
  6. Если с чеком всё хорошо, ЮKassa отправляет эквайеру распоряжение на перевод денег получателю выплаты.
  7. Эквайер обрабатывает запрос и сообщает результат выполнения операции.
  8. ЮKassa возвращает вам объект выплаты с финальным статусом — succeeded (выплата успешна) или canceled (выплата отменена).
Если в ответ на запрос ЮKassa вернула вам объект выплаты в статусе pending, это значит, что эквайер еще обрабатывает распоряжение на перевод. To find out the final status of the payout, wait for the YooMoney notification or request payout information using the GET method with increasing reasonable intervals (for example, you can use the Fibonacci sequence).
Запрос прав на регистрацию чеков в сервисе Мой налог
Общий порядок действий при запросе прав описан в разделе Общий сценарий проведения выплат самозанятым. Здесь приведена пошаговая инструкция с учетом возможных ответов ЮKassa и особенностей их обработки:
Шаг 1. Получение данных самозанятого
Сообщите пользователю, что ему необходимо выдать разрешение ЮMoney для автоматической регистрации чеков, и запросите у него ИНН или номер телефона, привязанный к сервису Мой налог.
Шаг 2. Создание объекта самозанятого
Чтобы создать объект самозанятого , отправьте ЮKassa запрос с данными для аутентификации, ключом идемпотентности и данными для запроса прав в сервисе Мой налог:
  • для идентификации пользователя в сервисе Мой налог передайте ИНН в параметре itn или номер телефона в параметре phone;
  • в объекте confirmation передайте параметр type со значением redirect.
Пример запроса на создание объекта самозанятого
cURL
PHP
Python
curl https://api.yookassa.ru/v3/self_employed \
  -X POST \
  -u <Gateway ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "itn": "123456789012",
        "confirmation": {
          "type": "redirect"
        }
      }'
Шаг 3. Обработка результатов запроса
Дальнейшие действия зависят от ответа, который вернет ЮKassa. Проверьте статус созданного объекта самозанятого .
Объект самозанятого в статусе confirmed
Статус confirmed означает, что самозанятый уже выдал ЮMoney разрешение и вы можете делать выплаты.
Пример объекта самозанятого в статусе confirmed
JSON
{
  "id": "se-d6b9b3fa-0cb8-4aa8-b3c0-254bf0358d4c",
  "status": "confirmed",
  "created_at": "2020-02-12T11:10:41.802Z",
  "itn": "123456789012",
  "test": false
}
Объект самозанятого в статусе canceled
Если вы отправили запрос на создание объекта самозанятого, и ЮKassa сразу вернула объект в статусе canceled, это значит, что у самозанятого недавно уже запрашивали права на регистрацию чеков и он отказался их выдать. Повторите запрос с новым ключом идемпотентности через 15 минут.
Нужно дождаться, когда объект самозанятого перейдет в статус pending, значит, ЮKassa заново запросила права у пользователя. Что делать, когда объект перейдет в статус pending
Пример созданного объекта самозанятого в статусе canceled
JSON
{
    "id": "se-d6b9b3fa-0cb8-4aa8-b3c0-254bf0358d4c",
    "status": "canceled",
    "created_at": "2020-02-12T11:10:41.802Z",
    "itn": "123456789012",
    "metadata": {},
    "test": false
}
Объект самозанятого в статусе pending
Статус pending означает, что самозанятому нужно перейти в сервис Мой налог и выдать права ЮMoney, чтобы при проведении выплат ЮKassa могла регистрировать чеки. Для этого:
  1. Перенаправьте пользователя на confirmation_url, который придет в объекте самозанятого. Это ссылка на сервис Мой налог, в котором пользователь выдаст ЮMoney права для регистрации чеков.
  2. Дождитесь, когда статус объекта самозанятого изменится на confirmed или canceled. Для этого повторяйте запрос с тем же ключом идемпотентности или запрашивайте информацию о самозанятом методом GET с возрастающим разумным интервалом.
Если статус объекта изменился на canceled, вы можете сообщить самозанятому, что выплата без разрешения на регистрацию чеков в сервисе Мой налог невозможна, и повторно отправить запрос на создание объекта самозанятого.
При необходимости вы можете провести выплату самозанятому как обычному физическому лицу: без регистрации чека и с отдельного шлюза ЮKassa.
Пример созданного объекта самозанятого в статусе pending
JSON
{
  "id": "se-d6b9b3fa-0cb8-4aa8-b3c0-254bf0358d4c",
  "status": "pending",
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://lknpd.nalog.ru/settings/partners/"
  },
  "created_at": "2020-02-12T11:10:41.802Z",
  "itn": "123456789012",
  "test": false
}
Пример запроса на получение информации о самозанятом
cURL
PHP
Python
curl https://api.yookassa.ru/v3/self_employed/{self_employed_id} \
  -X GET \
  -u <Gateway ID>:<Secret Key> \
Объект самозанятого в статусе unregistered
Статус unregistered означает, что пользователя с таким ИНН и статусом самозанятого нет в сервисе Мой налог.
Сообщите самозанятому, что пользователь с переданным в запросе ИНН не зарегистрирован в сервисе Мой налог или потерял статус самозанятого. Затем повторно запросите у пользователя ИНН или номер телефона и отправьте запрос с новым ключом идемпотентности и новыми данными.
При необходимости вы можете провести выплату самозанятому как обычному физическому лицу: без регистрации чека и с отдельного шлюза ЮKassa.
Пример созданного объекта самозанятого в статусе unregistered
JSON
{
    "id": "se-d6b9b3fa-0cb8-4aa8-b3c0-254bf0358d4c",
    "status": "unregistered",
    "created_at": "2020-02-12T11:10:41.802Z",
    "itn": "123456789012",
    "metadata": {},
    "test": false
}
Ошибка HTTP 400 вместо объекта самозанятого
Если при создании объекта самозанятого вы передадите только номер телефона (без ИНН), и в сервисе Мой налог не окажется пользователя с таким номером, в ответ на запрос вернется ошибка HTTP 400.
Сообщите пользователю, что номер телефона указан некорректно или самозанятый не зарегистрирован в сервисе Мой налог. Затем повторно запросите у пользователя ИНН или номер телефона и отправьте запрос с новым ключом идемпотентности и новыми данными.
При необходимости вы можете провести выплату самозанятому как обычному физическому лицу: без регистрации чека и с отдельного шлюза ЮKassa.
Проведение выплат с регистрацией чеков
Чтобы сделать выплату самозанятому:
  1. Получите данные для проведения выплаты.
  2. Проведите выплату с полученными данными.
Получение данных для выплаты
Для проведения выплаты вам понадобится id самозанятого в ЮKassa, описание услуги, оказанной самозанятым, и данные о способе получения выплаты:
Проведение выплаты
Создайте выплату : отправьте ЮKassa запрос с данными для аутентификации, ключом идемпотентности, данными о том, куда перевести выплату, и следующими данными для регистрации чека в сервисе Мой налог:
  • в объекте self_employed передайте идентификатор самозанятого, который вы получили при запросе прав в сервисе Мой налог;
  • в объекте receipt_data передайте описание услуги, которую вам оказал получатель выплаты, и при необходимости сумму для печати в чеке (сумма в чеке должна быть больше суммы выплаты или равна ей).
Пример запроса на создание выплаты (для выплаты на банковскую карту)
cURL
curl https://api.yookassa.ru/v3/payouts \
  -X POST \
  -u <Gateway ID>: <Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "5.00",
          "currency": "RUB"
        },
        "payout_token": "<Bank card synonym>",
        "self_employed":
        {
            "id": "se-d6b9b3fa-0cb8-4aa8-b3c0-254bf0358d4c"
        },
        "receipt_data":
        {
            "service_name": "Document delivery service"
        },
        "description": "Payout for order No. 37",
        "metadata": {
          "order_id": "37",
          "courier_id": "001"
        }
      }'
В ответ на запрос ЮKassa вернет созданный объект выплаты .
Пример созданного объекта выплаты
JSON
{
    "id": "po-285ec15d-0003-5000-a000-08d1bec7dade",
    "amount": {
        "value": "5.00",
        "currency": "RUB"
    },
    "status": "pending",
    "payout_destination": {
        "type": "bank_card",
        "card": {
           "first6": "220220",
           "last4": "2537",
           "card_type": "Mir",
           "issuer_country": "RU",
           "issuer_name": "Sberbank Of Russia"
        }
    },
    "description": "Payout for order No. 37",
    "created_at": "21.06.2021T14:28:45.132Z",
    "self_employed":
    {
        "id": "se-d6b9b3fa-0cb8-4aa8-b3c0-254bf0358d4c"
    },
    "receipt":
    {
        "service_name": "Document delivery service",
        "npd_receipt_id": "208jd98zqe",
        "url": "https://www.nalog.gov.ru/api/v1/receipt/208jd98zqe/print"
    },
    "metadata": {
        "order_id": "37",
        "courier_id": "001"
    },
    "test": "false"
}
Если вы получили объект выплаты в статусе pending, дождитесь, когда статус изменится на succeeded или canceled. Wait for the YooMoney notification or request payout information  with an increasing reasonable interval.
Пример запроса на получение информации о выплате
cURL
curl https://api.yookassa.ru/v3/payouts/{payout_id} \
    -X GET \
    -u <Gateway ID>:<Secret Key> \
Пример объекта выплаты в статусе succeeded
JSON
{
    "id": "po-285ec15d-0003-5000-a000-08d1bec7dade",
    "amount": {
        "value": "5.00",
        "currency": "RUB"
    },
    "status": "succeeded",
    "payout_destination": {
        "type": "bank_card",
        "card": {
           "first6": "220220",
           "last4": "2537",
           "card_type": "Mir",
           "issuer_country": "RU",
           "issuer_name": "Sberbank Of Russia"
        }
    },
    "description": "Payout for order No. 37",
    "created_at": "21.06.2021T14:28:45.132Z",
    "self_employed":
    {
        "id": "se-d6b9b3fa-0cb8-4aa8-b3c0-254bf0358d4c"
    },
    "receipt":
    {
        "service_name": "Document delivery service",
        "npd_receipt_id": "208jd98zqe",
        "url": "https://www.nalog.gov.ru/api/v1/receipt/208jd98zqe/print"
    },
    "test": "false"
}
В случае успеха объект выплаты будет содержать ссылку на сформированный чек.

Посмотреть сформированные чеки и скачать архив с чеками можно в личном кабинете ЮKassa, в истории выплат.

See also
Payouts to bank cards
Payouts to YooMoney wallets
Declined payouts
HTTP response codes
Legal information
Terms and Conditions of the YooMoney ServiceElectronic Document Flow Agreement
Not a developer?
Modules for CMSInvoicing to clientsPayments for landing pages
+7 (495) 974-35-86
Ask a questionHelp
© 2024, "YooMoney", NBCO LLC