Old versions of the API
Help
Sign up for YooMoney
Payouts to sellers
To process a payout, you need to be informed by the seller on where their remuneration should be credited. After that, you need to send YooMoney a request for creating a payout.
Specifics
Payouts can be made to bank cards issued by Russian banks and YooMoney wallets with any status except anonymous.
There are limits for all types of payouts to sellers. If these limits are exceeded, the payouts will not be processed.
Type of payoutOne-time limitLimit per time period
Bank card
Limits are applied to a single bank card of the payout recipient
Minimum — 1 ruble
Maximum — 150,000 rubles
Maximum number of payouts per day — 20
Maximum amount of payouts per month — 1,500,000 rubles
YooMoney wallet
Limits depend on the wallet status
Minimum — 1 ruble
Maximum depends on the current wallet balance. After the payout, the balance must not exceed a certain amount:
  • Reviewed wallet — 60,000 rubles
  • Identified wallet — 500,000 rubles
Maximum amount of payouts per month — 600,000 rubles
Interaction scenario
To make a payout:
  1. Get the information from the seller on where their remuneration should be credited to.
  2. Process the payout using the information you received.
The procedure depends on the type of payout:
If a payout doesn’t go through, YooMoney will notify you about the reason why the payout was canceled.
Payouts to bank card
To process a payout, you need to receive seller’s bank card details. Receiving and storing bank card numbers is subject to the PCI DSS standard, so YooMoney stores card data on its side. Use the special YooMoney widget to get seller's bank card details.
If you have a certificate of compliance with the PCI DSS standard, you can collect the information by yourself and send the bank card number to YooMoney when processing the payout.
Select how you'd like to get seller's bank card details:
Payouts when banking details are obtained using the YooMoney widget
To make a payout to a bank card:
  1. Obtain the bank card details using the special YooMoney widget.
  2. Process the payout using the obtained banking details.
Obtaining bank card details
To obtain the bank card details for the payout, place the special widget on your website and display the form for entering bank card details to the seller. To do that, you need to:
Step 1. Implement the library. The script is available at:
https://static.yoomoney.ru/payouts-data-widget-front/widget.js
Step 2. Add an HTML element where you’d like to place the form to the page for collecting bank card details. Set the id attribute for this element.
Step 3. To initialize the widget, create a new instance of the PayoutsData class and add successCallback for receiving card’s parameters and errorCallback for receiving the error code.
Step 4. To display the form for entering the card number, call the render method. Add the value of the id attribute where the form should be placed and, if necessary, the code that should be run after the form is displayed to this method.
HTML
<!--Library implementation-->
<script src="https://static.yoomoney.ru/payouts-data-widget-front/widget.js"></script>

<!--HTML element where the form for entering the card number will be placed-->
<div id="payout-form"></div>

<script>
//Widget initialization. All parameters are required.
const payoutsData = new window.PayoutsData({
  successCallback(data) {
    //Processing the response with card’s token
  },
  errorCallback(error) {
    //Processing of initialization errors
  }
});

//Display of payment form in the container
payoutsData.render('payout-form')
//After the payment form is displayed, the render method returns Promise (optional).
  .then(() => {
    //Code that must be executed after the payment form is displayed.
  });
</script>
When the user enters the information, the library will call successCallback. As a result, you will receive the following data:
ParameterTypeDescription
synonim
string
Bank card synonym: card’s ID in YooMoney’s system. It must be used for processing payouts.
Example: uAFUv0jwtUA_8mMIFeRqzAYw.SC.001.202106
panmask
string
Card mask for displaying bank card details to the user.
Example: 555555******4477
bankName
string
Name of the issuer of the bank card.
Example: YOOMONEY NBCO LLC
type
string
Name of the payment system.
Example: MasterCard
You can store this information on your side with no risk of it getting leaked: publishing this information won’t lead to financial or public image problems.
A bank card synonym can be used multiple times and for different payouts. Multiple synonyms can be made for the same card.
If you get an error when receiving bank card details, initialize the widget again and ask the seller to enter details once more.
Processing payouts to bank card
Step 1. Create a payout : send YooMoney a request with data for authentication, the idempotency key, and information for a payout to a bank card:
  • specify the amount to be paid out to the seller in the amount object;
  • specify deal’s ID in the deal object;
  • enter the description of the payout in the description parameter;
  • enter the received bank card synonym in the payout_token parameter.
