Sending the payout recipient's information for the purpose of making extracts from reports

In YooMoney, you can obtain extracts from the payout report, for example, to confirm the fact of a successful payout.

By default, extracts contain information about the payout, such as payout ID (transaction number), amount and currency of the payout, date and time of the processing, method of receiving the payout as well as the corresponding data (for example, phone number for a payout via the FPS).

Using the API, you can add personal information of the payout recipient to the extracts. Such extracts may be useful, for example, when some state agency requests you to confirm the fact that the payout was made. This option is available for all types of payouts.

This article describes how to specify this information when making a payout so that it does end up in the extracts.

How it works

You need to get the customer's first name, last name, patronymic (if they have one), date of birth, and provide these details to YooMoney. In response, YooMoney will return the personal data ID. This ID must be specified in the request for making a payout alongside other information. If you make payouts with a multipurpose token for payments and payouts, the personal data ID must be specified during every payout with the saved payment method.

When creating the payout object, YooMoney will save the recipient's personal information. The lifespan of a set of personal data is 5 years following the last payout made using this information. More about the lifespan of personal data

If a payout was successful, the recipient's details for it will be immediately available in the extract from the report on payouts in the Merchant Profile. In the extracts, the recipient's details are contained in the Additional information field, along with the transaction description.

General scenario of making a payout

General scenario of making a payout with the transmission of recipient's details for an extract

You request the user's first and last name, patronymic (if available), and the date of birth.
The user provides their personal information to you.
You create the personal information object by sending the POST request containing the user's first and last name, patronymic (if available), and the date of birth to YooMoney.
YooMoney returns the personal information object with the waiting_for_operation status (details have been received and are waiting to be processed).
You save the personal information ID.
You ask the user about the method through which they want to make the payout as well as the information required to make a payout via the selected method.
The user provides this information to you.
You create a payout by sending a POST request with the information about the payout and the payout recipient's personal data ID to YooMoney.
YooMoney sends the order to the acquirer for the transfer of money to the payout recipient.
Acquirer processes the request and informs about the results of the transaction.
YooMoney returns the payout object with the final status, either succeeded or canceled.

If in response to the request YooMoney returns the payout object with the pending status, it means that the acquirer is still processing the payout order. To find out the final status of the payout, wait until you get the notification form YooMoney, or make periodic requests about the payout via the GET method with an increasing periodic interval (for example, you can use the Fibonacci sequence).

Obtaining the personal data ID

Step 1. Request the user's first and last name, patronymic (if available), and the date of birth.

Step 2. Create the personal data object by sending a request to YooMoney containing the data for authentication, idempotency key, as well as the following information:

specify the payout_statement_recipient value in the type parameter (payout recipient for the extract from the report);
specify the recipient's last name in the last_name parameter;
specify the recipient's first name in the first_name parameter;
specify the recipient patronymic (if it's specified in their passport) in the middle_name parameter;
specify the recipient's date of birth in the birthdate parameter;
if necessary, specify additional parameters in the metadata object.

Example of a request for creating a personal data ID

cURL
PHP
Python
curl https://api.yookassa.ru/v3/personal_data \
  -X POST \
  -u <Gateway ID>: <Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "type": "payout_statement_recipient",
        "last_name": "Ivanov",
        "first_name": "Ivan",
        "middle_name": "Ivanovich",
        "birthdate": "2020-11-18",
        "metadata": {
          "recipient_id": "37"
        }
      }'

In response to the request, YooMoney will return the personal data object with the waiting_for_operation status.

Example of a created personal data object

JSON
{
  "id": "pd-22e12f66-000f-5000-8000-18db351245c7",
  "status": "waiting_for_operation",
  "created_at": "2023-09-15T07:28:39.390513Z",
  "metadata": {
    "recipient_id": "37"
  },
  "type": "payout_statement_recipient"
}

Step 3. Save the object ID: you will need it to make the payout.

The ID must be used within 24 hours from the moment of creation of the personal data object.

Making payouts

The process of making a payout is described in several articles, depending on the method of reception:

Payout from a card using the widget and manual collection of card details
Payouts via FPS without and with recipient verification
Payouts to YooMoney wallets
Payouts to the self-employed
Payouts with the use of a saved payment method

This article describes the general scenario of making a payout with the recipient's data being specified:

What information must be obtained from the user
How to make a payout with the recipient's data being specified
How to make a payout with several personal data IDs

Obtaining information for a payout

In order to make a payout with the recipient's data being specified:

Obtain the personal data ID. Request the user's first and last name, patronymic (if available), and the date of birth, and send this information to YooMoney. In response, YooMoney will return the saved data ID.
Ask the user about the method through which they want to make the payout as well as the information required for the selected method.

Making a payout with the recipient's data being specified

Create a payout : in the request to YooMoney specify the data for authentication, idempotency key, information on where to make the payout, as well additional data for the extracts in the personal_data array with the personal data ID in id.

If you make payouts using the multipurpose token for payments and payouts, the personal data ID must be specified during every payout.

