Payouts to the self-employed

Using YooMoney, you may make payouts to self-employed individuals with automatic record of receipts in Moi nalog.

Payouts to the self-employed can only be made to bank cards and YooMoney wallets.

How it works

In order to make payouts via YooMoney and record receipts automatically, it's necessary to obtain the INN (TIN) and permission for interaction with Moi nalog from the self-employed individual.

To do this, you need to receive the self-employed individual's INN (TIN) or their phone number linked to Moi nalog, and send it to YooMoney. YooMoney creates a request for granting rights in Moi nalog and return a link for you to confirm the request. You need to redirect the self-employed individual using this link and wait for them to grant the permission. If you submitted a phone number, YooMoney will also return the self-employed individual's INN (TIN).

When you make a payout to the self-employed, it's required to send the additional details for recording the receipt in Moi nalog through the request for creating a payout. When you make payouts to the self-employed, YooMoney checks the following information:

payout recipient is a self-employed individual;
recipient's annual income (including the current payout) doesn't exceed 2.4 million rubles (otherwise the recipient will stop being self-employed);
recipient has authorized YooMoney to record their receipts in Moi nalog.

If even one of these conditions isn't fulfilled, the payout won't go through. In this case, it's necessary to make a payout to the recipient as a regular individual: without recording the receipt and via a separate YooMoney gateway.

If you need to make payouts to both individuals and the self-employed, you can ask your YooMoney manager to set up two gateways, one for each type of payout recipient.

If you need to display the payout recipient information in payout report extracts (e.g., for submission to government agencies), save the recipient's data in YooMoney before making a payout. Then set the saved data ID in the request for creating a payout. Learn more about sending the recipient's data for the purpose of making extracts from reports

General scenario for making payouts to the self-employed

First you need to request the INN (TIN) and permission for YooMoney from the self-employed individual. After that, you can start making payouts with automatic record of receipts in Moi nalog.

Request for granting rights to record receipts in Moi nalog

This section describes the general scenario for making a payout when a recipient signed up for Moi nalog, while YooMoney doesn't have permission to record receipts on the self-employed individual's behalf.

Learn more about other possible YooMoney's responses in cases where the user didn't sign up for Moi nalog, has lost their self-employed status, or has already granted permission to YooMoney, in Processing request results.

Request for granting rights to record receipts in Moi nalog

You ask the user for information to identify them in Moi nalog: INN (TIN) or phone number linked to the service.
The user provides you with necessary details.
You create a self-employed object by sending a POST request with the information you received from the user.
YooMoney sends a request to Moi nalog in order to obtain rights for automatic recording receipts on the user's behalf.
Moi nalog returns YooMoney information about the self-employed individual.
YooMoney returns you a self-employed object with the status pending and a link to confirm the request.
You redirect the user to Moi nalog using the received link.
The user proceeds to Moi nalog and confirms granting rights.
You send a GET request to YooMoney in order to get information about the status of the self-employed object.
YooMoney asks for the request status in Moi nalog.
Moi nalog sends the status.
YooMoney returns you a self-employed object with the status, which is either confirmed (rights granted) or canceled (user refused to grant rights).

If the object returns with the confirmed status, you can make payouts recording receipts automatically. The granted permission will be valid until the payout recipient revokes it or stops being self-employed.

Making payouts to the self-employed

Self-employed individuals may receive only payouts to bank cards and YooMoney wallets.

Making a payout to the self-employed individual

You ask the user for information about the payout type.
The user provides you with the necessary details.
You create a payout by sending a POST request with information for making a payout to the selected payout type and specify details for reporting the receipt.
YooMoney provides Moi nalog with the details needed to report the receipt.
Moi nalog sends the result of reporting the receipt.
If there's nothing wrong with the receipt, YooMoney sends an order to the acquirer to transfer money to the payout recipient.
The acquirer processes the request and reports on the results of the transaction.
YooMoney returns the payout object with the final status, which is either succeeded (payout successful) or canceled (payout canceled).

If, in response to a request, YooMoney returns the payout object with the pending status, it means the acquirer is still processing the payout order. 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).

Request for granting rights to record receipts in Moi nalog

The general procedure for requesting rights is described in General scenario for making payouts to the self-employed. Here are step-by-step instructions including possible YooMoney's responses and specifics of their processing:

What information should be obtained from the self-employed
How to create a self-employed object
Possible YooMoney's responses and their processing

Step 1. Obtaining the self-employed individual's data

Inform the user that they need to grant YooMoney a permission for automatic recording receipts, and ask them for the INN (TIN) or phone number linked to Moi nalog.

Step 2. Creating a self-employed object

In order to create a self-employed object , send YooMoney a request with authentication data, idempotence key, and information needed to request rights in Moi nalog:

to identify the user in Moi nalog, set the INN (TIN) in the itn parameter or the phone number in the phone parameter;
in the confirmation object, set the type parameter with the redirect value.

Example of a request for creating a self-employed object

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"
        }
      }'

Step 3. Processing request results

The following steps depend on the response returned by YooMoney. Check the status of the created self-employed object .

Self-employed object with the confirmed status
Self-employed object with the canceled status
Self-employed object with the pending status
Self-employed object with the unregistered status
HTTP 400 error instead of a self-employed object

Self-employed object with the confirmed status

The confirmed status means that the self-employed individual has already granted permission to YooMoney, so you can make payouts.

Example of a self-employed object with the confirmed status

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

Self-employed object with the canceled status

If you sent a request for creating a self-employed object and YooMoney immediately returned the object with the canceled status, this means that the self-employed individual has recently refused to grant the rights to record receipts. Resend the request using a new idempotence key 15 minutes later.

You need to wait until the self-employed object changes to the pending status, which means that YooMoney has requested the user's rights again. What to do when the object changes to the pending status

Example of a created self-employed object with the canceled status

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

Self-employed object with the pending status

The pending status means that the self-employed individual needs to proceed to Moi nalog and grant rights to YooMoney, so that we could record receipts when you make payouts. To do that, you need to:

Redirect the user to the confirmation_url that will be sent in the self-employed object. This is a link to Moi nalog, where the user will grant the rights to record receipts for YooMoney.
Wait until the self-employed object changes to either confirmed or canceled status. To do this, resend the request with the same idempotence key or ask for information about the self-employed individual using the GET method at increasing reasonable intervals.

If the object status changed to canceled, you may inform the self-employed individual that it's not possible to make a payout without having a permission to report receipts in Moi nalog. Then, resend the request for creating a self-employed object.

If necessary, you can make a payout to a self-employed person as a regular individual: without reporting a receipt and via a separate YooMoney gateway.

Example of a created self-employed object with the pending status

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
}

Example of a request for information on the self-employed individual

cURL
PHP
Python
curl https://api.yookassa.ru/v3/self_employed/{self_employed_id} \
  -X GET \
  -u <Gateway ID>:<Secret Key> \

Self-employed object with the unregistered status

The status unregistered means that there's no user with this INN (TIN) and self-employed status in Moi nalog.

Inform the self-employed individual that the user with the INN (TIN) specified in the request isn't registered in Moi nalog, or has lost the status of self-employed. After that, ask for the user's INN (TIN) or phone number again, and send the request detailing new idempotence key and new information.

If necessary, you can make a payout to a self-employed person as a regular individual: without reporting a receipt and via a separate YooMoney gateway.

Example of a created self-employed object with the unregistered status

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 error instead of a self-employed object

If you set only a phone number (without the INN (TIN)) when creating a self-employed object and there's no user with that number in Moi nalog, the request will return an HTTP 400 error.

Notify the user that the phone number is incorrect or the self-employed individual isn't registered in Moi nalog. After that, ask for the user's INN (TIN) or phone number again, and send the request detailing a new idempotence key and new information.

If necessary, you can make a payout to a self-employed person as a regular individual: without reporting a receipt and via a separate YooMoney gateway.

Making payouts with record of receipts

To make a payout to the self-employed individual, you need to:

Obtain information for a payout.
Make a payout using the details received.

Obtaining information for a payout

In order to make a payout, you need the YooMoney's id of the self-employed individual, description of the service provided, and details of the payout type:

Payouts to bank cards (could be made using any method: a widget, card number, or saved payment method)
Payouts to YooMoney wallets

Making a payout

Create a payout : send a request with authentication data, idempotence key, information on where to transfer the payout, and the following details for recording the receipt in Moi nalog:

in the self_employed object, set the identifier of the self-employed individual received when you requested rights in Moi nalog;
in the receipt_data object, set a service description obtained from the payout recipient and, if necessary, the amount that will be printed in the receipt (this amount must exceed or be equal to the payout amount).

Example of a request for creating a payout (for payouts to bank cards)

cURL
PHP
Python
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"
        }
      }'

YooMoney will return a created payout object in response to the request.

Example of a created payout object

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"
}

If you received a payout with the pending status, wait until the status changes to succeeded or canceled. Wait for the YooMoney notification or request payout information with an increasing reasonable interval.

Example of a request for payout information

cURL
PHP
Python
curl https://api.yookassa.ru/v3/payouts/{payout_id} \
    -X GET \
    -u <Gateway ID>:<Secret Key> \

Example of a payout object with the succeeded status

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"
}

If the payout is successful, the payout object will contain a link to the created receipt.

You can view created receipts and download the receipts archive in your Merchant Profile under the payout history.