Example of a request for creating a payout
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payouts \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "800.00",
          "currency": "RUB"
        },
        "payout_token": "<Bank card synonym>",
        "description": "Payout for order No. 37",
        "metadata": {
          "order_id": "37"
        },
        "deal": {
          "id": "dl-285e5ee7-0022-5000-8000-01516a44b147"
        }
      }'
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": "800.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": "2021-06-21T14:28:45.132Z",
  "deal": {
    "id": "dl-285e5ee7-0022-5000-8000-01516a44b147"
  },
  "metadata": {
    "order_id": "37"
  },
  "test": false
}
Step 2. Wait until recipient’s bank confirms the payout and YooMoney changes the status of the payout object to succeeded. Send YooMoney periodic requests for information about the payout .
Example of a payout object with the succeeded status
JSON
{
  "id": "po-28559c4f-0003-5000-9000-0baf38b7a7fd",
  "amount": {
    "value": "800.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": "2021-06-21T14:28:45.132Z",
  "deal": {
    "id": "dl-285e5ee7-0022-5000-8000-01516a44b147"
  },
  "metadata": {
    "order_id": "37"
  },
  "test": false
}
If the payout is successful, YooMoney will close the deal.
Payouts when the bank card details are obtained independently

To specify the bank card number in the request for creating a payout, you need to get a certificate of compliance with the PCI DSS requirements.

To make a payout to a bank card:
  1. Obtain the bank card details.
  2. Process the payout using the obtained banking details.
Obtaining bank card details
You need the bank card number to process a payout. Obtain it using any method that’s convenient for you.
Payouts can only be made to cards issued by Russian banks.
Processing payouts to bank card
Step 1. Create a payout : send YooMoney a request with data for authentication, the idempotency key, and information for a payout to a bank card:
  • specify the amount to be paid out to the seller in the amount object;
  • specify deal’s ID in the deal object;
  • enter the description of the payout in the description parameter;
  • specify the bank_card payout type code and the number of the bank card to which seller’s remuneration should be transferred in the payout_destination_data object.
Example of a request for creating a payout
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payouts \
  -X POST \
  -u <Shop ID>: <Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "800.00",
          "currency": "RUB"
        },
        "payout_destination_data":
        {
            "type": "bank_card",
            "card": {
              "number": "5555555555554477"
          }
        },
        "description": "Payout for order No. 37",
        "metadata": {
          "order_id": "37"
        },
        "deal": {
          "id": "dl-285e5ee7-0022-5000-8000-01516a44b147"
        }
      }'
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": "800.00",
    "currency": "RUB"
  },
  "status": "pending",
  "payout_destination": {
    "type": "bank_card",
    "card": {
      "first6": "555555",
      "last4": "4477",
      "card_type": "Mir",
      "issuer_country": "RU",
      "issuer_name": "Sberbank Of Russia"
    }
  },
  "description": "Payout for order No. 37",
  "created_at": "2021-06-21T14:28:45.132Z",
  "deal": {
    "id": "dl-285e5ee7-0022-5000-8000-01516a44b147"
  },
  "metadata": {
    "order_id": "37"
  },
  "test": false
}
Step 2. Wait until recipient’s bank confirms the payout and YooMoney changes the status of the payout object to succeeded. Send periodic requests to YooMoney for information about the payout  or wait for the YooMoney notification.
Example of a payout object with the succeeded status
JSON
{
  "id": "po-28559c4f-0003-5000-9000-0baf38b7a7fd",
  "amount": {
    "value": "800.00",
    "currency": "RUB"
  },
  "status": "succeeded",
  "payout_destination": {
    "type": "bank_card",
    "card": {
      "first6": "555555",
      "last4": "4477",
      "card_type": "Mir",
      "issuer_country": "RU",
      "issuer_name": "Sberbank Of Russia"
    }
  },
  "description": "Payout for order No. 37",
  "created_at": "2021-06-21T14:28:45.132Z",
  "deal": {
    "id": "dl-285e5ee7-0022-5000-8000-01516a44b147"
  },
  "metadata": {
    "order_id": "37"
  },
  "test": false
}
If the payout is successful, YooMoney will close the deal.
Payouts to YooMoney wallets
To make a payout to a YooMoney wallet:
  1. Obtain the banking details of the YooMoney wallet.
  2. Process the payout using the obtained banking details.
