Передача данных получателя выплаты для выписки из реестра

В ЮKassa вы можете делать выписки из реестра выплат. Например, для подтверждения факта успешной выплаты.

По умолчанию выписки содержат информацию о выплате: идентификатор выплаты (номер транзакции), сумма и валюта выплаты, дата и время проведения, способ получения выплаты и связанные с ним данные (например, номер телефона для выплаты через СБП).

С помощью API вы можете добавить в выписки дополнительную информацию — персональные данные получателя выплаты. Такие выписки понадобятся, например, для подтверждения факта выплаты в госорганах. Эта возможность доступна для любых видов выплат.

В этой статье описано, как передать эти данные при проведении выплаты, чтобы они попали в выписки.

Как это работает

Вам необходимо получить от пользователя его фамилию, имя, отчество и дату рождения и передать их в ЮKassa. В ответ ЮKassa вернет идентификатор персональных данных. Этот идентификатор нужно передать в запросе на проведение выплаты вместе с другими данными. Если вы делаете выплаты с универсальным токеном платежей и выплат, идентификатор персональных данных нужно передавать при каждой выплате с сохраненным способом оплаты.

При создании объекта выплаты ЮKassa сохранит персональные данные получателя. Срок жизни персональных данных — 5 лет с даты проведения последней выплаты с этими данными. Подробнее о сроке жизни персональных данных

Если выплата прошла успешно, данные получателя для этой выплаты будут сразу доступны в выписке из реестра выплат в личном кабинете. В выписках данные получателя содержатся в графе Дополнительная информация — вместе с описанием транзакции.

Общий сценарий проведения выплаты

Общий сценарий проведения выплат с передачей данных получателя для выписки

Вы запрашиваете у пользователя его имя, фамилию, отчество и дату рождения.
Пользователь сообщает вам свои персональные данные.
Вы создаете объект персональных данных — отправляете ЮKassa POST-запрос с именем, отчеством, фамилией и датой рождения пользователя.
ЮKassa возвращает вам объект персональных данных в статусе waiting_for_operation (данные получены и ожидают использования).
Вы сохраняете идентификатор персональных данных.
Вы запрашиваете у пользователя, каким способом он хочет провести выплату, и данные, необходимые для выплаты выбранным способом..
Пользователь передает вам эти данные.
Вы создаете выплату — отправляете ЮKassa POST-запрос с данными о выплате и с идентификатором персональных данных получателя выплаты.
ЮKassa отправляет эквайеру распоряжение на перевод денег получателю выплаты.
Эквайер обрабатывает запрос и сообщает результат выполнения операции.
Ю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 часов с момента создания объекта персональных данных.

Проведение выплат

Процесс выплаты в зависимости от способа её получения описан в статьях:

Выплаты на карты с использованием виджета и самостоятельным получением данных карты
Выплаты через СБП без проверки получателя и с проверкой
Выплаты на кошельки ЮMoney
Выплаты самозанятым
Выплаты с использованием сохраненного способа оплаты

В этой статье описан общий сценарий проведения выплаты с передачей данных получателя:

Какие данные нужно получить от пользователя
Как провести выплату с передачей данных получателя
Как провести выплату с несколькими идентификаторами персональных данных

Получение данных для выплаты

Для проведения выплаты с передачей данных получателя:

Получите идентификатор персональных данных. Для этого запросите у пользователя его фамилию, имя, отчество и дату рождения и передайте эти данные в Ю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": "800.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 вернет ошибку.

Чтобы провести выплату с несколькими идентификаторами, нужно предварительно создать объекты персональных данных для каждого из них.

Пример для выплат через СБП с проверкой получателя и сохранением его персональных данных для выписки:

Получите от пользователя его имя, фамилию, отчество и дату рождения.
Создайте объект персональных данных для типа payout_statement_recipient и сохраните идентификатор, который вернет ЮKassa.
Создайте объект персональных данных для типа sbp_payout_recipient и сохраните идентификатор, который вернет ЮKassa.
В запросе на проведение выплаты передайте в массиве 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 <Идентификатор шлюза>:<Секретный ключ> \

Что почитать еще