API ЮKassa
Помощь
Подключить ЮKassa
Перевод на банковскую карту
С помощью ЮKassa вы можете делать выплаты на карты российских и зарубежных банков.
Чтобы сделать выплату, в запросе на зачисление перевода необходимо передать подтверждение принятия оферты, синоним банковской карты и персональные данные получателя выплаты.
Данные для выплаты
Синоним банковской карты
Получение и хранение номера банковской карты подпадает под действие стандарта PCI DSS, поэтому ЮKassa хранит данные карт на своей стороне. Чтобы вы могли делать выплаты на карты, ЮKassa предоставляет вам:
  • синоним карты skr_destinationCardSynonim — идентификатор карты в системе ЮKassa;
  • маску карты для отображения данных получателю skr_destinationCardPanmask;
  • дополнительные параметры карты, которые удалось определить в процессе обработки.
Вы можете хранить эти данные на своей стороне без опасения утечки: их публикация не приводит к финансовым или имиджевым потерям.
Персональные данные пользователя
Персональные данные необходимо передавать в соответствии с законодательством РФ.
Обязательно — паспортные данные (ФИО, серия, номер и дата выдачи паспорта, дата рождения, гражданство) и номер телефона.
Если карта эмитирована не российским банком или если выплата больше 15 000 рублей, нужно передать дополнительные данные о месте жительства получателя выплаты. Если карта эмитирована не российским банком, то размер выплаты не влияет на количество полей: нужно всегда передавать расширенный набор данных.
Дополнительно к паспортным данным можно указать данные других документов — ИНН, СНИЛС и номер полиса ОМС. Если при стандартной проверке персональных данных что-то пойдет не так, то ЮKassa использует эти данные, чтобы проверить получателя выплат другим способом.
Сценарии проведения выплат на карту
Собирать данные можно самостоятельно или с помощью формы ЮKassa.
Самостоятельное получение синонима банковской карты и персональных данных пользователя
Чтобы провести выплаты с самостоятельным сбором данных получателя выплаты:
  1. Получите синоним банковской карты.
  2. Разместите на своем сайте форму для ввода персональных данных пользователя и соберите данные.
  3. Отправьте запрос на перевод денег (makeDeposition) передайте в нём полученный синоним, персональные данные пользователя и подтверждение принятия оферты.
ЮKassa будет проверять персональные данные каждый раз, когда вы будете отправлять запрос makeDeposition.
Получение синонима и сбор персональных данных на стороне ЮKassa
Чтобы провести выплаты со сбором данных получателя выплаты через форму ЮKassa:
  1. Перенаправьте получателя выплаты на форму ЮKassa для сбора данных банковской карты и персональных данных и получите синоним карты и идентификатор пользователя.
  2. Отправьте запрос на перевод денег (makeDeposition) и передайте в нём данные, полученные на шаге 1, и подтверждение принятия оферты.
ЮKassa будет проверять персональные данные только при их сборе.
Срок действия идентификатора пользователя один год. Если срок действия закончился, нужно получить новый идентификатор или собрать персональные данные самостоятельно. Если в запросе makeDeposition использовать идентификатор с истекшим сроком действия, ЮKassa вернет ошибку с кодом 160.
Параметры запроса
Здесь описаны только параметры, специфичные для переводов на банковскую карту. Остальные параметры общие для всех типов запросов на зачисление перевода (makeDeposition).
Для выплат на банковскую карту в идентификаторе получателя dstAccount необходимо передать значение 25700130535186.
В paymentParams необходимо передать данные получателя выплаты.
Имя поля paymentParamsТипОписание
skr_destinationCardSynonimxs:string,
до 50 символов
Обязательный параметр
pof_offerAcceptedxs:int,
1 символ
Подтверждение принятия оферты получателем выплаты (1 — принята).
Обязательный параметр
Данные получателя выплаты — обязательно при сборе данных с помощью формы ЮKassa
cps_ymAccountxs:string,
до 25 символов
Идентификатор пользователя в ЮKassa. Равен значению параметра accountNumber, полученного в ответе после идентификации получателя выплаты через форму
Персональные данные получателя выплаты — обязательно при самостоятельном сборе данных
pdr_lastNamexs:string,
до 50 кириллических символов
Фамилия
pdr_firstNamexs:string,
до 50 кириллических символов
Имя
pdr_middleNamexs:string,
до 50 кириллических символов
Отчество. Обязательно, если есть в паспорте.
pdr_docNumberxs:long,
10 символов
Серия и номер паспорта гражданина РФ (без пробелов).
pdr_docIssueDatexs:string,
10 символов
Дата выдачи паспорта в формате ДД.ММ.ГГГГ
smsPhoneNumberxs:long,
до 15 символов
Номер телефона в международном формате (79…).
pdr_birthDatexs:string,
10 символов
Дата рождения в формате ДД.ММ.ГГГГ
pdr_countryxs:int,
3 цифры
Гражданство. Указывается как цифровой код страны (РФ — 643)
pdr_omsxs:int,
до 16 символов
Номер полиса ОМС. Пример: Пример: 12345678901234
Необязательный параметр
pdr_snilsxs:int,
до 14 символов
СНИЛС получателя выплат (только цифры, без пробелов). Пример: 12345678901
Необязательный параметр
pdr_innxs:int,
до 12 символов
ИНН получателя выплат. Пример: 123456789012
Необязательный параметр
Дополнительные персональные данные (если выплата больше 15 000 рублей или если карта эмитирована не российским банком) — обязательно при самостоятельном сборе данных
pdr_cityxs:string,
до 30 кириллических символов
Город получателя выплаты
pdr_addressxs:string,
до 100 кириллических символов
Адрес получателя выплаты
pdr_postcodexs:long,
6 символов
Почтовый индекс
Примеры запроса
Пример запроса для зачисления средств на банковскую карту (сокращенный набор полей)
XML
<makeDepositionRequest
  requestDT="2019-06-21T14:13:37.965Z"
  contract="Перевод денег на банковскую карту"
  amount="15000.00"
  agentId="12345"
  clientOrderId="payouts-110_1561126417933"
  dstAccount="25700130535186"
  currency="643">
  <paymentParams>
    <skr_destinationCardSynonim>oALesdd_h_YT6pzpJ10Kn5aB.SC.000.201906</skr_destinationCardSynonim>
    <pof_offerAccepted>1</pof_offerAccepted>
    <smsPhoneNumber>79818932328</smsPhoneNumber>
    <pdr_firstName>Эдуард</pdr_firstName>
    <pdr_lastName>Запеканкин</pdr_lastName>
    <pdr_docNumber>1013123456</pdr_docNumber>
    <pdr_docIssueDate>10.10.2013</pdr_docIssueDate>
    <pdr_inn>12345678912</pdr_inn>
    <pdr_country>643</pdr_country>
    <pdr_birthDate>31.10.1973</pdr_birthDate>
  </paymentParams>