Obtaining the information for payouts
You need the YooMoney wallet number to process a payout. Obtain it using any method that’s convenient for you.
To receive the payout, the owner of the wallet needs to complete the full or simplified identification in YooMoney (their wallet status must be reviewed or identified).
The maximum payout amount depends on the limit for balance: after the payout, the wallet balance can’t exceed a certain amount that depends on the wallet user’s status. If the payout wasn’t processed due to the limit for balance, the recipient must change their status or spend the excessive amount on the balance.
Processing payouts to YooMoney wallet
Create a payout : send YooMoney a request with data for authentication, the idempotency key, and information for a payout to a YooMoney wallet:
  • specify the amount to be paid out to the seller in the amount object;
  • specify deal’s ID in the deal object;
  • enter the description of the payout in the description parameter;
  • specify the yoo_money payout type code and the number of the wallet to which seller’s remuneration should be transferred in the payout_destination_data object.
Example of a request for creating a payout
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payouts \
  -X POST \
  -u <Shop ID>: <Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "800.00",
          "currency": "RUB"
        },
        "payout_destination_data": {
          "type": "yoo_money",
          "account_number": "4100116075156746"
        },
        "description": "Payout for order No. 37",
        "metadata": {
          "order_id": "37"
        },
        "deal": {
          "id": "dl-285e5ee7-0022-5000-8000-01516a44b147"
        }
      }'
YooMoney will return a created payout object  in response to the request. It will already be in the final status — succeeded or canceled.
Example of a created payout object
JSON
{
    "id": "po-28836e72-0003-5000-9000-08892e762c41",
    "amount": {
        "value": "800.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",
    "deal": {
        "id": "dl-285e5ee7-0022-5000-8000-01516a44b147"
    },
    "metadata": {
        "order_id": "37"
    },
    "test": "false"
}
If the payout is successful, YooMoney will close the deal.
Unsuccessful payouts
Something might go wrong during a payout. For example, the payout limit might get exceeded or YooMoney might suspect a fraud attempt. In this case, the payout will be canceled and its status will be updated correspondingly.
In order for you to have a better understanding of what happened and what you need to do with it, YooMoney will provide a comment to the canceled payout (cancellation_details) in the payout object . The comment will contain information about the initiator and reason for the cancellation. You can use this information to analyze and solve problems, display messages to the customer, or for any other purposes.
Example of a payout with the canceled status
JSON
{
    "id": "po-285c0ab7-0003-5000-9000-0e1166498fda",
    "amount": {
        "value": "400.00",
        "currency": "RUB"
    },
    "status": "canceled",
    "payout_destination": {
        "type": "bank_card",
        "card": {
            "first6": "444444",
            "last4": "4448",
            "card_type": "Visa",
            "issuer_country": "PL",
            "issuer_name": "Krakowski Bank Spoldzielczy"
        }
    },
    "description": "Payout for order No. 37",
    "created_at": "2021-06-16T13:04:55.633Z",
    "deal": {
        "id": "dl-28559370-0022-5000-8000-0b65d8e0e06d"
    },
    "metadata": {
        "order_id": "37"
    },
    "test": false,
    "cancellation_details": {
        "party": "yoo_money",
        "reason": "general_decline"
    }
}
Initiators of the cancellation of the payout
The initiator of the cancellation is returned in the party parameter of the cancellation_details object.
ValueDescription
yoo_moneyYooMoney
payout_network“External” participants of the payout process, i.e. all the other participants of the process except for you YooMoney and you (for example, the bank card issuer)
Reasons why the payout was canceled
The reason for the cancellation is returned in the reason parameter of the cancellation_details object.
ValueDescription
fraud_suspectedPayout blocked due to suspicions of fraudulent actions Contact the party that cancelled the payout to learn more details or select another method of receiving the payout or other means of payment (for example, a different bank card).
general_declineNo specific reason provided. User will have to contact the cancellation initiator for more details
identification_requiredThis YooMoney wallet is not identified. Adding money to anonymous wallets is forbidden. The user needs to complete identification
one_time_limit_exceededExceeded limit per single replenishment. Decrease the payment amount, split the amount and make several payouts, select another method of receiving the payout or other means of payment (for example, a different bank card).
periodic_limit_exceededExceeded limit per time period (day, month). Select another method of receiving the payout or other means of payment (for example, a different bank card).
rejected_by_payeeIssuer declined the payout for unspecified reasons. The user must contact the issuer to learn more details or select another method of receiving the payout or other means of payment (for example, a different bank card).
See also
Notifications