Payouts to YooMoney wallets

This article describes the features and procedure for making payouts to YooMoney wallets.

Payout limits

You can make payouts to a YooMoney user of any status.

Limits on the amount of payouts:

the minimum payout amount is 1 ruble;
the maximum amount of a single payout depends on the current wallet balance. After making a payout, the wallet balance can’t exceed a certain amount:
- Anonymous status: 15,000 rubles;
- Reviewed status: 60,000 rubles;
- Identified status: 500,000 rubles;
the maximum amount of payouts per month: 600,000 rubles.

General scenario for making payouts to YooMoney wallets

You request the details of the YooMoney wallet that the user wants to receive the payout to.
The user provides you with the wallet number.
You create a payout by sending a POST request to YooMoney detailing the amount to be debited from your balance and where to transfer it.
YooMoney transfers the payout to the user's wallet and returns the payout object with the final status, which is either succeeded (payout successful) or canceled (payout canceled).

If in response to the request YooMoney returns the payout object with the pending status, it means that YooMoney is still transferring money to the user's wallet. 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).

Making a payout

To make a payout to YooMoney wallets:

Obtain details of the YooMoney wallet.
Make a payout using the obtained details.

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 specify the saved data ID in the request for creating the payout. Learn more about sending the recipient's data for the purpose of making extracts from reports

Obtaining YooMoney wallet details

You need the YooMoney wallet number to process a payout. Obtain it using any method that’s convenient for you.

Inform the user that after making a payout, the wallet balance can’t exceed a certain amount which depends on the user status. If the payout doesn't go through due to the balance limit, the recipient should upgrade their user status, spend the amount that exceeds the balance, or choose another way to receive the payout.

Processing payouts to YooMoney wallets

Create a payout : send YooMoney a request with data for authentication, the idempotence key, and information for making a payout to a YooMoney wallet:

in the amount object, set the amount to be paid to the user; the amount must be within limits;
in the description parameter, provide the description for the payout;
set the yoo_money payout type code and the number of the wallet to which the payout should be made in the payout_destination_data object;
if you make payouts with recipient's data specified for the extract from a report, set the personal data ID in the personal_data array.

Example of a request for creating a payout

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": "2.00",
          "currency": "RUB"
        },
        "payout_destination_data": {
          "type": "yoo_money",
          "account_number": "4100116075156746"
        },
        "description": "Payout for order No. 37",
        "metadata": {
          "order_id": "37"
        }
      }'

Example of a created payout object

JSON
{
    "id": "po-285ec15d-0003-5000-a000-08d1bec7dade",
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "status": "pending",
    "payout_destination": {
        "type": "yoo_money",
        "account_number": "4100116075156746"
    },
    "description": "Payout for order No. 37",
    "created_at": "21.06.2021T14:28:45.132Z",
    "metadata": {
        "order_id": "37"
    },
    "test": "false"
}

If you received a payout object 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 in the succeeded status

JSON
{
    "id": "po-285ec15d-0003-5000-a000-08d1bec7dade",
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "status": "succeeded",
    "payout_destination": {
        "type": "yoo_money",
        "account_number": "4100116075156746"
    },
    "description": "Payout for order No. 37",
    "created_at": "21.06.2021T14:28:45.132Z",
    "metadata": {
        "order_id": "37"
    },
    "test": "false"
}