API ЮKassa
Инструкции
Старые версии API
Помощь
Подключить ЮKassa
Справочник
API ЮKassa: Инструкции
API ЮKassa: Справочник
Старые версии API
Помощь

|

Подключить ЮKassa
English
Проверка получателя выплаты
С помощью ЮKassa при проведении выплаты через СБП вы можете проверить, что пользователь, которому вы собираетесь перевести деньги, и владелец счета, к которому привязан телефон, — это один и тот же человек.
Как это работает
Вам необходимо получить от пользователя его фамилию, имя и отчество, затем передать их в ЮKassa и получить идентификатор персональных данных. Этот идентификатор нужно будет передать в запросе на проведение выплаты вместе с другими данными.
При проведении выплаты ЮKassa сначала передаст Национальной системе платежных карт (НСПК) номер телефона и идентификатор участника СБП и запросит информацию о владельце счета. НСПК вернет персональные данные. ЮKassa сравнит эти данные с теми, которые передали вы. Если данные совпадут, ЮKassa отправит распоряжение на перевод денег. Если не совпадут, ЮKassa отменит выплату, указав причину recipient_check_failed.
Общий сценарий проведения выплаты
Общий сценарий проведения выплат с проверкой получателя
  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. Сохраните идентификатор объекта — он понадобится для проведения выплаты.
Проведение выплат
Общий процесс проведения выплат через СБП описан в статье Выплаты через СБП. В этой статье описаны только особенности выплат с проверкой получателя:
Получение данных для выплаты
Для проведения выплаты через СБП с проверкой получателя:
  • Получите идентификатор персональных данных: запросите у пользователя его фамилию, имя и отчество, сохраните эти данные в Ю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
Юридические документы
Правила работы сервиса ЮKassaСоглашение об ЭДО
Вы не разработчик?
Модули для CMSВыставление счетовПлатежи для лендингов
8 800 250-66-99
Задать вопросПомощь
© 2023, ООО НКО «ЮМани»