For users of the Mass payout protocol
Only for those who're using a YooMoney Mass payout protocol
The YooMoney API differs from the Mass payout protocol in terms of its features and interaction format. This article describes the key differences that may be important when you set up the integration.
Benefits of the YooMoney API
- The API supports some features that aren't available in the Mass payout protocol. These include payouts via FPS, customization of the form to receive bank card details, multipurpose token for payments and payouts, and others.
- All YooMoney's API payment solutions have the same interaction format. If you want to accept payments via the YooMoney API or use other payment solutions, you'll only need to sign a contract and enable new features following our instructions.
- New features will only be available in the YooMoney API.
Differences between the YooMoney API and the Mass payout protocol
Interaction format
- Uses HTTP Basic Auth instead of a certificate to authenticate requests. The username is used as the ID of your payout gateway for this API, and a special secret key is used as the password. More about request authentication
- The interaction format is different. For example:
- request authentication details and the idempotency key are sent in the request header rather than in its body;
- details is sent in JSON format;
- the updated object is returned in response to the request;
- you can check the transaction status in the object's status;
- you can enable notifications to be aware of changes in the object's status.
- The payout object keeps all transaction details: amount and type of the payout, its status, your payout description, the reason for canceling the payout (if something went wrong), and any additional details you sent in the request (for example, the recipient's ID in your system).
- The payout object includes information about the mode in which this object was created: during testing or when the actual payout was made.
Payout types
Payouts can be made to bank cards, YooMoney wallets, and via FPS to accounts of banks and payment services. More about types and limits of payouts
Getting details for payouts to a bank card
Making payouts to a bank card requires fewer details. Only card details are needed: you don't have to get the recipient's personal data and their consent to the YooMoney offer.
The details required to make payouts can be obtained in two ways:
- If you don't have a PCI DSS compliance certificate, you need to use a dedicated YooMoney widget to recieve bank card details and exchange them for a card synonym. It needs to be embedded on your website page (if you use the old protocol, you need to redirect the user to the YooMoney page to collect the details). In the data collection form, you can customize the colors of interface elements and a text language (Russian or English).
- If you have a PCI DSS compliance certificate, you can collect bank card details independently and send them in a request without obtaining a card synonym.
Payouts to the self-employed
If you're going to make payouts to self-employed individuals, you need to get the user's TIN or phone number so that YooMoney gets the permission to record receipts. After that, you need to make a request via API using these details. Then redirect the user to the Moi nalog service via the link that will be returned by YooMoney, and wait for the self-employed individual to grant the rights to YooMoney. You can use the YooMoney API to check if the rights have been granted. More about payouts to the self-employed
Payout recipient verification
When you make payouts via FPS, you can additionally verify the recipient. If the specified recipient doesn't match the person who will actually get the money, YooMoney will cancel the payout. More about payouts with the recipient verification
Multipurpose token for payments and payouts
If you both accept payments and make payouts, you can create a multipurpose token with bank card details for the user. It can be used to make payments as well as payouts. More about a multipurpose token
Payout balance
To check the payout balance via API, you need to send a separate request for information about your gateway or view the balance status in your Merchant Profile. How to check the payout balance via API
Payout reports
For reconciliation, you can use reports on successful payouts sent by YooMoney. The reports come in the CSV format. This format is different from those used in the old protocol. More about reports
Sending the recipient's data for the purpose of making extracts from reports
With YooMoney, you can make extracts from the payout report that contain the recipient's data. Such extracts may be required to confirm that a payout was made when it's needed for government agencies.
To do this, you need to save the recipient's personal data in YooMoney, and then submit the saved information ID in the payout request. If the payout was successful, the recipient's data will be immediately available in the extract from the report in your Merchant Profile. More about sending the recipient's data for the purpose of making extracts from reports
See also