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 and on how you receive the information from the user:
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
<!--Implementing the library-->
<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>
//Initializing the widget. All the parameters are mandatory.
const payoutsData = new window.PayoutsData({
  successCallback(data) {
    //Processing the response with card’s token
  },
  errorCallback(error) {
    //Processing initialization errors
  }
});

//Displaying the payment form in the container
payoutsData.render('payout-form')
//After the payment form is displayed, the render method returns Promise (optional).
  .then(() => {
    //Code that should be run 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
synonimstring
Bank card synonym: card’s ID in YooMoney’s system. It must be used for processing payouts.
Example:
uAFUv0jwtUA_8mMIFeRqzAYw.SC.001.202106
panmaskstring
Card mask for displaying bank card details to the user.
Example:
555555******4477
bankNamestring
Name of the issuer of the bank card.
Example:
YOOMONEY NBCO LLC
typestring
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 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": "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
merchantGateway (you)
yoo_moneyYooMoney
payment_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
general_declineNo specific reason provided. User will have to contact the cancellation initiator for more details
one_time_limit_exceededLimit per time period (day, month) exceeded. More about limits
periodic_limit_exceededlimit per time period (day, month) exceeded. More about limits
rejected_by_payeeIssuer declined the payout for unspecified reasons.

Do you have any questions or comments regarding the documentation?

We can set up a call and discuss them: we'll help you solve the problem and you'll help us understand what we need to improve. To do that, share your contact information and select the time.
Yes, I'd like to set up a meeting
See also
NotificationsBasics of using the APITesting Safe dealRemuneration reports