Old versions of the API
Help
Sign up for YooMoney
Передача данных получателя выплаты для выписки из реестра
В ЮKassa вы можете делать выписки из реестра выплат. Например, для подтверждения факта успешной выплаты.
По умолчанию выписки содержат информацию о выплате: идентификатор выплаты (номер транзакции), сумма и валюта выплаты, дата и время проведения, способ получения выплаты и связанные с ним данные (например, номер телефона для выплаты через СБП).
С помощью API вы можете добавить в выписки дополнительную информацию — персональные данные получателя выплаты. Такие выписки понадобятся, например, для подтверждения факта выплаты в госорганах. Эта возможность доступна для любых видов выплат.
В этой статье описано, как передать эти данные при проведении выплаты, чтобы они попали в выписки.
Как это работает
Вам необходимо получить от пользователя его фамилию, имя, отчество и дату рождения и передать их в ЮKassa. В ответ ЮKassa вернет идентификатор персональных данных. Этот идентификатор нужно передать в запросе на проведение выплаты вместе с другими данными. Если вы делаете выплаты с универсальным токеном платежей и выплат, идентификатор персональных данных нужно передавать при каждой выплате с сохраненным способом оплаты.
При создании объекта выплаты ЮKassa сохранит персональные данные получателя. Срок жизни персональных данных — 5 лет с даты проведения последней выплаты с этими данными. Подробнее о сроке жизни персональных данных
Если выплата прошла успешно, данные получателя для этой выплаты будут сразу доступны в выписке из реестра выплат в личном кабинете. В выписках данные получателя содержатся в графе Дополнительная информация — вместе с описанием транзакции.
Общий сценарий проведения выплаты
Общий сценарий проведения выплат с передачей данных получателя для выписки
  1. Вы запрашиваете у пользователя его имя, фамилию, отчество и дату рождения.
  2. Пользователь сообщает вам свои персональные данные.
  3. Вы создаете объект персональных данных — отправляете ЮKassa POST-запрос с именем, отчеством, фамилией и датой рождения пользователя.
  4. ЮKassa возвращает вам объект персональных данных в статусе waiting_for_operation (данные получены и ожидают использования).
  5. Вы сохраняете идентификатор персональных данных.
  6. Вы запрашиваете у пользователя, каким способом он хочет провести выплату, и данные, необходимые для выплаты выбранным способом..
  7. Пользователь передает вам эти данные.
  8. Вы создаете выплату — отправляете ЮKassa POST-запрос с данными о выплате и с идентификатором персональных данных получателя выплаты.
  9. ЮKassa отправляет эквайеру распоряжение на перевод денег получателю выплаты.
  10. Эквайер обрабатывает запрос и сообщает результат выполнения операции.
  11. ЮKassa возвращает вам объект выплаты с финальным статусом — succeeded (выплата успешна) или canceled (выплата отменена).
Если в ответ на запрос ЮKassa вернула вам объект выплаты в статусе pending, это значит, что эквайер еще обрабатывает распоряжение на перевод. Чтобы узнать финальный статус выплаты, подождите, когда придет уведомление от ЮKassa, или запрашивайте информацию о выплате методом GET с возрастающим разумным интервалом (например, можно использовать последовательность Фибоначчи).
Получение идентификатора персональных данных
Шаг 1. Получите от пользователя его имя, фамилию, отчество и дату рождения.
Шаг 2. Создайте объект персональных данных : отправьте ЮKassa запрос с данными для аутентификации, ключом идемпотентности и следующими данными:
  • в параметре type передайте значение payout_statement_recipient (получатель выплаты для выписки из реестра);
  • в параметре last_name передайте фамилию получателя;
  • в параметре first_name передайте имя получателя;
  • в параметре middle_name передайте отчество получателя (если оно есть в паспорте);
  • в параметре birthdate передайте дату рождения получателя;
  • при необходимости в объекте metadata передайте дополнительные параметры.
Пример запроса на создание объекта персональных данных
cURL
PHP
Python
curl https://api.yookassa.ru/v3/personal_data \
  -X POST \
  -u <Идентификатор шлюза>: <Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "type": "payout_statement_recipient",
        "last_name": "Иванов",
        "first_name": "Иван",
        "middle_name": "Иванович",
        "birthdate": "2020-11-18",
        "metadata": {
          "recipient_id": "37"
        }
      }'
В ответ на запрос ЮKassa вернет созданный объект персональных данных  в статусе waiting_for_operation.
Пример созданного объекта персональных данных
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"
}
Шаг 3. Сохраните идентификатор объекта — он понадобится для проведения выплаты.

Идентификатор необходимо использовать в течение 24 часов с момента создания объекта персональных данных.

Проведение выплат
Процесс выплаты в зависимости от способа её получения описан в статьях:
В этой статье описан общий сценарий проведения выплаты с передачей данных получателя:
Получение данных для выплаты
Для проведения выплаты с передачей данных получателя:
  • Получите идентификатор персональных данных. Для этого запросите у пользователя его фамилию, имя, отчество и дату рождения и передайте эти данные в ЮKassa. В ответ ЮKassa вернет идентификатор сохраненнных данных.
  • Запросите у пользователя, каким способом он хочет провести выплату, и необходимые данные для выбранного способа.