</makeDepositionRequest>
Пример запроса для зачисления средств на банковскую карту (полный набор полей)
XML
<makeDepositionRequest
  requestDT="2019-06-21T14:17:29.578Z"
  contract="Перевод денег на банковскую карту"
  amount="20000.00"
  agentId="12345"
  clientOrderId="payouts-110_1561126649528"
  dstAccount="25700130535186"
  currency="643">
  <paymentParams>
    <skr_destinationCardSynonim>3lSdWL0Yf9DHRd2r4LAbyhfV.SC.000.201906</skr_destinationCardSynonim>
    <pof_offerAccepted>1</pof_offerAccepted>
    <smsPhoneNumber>79818932328</smsPhoneNumber>
    <pdr_firstName>Эдуард</pdr_firstName>
    <pdr_lastName>Запеканкин</pdr_lastName>
    <pdr_docIssueDate>10.10.2013</pdr_docIssueDate>
    <pdr_inn>12345678912</pdr_inn>
    <pdr_phoneNumber>79111471111</pdr_phoneNumber>
    <pdr_postcode>701152</pdr_postcode>
    <pdr_country>643</pdr_country>
    <pdr_city>Санкт-Петербург</pdr_city>
    <pdr_address>Невский проспект, д 1, к 2, кв 1</pdr_address>
    <pdr_birthDate>22.07.1967</pdr_birthDate>
  </paymentParams>
</makeDepositionRequest>
Пример запроса для зачисления средств на банковскую карту (сбор данных на стороне ЮKassa)
XML
<makeDepositionRequest
  agentId="200200"
  clientOrderId="db6c3eaf9ffc0d8933490ed1"
  requestDT="2018-12-01T00:00:01+03:00"
  dstAccount="25700130535186"
  amount="100.00"
  currency="643"
  contract="Перевод денег на банковскую карту">
  <paymentParams>
    <skr_destinationCardSynonim>2OHSXN6QG-vGPX8WHtOciU86.SC.000.201906</skr_destinationCardSynonim>
    <pof_offerAccepted>1</pof_offerAccepted>
    <cps_ymAccount>4100322815079</cps_ymAccount>
  </paymentParams>
</makeDepositionRequest>
Ответ на запрос
Если при переводе на банковскую карту возникла ошибка (error=48), ответ ЮKassa может содержать дополнительный поясняющий текст (techMessage):
  • notRegistrationRecord — не хватает обязательных параметров (pdr_). Дополнительно указывается перечень недостающих полей.
  • Банк отклонил перевод денег на данную карту
  • Банк отклонил операцию
  • Превышен лимит операций
  • Паспортные данные не прошли проверку
Пример сообщения об ошибке
XML
<makeDepositionResponse
  clientOrderId="payouts-110_1561103462999"
  status="3"
  error="48"
  processedDT="2019-06-21T10:51:04.089+03:00"
  techMessage="Не заданы или неверно заданы поля: pdr_docIssueDate"
/>
Что почитать еще
Выплаты с расчетного счетаТипы данныхКоды ошибокТестированиеРеестры успешных и возвращенных выплат