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