Проведение выплаты с передачей данных получателя
Создайте выплату : передайте в запросе ЮKassa данные для аутентификации, ключ идемпотентности, данные о том, куда перевести выплату, и дополнительные данные для выписок — массив personal_data с идентификатором персональных данных id.
Если вы делаете выплаты с использованием универсального токена платежей и выплат, идентификатор персональных данных нужно передавать при каждой выплате.
Пример запроса на создание выплаты с передачей данных получателя (на примере СБП)
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payouts \
  -X POST \
  -u <Идентификатор шлюза>: <Секретный ключ> \
  -H '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": "Выплата по заказу № 37",
        "metadata": {
          "order_id": "37"
        }
      }'
В ответ на запрос ЮKassa вернет созданный объект выплаты .
Пример созданного объекта выплаты
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": "Выплата по заказу №37",
  "created_at": "2021-06-21T14:28:45.132Z",
  "metadata": {
    "order_id": "37"
  },
  "test": false
}
Если вы получили объект выплаты в статусе pending, дождитесь, когда статус изменится на succeeded или canceled. Для этого подождите, когда придет уведомление от ЮKassa, или запрашивайте информацию о выплате  с возрастающим разумным интервалом.
Пример запроса на получение информации о выплате
cURL
curl https://api.yookassa.ru/v3/payouts/{payout_id} \
    -X GET \
    -u <Идентификатор шлюза>:<Секретный ключ> \
Пример объекта выплаты в статусе succeeded
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": "Выплата по заказу №37",
    "created_at": "2021-06-21T14:28:45.132Z",
    "metadata": {
        "order_id": "37"
    },
    "test": false
}
Проведение выплаты с несколькими идентификаторами персональных данных

Только для тех, кто уже использует массив personal_data и передает идентификатор персональных данных. Например, в выплатах через СБП с проверкой получателя.

В массиве personal_data можно одновременно передать несколько идентификаторов, но только для объектов с разными типами данных. Если передать одинаковые типы (например, два идентификатора payout_statement_recipient), ЮKassa вернет ошибку.
Чтобы провести выплату с несколькими идентификаторами, нужно предварительно создать объекты персональных данных для каждого из них.
Пример для выплат через СБП с проверкой получателя и сохранением его персональных данных для выписки:
  1. Получите от пользователя его имя, фамилию, отчество и дату рождения.
  2. Создайте объект персональных данных для типа payout_statement_recipient и сохраните идентификатор, который вернет ЮKassa.
  3. Создайте объект персональных данных для типа sbp_payout_recipient и сохраните идентификатор, который вернет ЮKassa.
  4. В запросе на проведение выплаты передайте в массиве personal_data оба сохраненных идентификатора.
Пример запроса на создание выплаты с несколькими идентификаторами
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payouts \
  -X POST \
  -u <Идентификатор шлюза>: <Секретный ключ> \
  -H '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-5111-8111-18db351245c7"
          }
        ],
        "description": "Выплата по заказу № 37",
        "metadata": {
          "order_id": "37"
        }
      }'
Жизненный цикл персональных данных
Каждому этапу жизненного цикла соответствует статус объекта персональных данных : waiting_for_operation, active и canceled.
Когда вы создадите объект персональных данных, ЮKassa вернет его в статусе waiting_for_operation — переданные данные сохранены, но еще не были использованы для выплаты. Идентификатор объекта со статусом waiting_for_operation можно использовать при проведении выплат неограниченное количество раз, но только в течение 24 часов с момента создания объекта (время создания указано в параметре created_at).
Пример объекта персональных данных в статусе waiting_for_operation
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"
}
Если для проведения выплаты вы использовали объект персональных данных со статусом waiting_for_operation (создан объект выплаты), объект персональных данных перейдет в статус active — данные сохранены.
Срок жизни персональных данных — 5 лет. В течение этого срока персональные данные можно использовать при проведении выплат неограниченное количество раз. При каждом создании выплаты с этими персональными данными срок жизни автоматически продлевается (плюс 5 лет от даты создания выплаты).
Срок жизни персональных данных указан в параметре expires_at.
Пример объекта персональных данных в статусе active
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"
}
В статус canceled объект персональных данных переходит в следующих случаях:
  • Объект со статусом waiting_for_operation переходит в статус canceled, если в течение 24 часов с момента создания объекта не было ни одной выплаты с идентификатором этого объекта (объект не перешел в статус active).
  • Объект со статусом active переходит в статус canceled, если истек срок жизни объекта, указанный в параметре expires_at.
Объект в статусе canceled содержит объект cancellation_details с причиной отмены expired_by_timeout. Статус canceled финальный и неизменяемый. Персональные данные с этим статусом нельзя использовать при проведении выплат.
Пример объекта персональных данных в статусе canceled
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"
  }
}
Чтобы узнать статус объекта, отправьте ЮKassa запрос на получение информации о персональных данных  и передайте в нём идентификатор персональных данных.
Пример запроса на получение информации о персональных данных
cURL
PHP
Python
curl https://api.yookassa.ru/v3/personal_data/{personal_data_id} \
    -X GET \
    -u <Идентификатор шлюза>:<Секретный ключ> \
Что почитать еще
Выписки из реестра выплат