Проверка получателя выплаты

С помощью ЮKassa при проведении выплаты через СБП вы можете проверить, что пользователь, которому вы собираетесь перевести деньги, и владелец счета, к которому привязан телефон, — это один и тот же человек.

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

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

При проведении выплаты ЮKassa сначала передаст Национальной системе платежных карт (НСПК) номер телефона и идентификатор участника СБП и запросит информацию о владельце счета. НСПК вернет персональные данные. ЮKassa сравнит эти данные с теми, которые передали вы. Если данные совпадут, ЮKassa отправит распоряжение на перевод денег. Если не совпадут, ЮKassa отменит выплату, указав причину recipient_check_failed.

Если хотите делать выплаты с проверкой получателя, сообщите об этом вашему менеджеру ЮKassa.

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

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

Вы запрашиваете у пользователя его имя, фамилию и отчество.
Пользователь сообщает вам свои персональные данные.
Вы создаете объект персональных данных — отправляете ЮKassa POST-запрос с именем, отчеством и фамилией пользователя.
ЮKassa возвращает вам объект персональных данных в статусе waiting_for_operation (данные получены и ожидают использования).
Вы сохраняете идентификатор персональных данных.
Вы запрашиваете у пользователя другие данные, необходимые для выплаты.
Пользователь передает вам эти данные.
Вы создаете выплату — отправляете ЮKassa POST-запрос с данными о выплате и с идентификатором персональных данных получателя выплаты.
ЮKassa запрашивает в НСПК информацию о владельце счета.
НСПК возвращает запрошенные данные.
ЮKassa сравнивает данные о получателе выплаты с данными владельца счета.
Если данные совпадают, ЮKassa отправляет эквайеру распоряжение на перевод денег получателю выплаты.
Эквайер обрабатывает запрос и сообщает результат выполнения операции.
YooMoney returns the payout object with the final status, which is either succeeded (payout successful) or canceled (payout canceled).

Если в ответ на запрос ЮKassa вернула вам объект выплаты в статусе pending, это значит, что эквайер еще обрабатывает распоряжение на перевод. To find out the final status of the payout, wait for the YooMoney notification or request payout information using the GET method with increasing reasonable intervals (for example, you can use the Fibonacci sequence).

Получение идентификатора персональных данных

Шаг 1. Получите от пользователя его имя, фамилию и отчество.

Шаг 2. Создайте объект персональных данных : отправьте ЮKassa запрос с данными для аутентификации запроса, ключом идемпотентности и следующими данными:

в параметре type передайте значение sbp_payout_recipient (проверка получателя при выплатах через СБП);
в параметре last_name передайте фамилию получателя;
в параметре first_name передайте имя получателя;
в параметре middle_name передайте отчество получателя (если оно есть в паспорте);
при необходимости в объекте metadata передайте дополнительные параметры.

Пример запроса на создание объекта персональных данных

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": "sbp_payout_recipient",
        "last_name": "Ivanov",
        "first_name": "Ivan",
        "middle_name": "Ivanovich",
        "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 <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"
        }
      }'

В ответ на запрос Ю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": "Payout for order No. 37",
  "created_at": "2021-06-21T14:28:45.132Z",
  "metadata": {
    "order_id": "37"
  },
  "test": false
}

Если вы получили объект выплаты в статусе pending, дождитесь, когда статус изменится на succeeded или canceled. Wait for the YooMoney notification or request payout information with an increasing reasonable interval.

Обработка результата проведения выплаты

Чтобы узнать результат проверки получателя, вам нужно проанализировать объект выплаты:

Выплата в статусе succeeded
Выплата в статусе canceled с причиной отмены recipient_check_failed
Выплата в статусе 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": "Payout for order No. 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": "Payout for order No. 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
PHP
Python
curl https://api.yookassa.ru/v3/personal_data/{personal_data_id} \
    -X GET \
    -u <Gateway ID>:<Secret Key> \