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