Выплаты самозанятым — Выплаты по API ЮKassa

Выплаты самозанятым

С помощью ЮKassa вы можете делать выплаты самозанятым с автоматической регистрацией чека в сервисе Мой налог.

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

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

Чтобы при выплатах ЮKassa автоматически регистрировала чеки, нужно получить от самозанятого ИНН и разрешение для ЮMoney на взаимодействие с сервисом Мой налог от имени самозанятого.

Для этого вам необходимо получить ИНН самозанятого или номер его телефона, привязанный к сервису Мой налог, и передать эти данные ЮKassa. ЮKassa создаст в сервисе Мой налог заявку на выдачу прав и вернет вам ссылку для подтверждения заявки. Вам необходимо перенаправить самозанятого по этой ссылке и дождаться, когда он выдаст разрешение. Если вы передавали номер телефона, ЮKassa также вернет вам ИНН самозанятого.

При проведении выплаты самозанятому в запросе на создание выплаты нужно дополнительно передавать данные для регистрации чека в сервисе Мой налог. При проведении выплат самозанятым ЮKassa проверяет следующее:

получатель выплаты имеет статус самозанятого;
годовой доход получателя с учетом текущей выплаты не превышает 2,4 миллиона рублей (иначе получатель потеряет статус самозанятого);
получатель выплаты разрешил ЮMoney регистрировать за него чеки в сервисе Мой налог.

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

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

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

Сначала нужно получить от самозанятого его ИНН и разрешение для ЮMoney, после этого можно проводить выплаты с автоматической регистрацией чеков в сервисе Мой налог.

Запрос прав на регистрацию чеков в сервисе Мой налог

Вы запрашиваете у пользователя данные для его идентификации в сервисе Мой налог: ИНН или номер телефона, привязанного к сервису.
Пользователь сообщает вам данные.
Вы создаете объект самозанятого — отправляете ЮKassa POST-запрос с теми данными, которые получили от пользователя.
ЮKassa отправляет сервису Мой налог запрос на получение прав для автоматической регистрации чеков за пользователя.
Сервис Мой налог возвращает ссылку, на которую нужно перенаправить пользователя для подтверждения запроса.
ЮKassa возвращает вам объект самозанятого в статусе pending и с ссылкой для подтверждения запроса.
Вы перенаправляете пользователя в сервис Мой налог по полученной ссылке.
Пользователь в сервисе Мой налог подтверждает выдачу прав.
Вы узнаете результат — отправляете ЮKassa GET-запрос для получения статуса объекта самозанятого.
ЮKassa запрашивает в сервисе Мой налог статус заявки.
Сервис Мой налог сообщает статус.
ЮKassa возвращает вам объект самозанятого в статусе confirmed (права выданы) или canceled (пользователь отказался выдать права).

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

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

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

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

Вы запрашиваете у пользователя данные о способе получения выплаты.
Пользователь сообщает вам необходимые данные.
Вы создаете выплату — отправляете ЮKassa POST-запрос с данными для выплаты на выбранный способ получения выплаты и с данными для регистрации чека.
ЮKassa отправляет в сервис Мой налог данные для регистрации чека.
Мой налог сообщает результат регистрации чека.
Если с чеком всё хорошо, ЮKassa отправляет эквайеру распоряжение на перевод денег получателю выплаты.
Эквайер обрабатывает запрос и сообщает результат выполнения операции.
ЮKassa возвращает вам объект выплаты с финальным статусом — succeeded (выплата успешна) или canceled (выплата отменена).

Если в ответ на запрос ЮKassa вернула вам объект выплаты в статусе pending, это значит, что эквайер еще обрабатывает распоряжение на перевод. Чтобы узнать финальный статус, повторяйте запрос на проведение выплаты с тем же ключом идемпотентности или запрашивайте информацию о выплате методом GET с возрастающим разумным интервалом (например, можно использовать последовательность Фибоначчи).

Запрос прав на регистрацию чеков в сервисе Мой налог

Шаг 1. Сообщите пользователю, что ему необходимо выдать разрешение ЮMoney для автоматической регистрации чеков, и запросите у него ИНН или номер телефона, привязанный к сервису Мой налог.

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

для идентификации пользователя в сервисе Мой налог передайте ИНН в параметре itn или номер телефона в параметре phone;
в объекте confirmation передайте параметр type со значением redirect.

Пример запроса на создание самозанятого

cURL
curl https://api.yookassa.ru/v3/self_employed \
  -X POST \
  -u <Идентификатор шлюза>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "itn": "123456789012",
        "confirmation": {
          "type": "redirect"
        }
      }'

