Docs
Инструкции
Помощь
Подключить ЮKassa
Проверка получателя выплаты
Только для выплат через СБП
С помощью ЮKassa при проведении выплаты через СБП вы можете проверить, что пользователь, которому вы собираетесь перевести деньги, и владелец счета, к которому привязан телефон, — это один и тот же человек.
Как это работает
Вам необходимо получить от пользователя его фамилию, имя и отчество, затем передать их в ЮKassa и получить идентификатор персональных данных. Этот идентификатор нужно будет передать в запросе на проведение выплаты вместе с другими данными.
При проведении выплаты ЮKassa сначала передаст Национальной системе платежных карт (НСПК) номер телефона и идентификатор участника СБП и запросит информацию о владельце счета. НСПК вернет персональные данные. ЮKassa сравнит эти данные с теми, которые передали вы. Если данные совпадут, ЮKassa отправит распоряжение на перевод денег. Если не совпадут, ЮKassa отменит выплату, указав причину
recipient_check_failed
.
Если хотите делать выплаты с проверкой получателя, сообщите об этом вашему менеджеру ЮKassa.
Общий сценарий проведения выплаты
Общий сценарий проведения выплат с проверкой получателя
  1. Вы запрашиваете у пользователя его имя, фамилию и отчество.
  2. Пользователь сообщает вам свои персональные данные.
  3. Вы создаете объект персональных данных — отправляете ЮKassa POST-запрос с именем, отчеством и фамилией пользователя.
  4. ЮKassa возвращает вам объект персональных данных в статусе
    waiting_for_operation
    (данные получены и ожидают использования).
  5. Вы сохраняете идентификатор персональных данных.
  6. Вы запрашиваете у пользователя другие данные, необходимые для выплаты.
  7. Пользователь передает вам эти данные.
  8. Вы создаете выплату — отправляете ЮKassa POST-запрос с данными о выплате и с идентификатором персональных данных получателя выплаты.
  9. ЮKassa запрашивает в НСПК информацию о владельце счета.
  10. НСПК возвращает запрошенные данные.
  11. ЮKassa сравнивает данные о получателе выплаты с данными владельца счета.
  12. Если данные совпадают, ЮKassa отправляет эквайеру распоряжение на перевод денег получателю выплаты.
  13. Эквайер обрабатывает запрос и сообщает результат выполнения операции.
  14. ЮKassa возвращает вам объект выплаты с финальным статусом —
    succeeded
    (выплата успешна) или 
    canceled
    (выплата отменена).
Если в ответ на запрос ЮKassa вернула вам объект выплаты в статусе
pending
, это значит, что эквайер еще обрабатывает распоряжение на перевод. Чтобы узнать финальный статус, повторяйте запрос на проведение выплаты с тем же ключом идемпотентности или запрашивайте информацию о выплате методом GET с возрастающим разумным интервалом (например, можно использовать последовательность Фибоначчи).
Получение идентификатора персональных данных
Шаг 1. Получите от пользователя его имя, фамилию и отчество.
Шаг 2. Создайте объект персональных данных : отправьте ЮKassa запрос с данными для аутентификации запроса, ключом идемпотентности и следующими данными:
  • в параметре
    type
    передайте значение
    sbp_payout_recipient
    (проверка получателя при выплатах через СБП);
  • в параметре
    last_name
    передайте фамилию получателя;
  • в параметре
    first_name
    передайте имя получателя;
  • в параметре
    middle_name
    передайте отчество получателя (если оно есть в паспорте);
  • при необходимости в объекте
    metadata
    передайте дополнительные параметры.
Пример запроса на создание объекта персональных данных
cURL
curl https://api.yookassa.ru/v3/personal_data \
  -X POST \
  -u <Идентификатор шлюза>: <Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "type": "sbp_payout_recipient",
        "last_name": "Иванов",
        "first_name": "Иван",
        "middle_name": "Иванович",
        "metadata": {
          "recipient_id": "37"
        }
      }'
В ответ на запрос ЮKassa вернет созданный объект персональных данных  в статусе
waiting_for_operation
.
Пример созданного объекта персональных данных
JSON
{
  "id": "pd-22e12f66-000f-5000-8000-18db351245c7",
  "status": "waiting_for_operation",
  "created_at": "2022-09-15T07:28:39.390513Z",
  "metadata": {
    "recipient_id": "37"
  },
  "type": "sbp_payout_recipient"
}
Шаг 3. Сохраните идентификатор объекта — он понадобится для проведения выплаты.
Идентификатор необходимо использовать в течение 24 часов с момента создания объекта персональных данных.
Проведение выплат
Общий процесс проведения выплат через СБП описан в статье Выплаты через СБП. В этой статье описаны только особенности выплат с проверкой получателя:
Получение данных для выплаты
Для проведения выплаты через СБП с проверкой получателя:
  • Получите идентификатор персональных данных: запросите у пользователя его фамилию, имя и отчество, сохраните эти данные в ЮKassa и получите идентификатор персональных данных.
  • Получите данные, которые нужны для выплаты через СБП без проверки получателя: номер телефона и идентификатор участника СБП. При получении данных сообщите пользователю, что ему нужно выбрать тот счет, который принадлежит ему, иначе выплата не пройдет.
