API ЮKassa
Помощь
Подключить ЮKassa
Форма для сбора данных
Для перевода денег на банковскую карту необходимо собрать персональные данные пользователя и данные банковской карты. Это можно сделать самостоятельно или с помощью специальной формы ЮKassa.
Если использовать форму, ЮKassa будет хранить необходимые данные на своей стороне. Вы получите синоним банковской карты и идентификатор пользователя в ЮKassa — это обезличенные данные, публикация которых не несет имиджевых или финансовых рисков. С помощью полученных данных вы сможете проводить выплаты на карту без проверки паспортных данных.
ЮKassa будет проверять персональные данные только при получении идентификатора пользователя. Срок действия идентификатора один год. Для дальнейших выплат на карту пользователя персональные данные нужно собирать заново.
Сценарий взаимодействия
Шаг 1. Пользователь в вашей системе инициирует выплату на свою банковскую карту.
Шаг 2. Вы перенаправляете пользователя на форму для сбора данных банковской карты.
Шаг 3. Пользователь вводит данные карты и нажимает Дальше.
Форма ввода данных банковской карты
Шаг 4. Переходит на форму для ввода паспортных данных, заполняет все поля и нажимает На проверку.
Форма ввода персональных данных пользователя (полный набор полей)
Шаг 5. ЮKassa отображает пользователю ИНН, соответствующий этим данным, и просит пользователя подтвердить, что ИНН принадлежит ему.
Форма подтверждения ИНН
Когда пользователь нажимает Подтверждаю, ЮKassa отправляет вам параметры для проведения выплаты (синоним банковской карты и идентификатор пользователя) и перенаправляет пользователя на страницу успеха.
Если с данными что-то не так или по ним не получилось найти ИНН, ЮKassa просит пользователя еще раз проверить введенные данные и поправить их при необходимости.
Форма проверки введенных данных
Если пользователь что-то меняет в своих данных, ЮKassa заново запускает проверку. Если пользователь ничего не меняет и подтверждает, что данные корректны, ЮKassa предлагает пользователю ввести данные второго документа — ИНН, СНИЛС или полиса ОМС, чтобы проверить получателя выплат другим способом.
Форма ввода вторго документа
Если после этого проверка проходит успешно, ЮKassa отправляет вам параметры для проведения выплаты (синоним банковской карты и идентификатор пользователя) и перенаправляет пользователя на страницу успеха. Если с данными всё еще что-то не так, ЮKassa перенаправляет пользователя на страницу неудачи.
Шаг 6. ЮKassa отправляет полученные данные в сервис ГУВМ МВД для завершения проверки получателя выплат.
Готово!
Выплаты можно делать сразу, как только вы получите данные от ЮKassa. Окончательный результат проверки вы узнаете при первом использовании идентификатора пользователя:
  • Если выплата с этим идентификатором пользователя, пройдет успешно (status=0), то всё хорошо, получатель идентифицирован, данные можно использовать для проведения выплат.
  • Если в ответ вернется ошибка, что паспортные данные не прошли проверку (status=3 и error=48), то получателю выплаты необходимо еще раз пройти идентификацию.
  • Если в ответ вернется сообщение, что запрос в обработке (status=1), то это значит, что проверка данных еще идет. Дождитесь финального статуса запроса (успех или неудача).
Форма для привязки банковской карты и идентификации пользователя
Форма для сбора данных размещена на стороне ЮKassa. Вам нужно перенаправить на нее пользователя.
Адрес для отправки запросов
https://yookassa.ru/cardauth
ПараметрТипОписание
url_successxs:string,
до 250 символов
URL, на который необходимо отправить пользователя в случае успеха авторизации.
Обязательный параметр
url_errorxs:string,
до 250 символов
URL, на который необходимо отправить пользователя в случае неуспеха авторизации.
Обязательный параметр
identifyxs:boolean
Необходимость получить от пользователя данные для идентификации кошелька. Используется в случае, если требуется хранение и проверка паспортных данных на стороне ЮKassa.
Необязательный параметр
small_amount_onlyxs:boolean
Признак выплат от 100 до 15 000 рублей включительно. Влияет на количество полей, которые нужно заполнить пользователю.
Значение по умолчанию — false.
Необязательный параметр
Пример формы (полный набор полей)
https://yookassa.ru/cardauth?url_error=http://domain.tld/fail&url_success=http://domain.tld/success&identify=true
Пример формы (сокращенный набор полей)
https://yookassa.ru/cardauth?url_error=http://domain.tld/fail&url_success=http://domain.tld/success&identify=true&small_amount_only=true
Ответ после отправки формы
ЮKassa обрабатывает полученные на форме данные и перенаправляет пользователя методом GET на адрес, указанный в url_success или url_error.
Вы получаете ответ при перенаправлении пользователя на страницу успеха или ошибки.
В случае успеха к адресу добавляются синоним, маска и дополнительные параметры карты пользователя, которые удалось определить в процессе обработки. Вы можете хранить синонимы, маски и дополнительные параметры карты на своей стороне без опасения утечки: их публикация не приводит к финансовым или имиджевым потерям.
ПараметрТипОписание
Обязательные параметры
skr_destinationCardPanmaskxs:string,
до 25 символов
Маска банковской карты. Пример: 510612******3456
skr_destinationCardSynonimxs:string,
до 100 символов
Синоним банковской карты. Пример: Ubc1CrurSqRQ5Va09IeVIRI6.SC.000.201812
skr_destinationCardCountryCodexs:string,
до 3 символов
Цифровой код страны, в которой выпущена карта. Например, 643 (Россия)
skr_destinationCardTypexs:string,
до 25 символов
Тип банковской карты. Visa, Mastercard, Mir
identificationStatusxs:string,
до 100 символов
Результат проверки паспортных данных:
  • success при успехе,
  • error или fail при ошибке.
Возвращается, только если вы передали в форме identify=true
accountNumberxs:string,
до 25 символов
Идентификатор пользователя в ЮKassa. Возвращается только в случае успеха идентификации. Пример: 410012345678933
Возвращается, только если вы передали в форме identify=true
Условно-обязательные параметры
identificationErrorxs:string,
до 1000 символов
Возвращается только в случае ошибки при проверке. В отдельных случаях может не возвращаться
Полученные данные нужно использовать в запросах на зачисление переводов. ЮKassa по полученному синониму определяют номер карты получателя, а по идентификатору — персональные данные пользователя.
Что почитать еще
Зачисление переводов на банковскую картуТипы данныхКоды ошибокТестирование