В ответ на запрос ЮKassa вернет созданный объект самозанятого .

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

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
}

Шаг 3. Проверьте статус самозанятого. Он может быть confirmed или pending.

Статус confirmed означает, что у ЮKassa уже есть права и вы можете делать выплаты.

Статус pending означает, что самозанятому нужно перейти в сервис Мой налог и выдать права ЮMoney, чтобы при проведении выплат ЮKassa могла регистрировать чеки. Для этого:

Перенаправьте пользователя на confirmation_url, который придет в объекте самозанятого. Это ссылка на сервис Мой налог, в котором пользователь выдаст ЮMoney права для регистрации чеков.
Дождитесь, когда статус объекта самозанятого изменится на confirmed или canceled. Для этого повторяйте запрос с тем же ключом идемпотентности или запрашивайте информацию о самозанятом методом GET с возрастающим разумным интервалом.

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

cURL
curl https://api.yookassa.ru/v3/self_employed/{self_employed_id} \
  -X GET \
  -u <Идентификатор шлюза>:<Секретный ключ> \

Пример объекта самозанятого в статусе confirmed

JSON
{
  "id": "se-d6b9b3fa-0cb8-4aa8-b3c0-254bf0358d4c",
  "status": "confirmed",
  "created_at": "2020-02-12T11:10:41.802Z",
  "itn": "123456789012",
  "test": false
}

Проведение выплат с регистрацией чеков

Чтобы сделать выплату самозанятому:

Получите данные для проведения выплаты.
Проведите выплату с полученными данными.

Получение данных для выплаты

Для проведения выплаты вам понадобится id самозанятого в ЮKassa, описание услуги, оказанной самозанятым, и данные о способе получения выплаты:

Выплаты на банковскую карту (подойдет любой вариант — выплаты с использованием виджета, выплаты по номеру карты, выплаты с использованием сохраненного способа оплаты)
Выплаты на кошелек ЮMoney

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

Создайте выплату

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

в объекте self_employed передайте идентификатор самозанятого, который вы получили при запросе прав в сервисе Мой налог;
в объекте receipt_data передайте описание услуги, которую вам оказал получатель выплаты, и при необходимости сумму для печати в чеке (сумма в чеке должна быть больше суммы выплаты или равна ей).

Пример запроса на создание выплаты (для выплаты на банковскую карту)

cURL
curl https://api.yookassa.ru/v3/payouts \
  -X POST \
  -u <Идентификатор шлюза>: <Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "100.00",
          "currency": "RUB"
        },
        "payout_token": "<Синоним банковской карты>",
        "self_employed":
        {
            "id": "se-d6b9b3fa-0cb8-4aa8-b3c0-254bf0358d4c"
        },
        "receipt_data":
        {
            "service_name": "Доставка документов"
        },
        "description": "Выплата по заказу № 37",
        "metadata": {
          "order_id": "37",
          "courier_id": "001"
        }
      }'

В ответ на запрос ЮKassa вернет созданный объект выплаты .

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

JSON
{
    "id": "po-285ec15d-0003-5000-a000-08d1bec7dade",
    "amount": {
        "value": "100.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": "Выплата по заказу № 37",
    "created_at": "21.06.2021T14:28:45.132Z",
    "self_employed":
    {
        "id": "se-d6b9b3fa-0cb8-4aa8-b3c0-254bf0358d4c"
    },
    "receipt":
    {
        "service_name": "Доставка документов",
        "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. Для этого повторяйте запрос с тем же ключом идемпотентности или запрашивайте информацию о выплате методом GET с возрастающим разумным интервалом.

Пример запроса на получение информации о выплате

cURL
curl https://api.yookassa.ru/v3/payouts/{payout_id} \
    -X GET \
    -u <Идентификатор шлюза>:<Секретный ключ> \

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

JSON
{
    "id": "po-285ec15d-0003-5000-a000-08d1bec7dade",
    "amount": {
        "value": "100.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": "Выплата по заказу № 37",
    "created_at": "21.06.2021T14:28:45.132Z",
    "self_employed":
    {
        "id": "se-d6b9b3fa-0cb8-4aa8-b3c0-254bf0358d4c"
    },
    "receipt":
    {
        "service_name": "Доставка документов",
        "npd_receipt_id": "208jd98zqe",
        "url": "https://www.nalog.gov.ru/api/v1/receipt/208jd98zqe/print"
    },
    "test": "false"
}

В случае успеха объект выплаты будет содержать ссылку на сформированный чек.

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

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

Выплаты на банковские карты Выплаты на кошельки ЮMoney Неуспешные выплаты Коды ответа (состояния) HTTP