Пользователям Протокола массовых выплат
Только для тех, кто использует Протокол массовых выплат ЮKassa
API ЮKassa отличается от Протокола массовых выплат с точки зрения возможностей, и с точки зрения формата взаимодействия. В этой статье приведены основные отличия, которые могут быть важны при интеграции.
Преимущества API ЮKassa
- API поддерживает те возможности, которых нет в Протоколе массовых выплат, например выплаты через СБП, настройка формы для получения данных банковской карты, универсальный токен для платежей и выплат и другие.
- У всех платежных решений API ЮKassa один и тот же формат взаимодействия. Если вы захотите принимать платежи по API ЮKassa или использовать другие платежные решения, вам нужно будет только подписать договор и подключить новые возможности по соответствующим инструкциям.
- Новые возможности будут появляться только в API ЮKassa.
Отличия API ЮKassa от Протокола массовых выплат
Формат взаимодействия
- Для аутентификации запросов вместо сертификата используется HTTP Basic Auth. В качестве имени пользователя используется идентификатор вашего шлюза для выплат по этому API, в качестве пароля — специальный секретный ключ. Подробнее об аутентификации запросов
- Формат взаимодействия другой. В частности:
- данные для аутентификации запроса и ключ идемпотентности передаются в заголовке, а не в теле запроса;
- данные передаются в формате JSON;
- в ответ на запрос возвращается объект в актуальном состоянии;
- состояние операции можно узнать по статусу объекта;
- можно подписаться на уведомления об изменении статуса объекта.
- В объекте выплаты сохраняется вся информация об операции — сумма выплаты и способ ее получения, статус, ваше описание выплаты, причина отмены выплаты (если в процессе что-то пошло не так), дополнительные данные, которые вы передавали в запросе (например, идентификатор получателя выплаты в вашей системе).
- В объекте выплаты есть информация о том, в каком режиме этот объект создавали — при тестировании или при проведении реальной выплаты.
Способы получения выплат
Выплаты можно делать на банковские карты, кошельки ЮMoney и через СБП на счета в банках и платежных сервисах. Подробнее о видах и лимитах выплат
Данные для выплат на банковскую карту
Нужно меньше данных: для выплат на банковскую карту нужны только данные карты — персональные данные получателя выплаты и согласие с офертой ЮKassa собирать не нужно.
Данные для выплат можно получить двумя способами:
- Если у вас нет сертификата на соответствие требованиям PCI DSS, для получения данных банковской карты и их обмена на синоним карты необходимо использовать специальный виджет ЮKassa. Его нужно встроить на страницу вашего сайта (в старом протоколе для сбора данных нужно перенаправить пользователя на страницу ЮKassa). В форме сбора данных можно настраивать цвета элементов интерфейса и язык текстов (русский или английский).
- Если у вас есть сертификат на соответствие требованиям PCI DSS, вы можете самостоятельно собирать данные банковской карты и передавать их в запросе без предварительного получения синонима карты.
Проверка получателя выплат
При выплатах через СБП дополнительно можно проверять получателя выплаты. Если указанный вами получатель выплаты не совпадет с тем, кто реально получит деньги, ЮKassa отменит выплату. Подробнее о выплатах с проверкой получателя
Универсальный токен для платежей и выплат
Если вы одновременно принимаете платежи и делаете выплаты, вы можете создать для пользователя универсальный токен с данными банковской карты. Его можно использовать и для проведения платежей, и для проведения выплат. Подробнее об универсальном токене
Баланс выплат
Чтобы узнать состояние баланса выплат по API, вам необходимо отправить отдельный запрос на получение информации о вашем шлюзе или посмотреть состояние баланса в личном кабинете. Как узнать баланс выплат по API
Реестры выплат
Для финансовой сверки ЮKassa присылает только реестр успешных выплат. Формат реестра — CSV. Формат отличается от формата тех реестров, которые используются в старом протоколе. Подробнее о реестрах
Передача данных получателя выплаты для выписки из реестра
С помощью ЮKassa вы можете делать выписки из реестра выплат с информацией о получателе выплаты. Такие выписки могут понадобиться для подтверждения факта выплаты в госорганах.
Для этого нужно сохранить персональные данные получателя в ЮKassa и затем передать идентификатор сохраненных данных в запросе на проведение выплаты. Если выплата была успешной, данные о получателе будут сразу доступны в выписке из реестра в личном кабинете. Подробнее о передаче данных получателя выплаты для выписок
Что почитать еще