Safe deal: payouts to sellers — Payment acceptance via the YooMoney API

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 payout	One-time limit	Limit 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:

Get the information from the seller on where their remuneration should be credited to.
Process the payout using the information you received.

The procedure depends on the type of payout:

Payouts to bank card
Payouts to YooMoney wallet

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:

Using the YooMoney widget for collecting banking details
On your own

Payouts when banking details are obtained using the YooMoney widget

To make a payout to a bank card:

Obtain the bank card details using the special YooMoney widget.
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:

Parameter	Type	Description
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:

Obtain the bank card details.
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:

Obtain the banking details of the YooMoney wallet.
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.

Value	Description
yoo_money	YooMoney
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.

Value	Description
fraud_suspected	Payout 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_decline	No specific reason provided. User will have to contact the cancellation initiator for more details
identification_required	This YooMoney wallet is not identified. Adding money to anonymous wallets is forbidden. The user needs to complete identification
one_time_limit_exceeded	Exceeded 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_exceeded	Exceeded 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_payee	Issuer 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).