Проведение выплаты с проверкой получателя
При проведении выплаты в запросе к ЮKassa передайте данные для выплаты через СБП и объект
personal_data
с идентификатором персональных данных.
Пример запроса на создание выплаты
cURL
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 вернет созданный объект выплаты . Он будет содержать параметр
recipient_checked
со значением
true
. Это значит, что выплата проходит с проверкой получателя.
Пример созданного объекта выплаты
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": true
  },
  "description": "Выплата по заказу №37",
  "created_at": "2021-06-21T14:28:45.132Z",
  "metadata": {
    "order_id": "37"
  },
  "test": false
}
Если вы получили объект выплаты в статусе
pending
, дождитесь, когда статус изменится на 
succeeded
или 
canceled
.
Обработка результата проведения выплаты
Чтобы узнать результат проверки получателя, вам нужно проанализировать объект выплаты:
Выплата в статусе succeeded
Если выплата перешла в статус
succeeded
, это значит, что получатель успешно прошел проверку, деньги перевели.
Пример объекта выплаты в статусе 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": true
    },
    "description": "Выплата по заказу №37",
    "created_at": "2021-06-21T14:28:45.132Z",
    "metadata": {
        "order_id": "37"
    },
    "test": false
}
Выплата в статусе canceled с причиной отмены recipient_check_failed
Если выплата перешла в статус
canceled
с причиной отмены
recipient_check_failed
, это значит, что получатель выплаты не совпал с владельцем платежного средства.
Пример объекта выплаты, если проверка получателя неуспешна
JSON
{
    "id": "po-285ec15d-0003-5000-a000-08d1bec7dade",
    "amount": {
        "value": "2.00",
        "currency": "RUB"
    },
    "status": "canceled",
    "payout_destination": {
      "type": "sbp",
      "phone": "79000000000",
      "bank_id": "100000000111",
      "recipient_checked": true
    },
    "description": "Выплата по заказу №37",
    "created_at": "2021-06-21T14:28:45.132Z",
    "metadata": {
        "order_id": "37"
    },
    "test": false,
    "cancellation_details": {
        "party": "yoo_money",
        "reason": "recipient_check_failed"
    }
}
Проверьте корректность персональных данных, которые вы передали ЮKassa: данные указаны, как в паспорте, нет опечаток, данные переданы в нужных параметрах:
  • Если с персональными данными что-то не так, создайте новый объект персональных данных с корректными данными. Повторите выплату с новым идентификатором персональных данных и новым ключом идемпотентности.
  • Если с персональными данными всё хорошо, сообщите пользователю, что для проведения выплаты нужен счет, который открыт на него. Повторите выплату с новыми данными для выплаты и новым ключом идемпотентности. Если повторную выплату делаете в течение 24 часов после создания объекта персональных данных (объект персональных данных в статусе
    waiting_for_operation
    ), то можно использовать тот же идентификатор персональных данных.
Выплата в статусе canceled с другими причинами отмены
Если выплата перешла в статус
canceled
с другой причиной отмены (не
recipient_check_failed
), это значит, что получатель выплаты успешно прошел проверку, но при проведении самой выплаты что-то пошло не так. Ваши дальнейшие действия зависят от причины отмены выплаты.
Жизненный цикл персональных данных
Жизненный цикл персональных данных зависит от того, как вы эти данные используете. Каждому этапу жизненного цикла соответствует статус объекта персональных данных :
waiting_for_operation
,
active
и 
canceled
.
Когда вы создадите объект персональных данных, он вернется в статусе
waiting_for_operation
. Это значит, что переданные персональные данные сохранены, но еще не было успешных выплат с этими данными. Идентификатор объекта с таким статусом можно использовать при проведении выплат неограниченное количество раз, но только в течение 24 часов с момента создания объекта (время создания указано в параметре
created_at
).
Пример объекта персональных данных в статусе waiting_for_operation
JSON
{
  "id": "pd-22e12f66-000f-5000-8000-18db351245c7",
  "status": "waiting_for_operation",
  "created_at": "2022-09-15T07:28:39.390513Z",
  "metadata": {
    "recipient_id": "37"
  },
  "type": "sbp_payout_recipient"
}
Если вы использовали объект персональных данных со статусом
waiting_for_operation
при проведении выплаты с проверкой получателя и выплата прошла успешно, объект персональных данных перейдет в статус
active
 — данные проверены и сохранены на 24 часа. В течение этого срока персональные данные можно использовать при проведении выплат неограниченное количество раз. Срок жизни персональных данных указан в параметре
expires_at
.
Пример объекта персональных данных в статусе active
JSON
{
  "id": "pd-22e12f66-000f-5000-8000-18db351245c7",
  "status": "active",
  "created_at": "2022-09-15T07:28:39.390513Z",
  "expires_at": "2022-09-16T07:28:39.390513Z",
  "metadata": {
    "recipient_id": "37"
  },
  "type": "sbp_payout_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": "2022-09-15T07:28:39.390513Z",
  "metadata": {
    "recipient_id": "37"
  },
  "type": "sbp_payout_recipient",
  "cancellation_details": {
    "party": "yoo_money",
    "reason": "expired_by_timeout"
  }
}
Чтобы узнать статус объекта, отправьте ЮKassa запрос на получение информации о персональных данных  и передайте в нём идентификатор персональных данных.
Пример запроса на получение информации о персональных данных
cURL
curl https://api.yookassa.ru/v3/personal_data/{personal_data_id} \
    -X GET \
    -u <Идентификатор шлюза>:<Секретный ключ> \
Что почитать еще
Выплаты через СБПТестирование выплатНеуспешные выплатыКоды ответа (состояния) HTTP