Форма для сбора данных
Для перевода денег на банковскую карту необходимо собрать персональные данные пользователя и данные банковской карты. Это можно сделать самостоятельно или с помощью специальной формы ЮKassa.
Если использовать форму, ЮKassa будет хранить необходимые данные на своей стороне. Контрагент получит синоним банковской карты и идентификатор пользователя в ЮKassa — это обезличенные данные, публикация которых не несет имиджевых или финансовых рисков. С помощью полученных данных контрагент сможет проводить выплаты на карту без проверки паспортных данных.
ЮKassa будет проверять персональные данные только при получении идентификатора пользователя. Срок действия идентификатора один год. Для дальнейших выплат на карту пользователя персональные данные нужно собирать заново.
 
Сценарий взаимодействия
Шаг 1. Пользователь инициирует выплату на свою банковскую карту на стороне контрагента.
Шаг 2. Контрагент перенаправляет пользователя на форму для сбора данных банковской карты.
Шаг 3. Пользователь вводит данные карты и нажимает Добавить карту.
Форма ввода данных банковской карты
Шаг 4. Переходит на веб-страницу ЮKassa с формой для ввода паспортных данных, заполняет все поля и нажимает Добавить.
Форма ввода персональных данных пользователя (полный набор полей)
Шаг 5. Данные проходят проверку, и ЮKassa перенаправляет пользователя на сторону контрагента.
  • Если с данными всё в порядке, ЮKassa отправляет контрагенту параметры для проведения выплаты (синоним банковской карты и идентификатор пользователя) и перенаправляет пользователя на страницу успеха.
  • Если с данными что-то не так, ЮKassa перенаправляет пользователя на страницу неудачи.
Шаг 6. Контрагент отправляет ЮKassa запрос на проведение выплаты (
makeDeposition
) с параметрами, полученными от ЮKassa на предыдущем шаге.
ЮKassa проверяет персональные данные пользователя в два этапа: быстрая проверка — на этапе ввода данных пользователем — и полная проверка в течение суток после отправки данных. Если после полной проверки с данными будет что-то не так, в ответ на запрос
makeDeposition
вернется ошибка.
 
Форма для привязки банковской карты и идентификации пользователя
Форма для сбора данных размещена в сервисе ЮKassa. Контрагенту нужно перенаправить на нее пользователя.
Адрес для отправки запросов
https://yookassa.ru/cardauth
ПараметрТипОписание
url_successxs:string,
до 250 символов
URL, на который необходимо отправить пользователя в случае успеха авторизации.
Обязательный параметр
url_errorxs:string,
до 250 символов
URL, на который необходимо отправить пользователя в случае неуспеха авторизации.
Обязательный параметр
identifyxs:boolean
Необходимость получить от пользователя данные для идентификации кошелька. Используется в случае, если требуется хранение и проверка паспортных данных на стороне ЮKassa.
Необязательный параметр
Если передан, в ответе придет результат проверки паспортных данных (
identificationStatus
) и идентификатор пользователя в ЮKassa (
accountNumber
).
small_amount_onlyxs:boolean
Признак выплат от 100 до 15 000 рублей включительно. Влияет на количество полей, которые нужно заполнить пользователю.
Значение по умолчанию —
false
.
Необязательный параметр
  • Если выплаты будут небольшие (до 15 000 рублей), рекомендуется передать
    small_amount_only=true
    . В этом случае, если карта эмитирована российским банком, пользователю нужно будет заполнить меньше полей.
  • Чтобы после привязки банковской карты пользователь ввел свои персональные данные, необходимо передать
    identify=true
    .
Пример формы (полный набор полей)
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
 
Ответ после отправки формы
Сервис обрабатывает полученные на форме данные и перенаправляет пользователя методом 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 может включать не описанные в этом документе параметры. Контрагенту следует их игнорировать.
Полученные данные нужно использовать в запросах на зачисление переводов. ЮKassa по полученному синониму определяют номер карты получателя, а по идентификатору — персональные данные пользователя.
 
Что почитать еще
Зачисление переводов на банковскую картуТипы данныхКоды ошибокТестирование