Example of a request for making a payout with the recipient's data being specified (using FPS as an example)

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": "sbp",
            "phone": "79000000000",
            "bank_id": "100000000111"
        },
        "personal_data": [
          {
            "id": "pd-22e12f66-000f-5000-8000-18db351245c7"
          }
        ],
        "description": "Payout for order No. 37",
        "metadata": {
          "order_id": "37"
        }
      }'

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": "2.00",
    "currency": "RUB"
  },
  "status": "pending",
  "payout_destination": {
    "type": "sbp",
    "phone": "79000000000",
    "bank_id": "100000000111",
    "recipient_checked": false
  },
  "description": "Payout for order No. 37",
  "created_at": "2021-06-21T14: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 payment object in the succeeded status

JSON
{
    "id": "po-285ec15d-0003-5000-a000-08d1bec7dade",
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "status": "succeeded",
    "payout_destination": {
      "type": "sbp",
      "phone": "79000000000",
      "bank_id": "100000000111",
      "recipient_checked": false
    },
    "description": "Payout for order No. 37",
    "created_at": "2021-06-21T14:28:45.132Z",
    "metadata": {
        "order_id": "37"
    },
    "test": false
}

Making a payout with several personal data IDs

Only for those who already use the personal_data array and specify the personal data ID. For example, in payouts via the FPS with recipient verification.

In the personal_data array, you can send several IDs at the same time, but only for object with different data types. If you specify similar types (for example, two payout_statement_recipient IDs), YooMoney will return an error.

To make a payout with several IDs, first you need to create personal data objects for each of them.

Example for payouts made via FPS with recipient verification and saving the recipient's personal data for an extract:

Request the user's first and last name, patronymic (if available), and the date of birth.
Create a personal data object for the payout_statement_recipient type and save the ID that will be returned by YooMoney.
Create a personal data object for the sbp_payout_recipient type and save the ID that will be returned by YooMoney.
Specify both of the saved IDs in the personal_data array of the request for making a payout.

Example of a request for making a payout with several IDs

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": "sbp",
            "phone": "79000000000",
            "bank_id": "100000000111"
        },
        "personal_data": [
          {
            "id": "pd-22e12f66-000f-5000-8000-18db351245c7",
            "id": "pd-22e12f66-000f-51111-81111- 18db351245c7"
          }
        ],
        "description": "Payout for order No. 37",
        "metadata": {
          "order_id": "37"
        }
      }'

Lifecycle of personal data

Each stage of the lifecycle has a corresponding status of the personal data object : waiting_for_operation, active, and canceled.

When you create a personal data object, YooMoney will return it with the waiting_for_operation status: the specified data has been saved but not yet used for a payout. The object ID with the waiting_for_operation status can be used for payouts for an unlimited number of time but only within 24 hours since the moment of creation of the object (the time of creation is specified in the created_at parameter).

Example of a personal data object with the waiting_for_operation status

JSON
{
  "id": "pd-22e12f66-000f-5000-8000-18db351245c7",
  "status": "waiting_for_operation",
  "created_at": "2023-09-15T07:28:39.390513Z",
  "metadata": {
    "recipient_id": "37"
  },
  "type": "payout_statement_recipient"
}

If you used the personal data object with the waiting_for_operation status (payout object created) to make a payout, the personal data object's status will be changed to active, meaning the data has been saved.

The lifecycle of personal data is 5 years. Within this period, the personal data must be used for making payouts for an unlimited number of times. The lifecycle gets extended every time this personal data is used for creating a payout (plus 5 years from the date when the payout is created).

The personal data expiration date is specified in the expires_at parameter.

Example of a personal data object with the active status

JSON
{
  "id": "pd-22e12f66-000f-5000-8000-18db351245c7",
  "status": "active",
  "created_at": "2023-09-15T07:28:39.390513Z",
  "expires_at": "2028-09-15T07:28:39.390513Z",
  "metadata": {
    "recipient_id": "37"
  },
  "type": "payout_statement_recipient"
}

The personal data object's status changes to canceled in the following cases:

The status of the object changes from waiting_for_operation to canceled if there wasn't a single payout with this object's ID made within 24 hours from the moment of creation of this object (i.e. the object's status wasn't changed to active).
The object's status changes from active to canceled if the object has expired (the expiration date is specified in the expires_at parameter).

The object with the canceled status contains the cancellation_details object with the cancellation reason expired_by_timeout. The canceled status is final and unchangeable. The personal data with this status must not be used for making payouts.

Example of a personal data object with the canceled status

JSON
{
  "id": "pd-22e12f66-000f-5000-8000-18db351245c7",
  "status": "canceled",
  "created_at": "2023-09-15T07:28:39.390513Z",
  "metadata": {
    "recipient_id": "37"
  },
  "type": "payout_statement_recipient",
  "cancellation_details": {
    "party": "yoo_money",
    "reason": "expired_by_timeout"
  }
}

To find out an object's status, send a request for obtaining information about the personal data to YooMoney and specify the personal data ID in it.

Example of a request for obtaining information about personal data

cURL
PHP
Python
curl https://api.yookassa.ru/v3/personal_data/{personal_data_id} \
    -X GET \
    -u <Gateway ID>:<Secret Key> \