Интеграция платежной системы ЮKassa: документация API и SDK, инструкции для разработчиков

Добро пожаловать в исчерпывающее руководство по интеграции ЮKassa для разработчиков! Меня зовут Алексей Солтык, я PHP-программист и SEO-специалист с более чем 10-летним опытом. В этом материале я расскажу, как внедрить прием онлайн-платежей на сайт с помощью ЮKassa - от регистрации в сервисе и получения API-ключей до настройки приема платежей, возвратов и работы с онлайн-кассой. 

В статье вы найдете подробные инструкции по работе с API и SDK ЮKassa, примеры кода на PHP, Python, JavaScript и других языках, ссылки на полезные справочники и технические ресурсы. Я поделюсь своим опытом интеграции платежей в интернет-магазины, расскажу о типовых ошибках и лучших практиках разработки. Материал будет полезен как для опытных разработчиков, так и для тех, кто впервые настраивает прием оплаты на сайте.

Интеграция ЮKassa открывает интернет-магазинам и онлайн-сервисам доступ к широкой базе клиентов ЮMoney и принятие оплаты всеми популярными способами:

• Банковские карты Visa, Mastercard, МИР 
• Кошелек ЮMoney 
• Сбербанк Онлайн 
• QIWI Кошелек 
• Интернет-банки 
• Apple Pay, Google Pay

Кроме того, вы сможете принимать оплату в рублях и других валютах, настроить онлайн-кассу в соответствии с 54-ФЗ, получать информацию о платежах и выплатах через Webhook-уведомления. А если нет времени на интеграцию API - можно начать принимать оплату через платежные ссылки или выставлять счета клиентам без единой строчки кода.

Уже более 120 000 онлайн-бизнесов используют ЮKassa для приема платежей. В их числе - Яндекс.Маркет, Skyeng, Ситимобил, Домклик от Сбербанка и многие другие. С нами вы получаете современную и надежную платежную систему, сертифицированную по стандарту PCI-DSS для защиты данных плательщиков. А персональный менеджер и служба поддержки 24/7 помогут на всех этапах подключения и работы с сервисом.

Добавьте на ваш сайт удобные способы оплаты, расширьте свою аудиторию покупателей и повысьте конверсию - интегрируйте ЮKassa уже сегодня!

Обзор возможностей API ЮKassa

API ЮKassa предоставляет универсальные инструменты для работы с онлайн-платежами на вашем сайте или в мобильном приложении. Основные возможности сервиса включают:

• Прием платежей более чем 20 способами оплаты. Можно принимать оплату с карт (Visa, Mastercard, МИР), через интернет-банки (Сбербанк Онлайн, Альфа-Клик и др.), электронные кошельки (ЮMoney, QIWI) и со счета мобильного телефона. 
• Сохранение карт плательщиков и возможность оплаты в один клик. Это увеличивает конверсию оплат, особенно для повторных покупок.
• Платежные ссылки и выставление счетов без интеграции. Быстрый способ начать принимать платежи, если нет времени на подключение API.
• Информация о платежах и возвратах в личном кабинете и через API. Всегда можно узнать статус транзакции, получить данные для бухгалтерии и аналитики.  
• Проведение полных и частичных возвратов. Если покупатель отменил заказ или вернул товар, можно легко вернуть ему оплату обратно на карту или кошелек.
• Безопасные сделки для маркетплейсов. Движение денег между покупателями и продавцами на вашей площадке будет автоматизировано и защищено от мошенничества.
• Кассовые чеки для соответствия 54-ФЗ. ЮKassa передает данные для формирования чека в онлайн-кассу партнеров. Вы работаете в соответствии с законом.
• Настройка уведомлений о событиях через Webhook. Получайте информацию об изменениях статусов платежей в реальном времени и автоматизируйте свои бизнес-процессы.

Далее мы рассмотрим пошагово, как внедрить эти возможности в ваш проект и начать принимать онлайн-оплату на сайте. 

С чего начать интеграцию ЮKassa

Чтобы подключить ЮKassa к вашему сайту, нужно сделать несколько подготовительных шагов: 

1. Создать аккаунт ЮKassa. Зарегистрируйтесь в личном кабинете ЮKassa по ссылке https://yookassa.ru/joinups. Для работы с реальными платежами нужно оформить договор с "ЮMoney", для этого придется предоставить данные организации или ИП.
2. Отправить документы на проверку. Чтобы начать принимать оплату на реальный счет, ЮKassa должен проверить ваши данные и документы. Обычно проверка занимает 1-2 рабочих дня. 
3. Получить API-ключи. В разделе "Настройки" личного кабинета вы найдете ваши API-ключи - идентификатор аккаунта (shopId) и секретный ключ (Secret Key). Они нужны для аутентификации ваших запросов к API ЮKassa. Никому не передавайте секретный ключ, кроме доверенных разработчиков.
4. Выбрать способы оплаты. В разделе "Настройки" вы также сможете указать, какие способы приема платежей хотите подключить. Можно выбрать карты, кошельки, интернет-банки, счет телефона - или все сразу. Чем больше вариантов оплаты - тем лучше для конверсии.
5. Скачать SDK на вашем языке программирования. ЮKassa предоставляет готовые библиотеки на PHP, Java, Python, Node.JS, .NET, 1С и других платформах. Это сэкономит время и избавит от рутинной работы по созданию запросов к API. 

Когда подготовительные шаги пройдены, можно переходить непосредственно к интеграции API на вашем сайте.

Интеграция ЮKassa на сайт

Для интеграции платежей ЮKassa на сайте необходимо реализовать несколько ключевых функций:

1. Аутентификацию запросов к API с помощью ключей shopId и Secret Key
2. Инициацию платежей путем создания объекта "платеж" 
3. Перенаправление пользователя на страницу оплаты ЮKassa или отображение платежной формы на вашем сайте
4. Обработка уведомлений о статусе платежа
5. Проведение возвратов при необходимости 

Рассмотрим подробнее каждый из этих пунктов.

Аутентификация через API-ключи

Первым делом необходимо реализовать аутентификацию ваших запросов к API. 

• ЮKassa использует связку из двух ключей - shopId и Secret Key. shopId передается в параметрах запроса, Secret Key в специальном заголовке.
• Ключи можно скопировать в личном кабинете ЮKassa. Есть два набора ключей - тестовый и боевой. На этапе разработки и отладки используйте тестовые ключи. Когда решение будет готово - переключитесь на боевые.
• Внимательно следите за сохранностью ключей, особенно боевого Secret Key. Утечка секретного ключа может привести к мошенническим операциям от вашего имени. Если есть подозрения, что ключ скомпрометирован - сразу же отзовите его и сгенерируйте новый.
• Не передавайте секретный ключ на клиентскую сторону (в браузер или мобильное приложение). Используйте его только на бэкенде. 
• Примеры аутентификации запросов через API-ключи есть в документации к API и в составе SDK библиотек ЮKassa на популярных языках программирования. 

Также ЮKassa поддерживает аутентификацию через OAuth-токены. Это более гибкий и безопасный способ авторизации запросов к API. Если вы реализуете сложные сценарии взаимодействия с ЮKassa - изучите возможность применения OAuth в вашем проекте.

Работа с API ЮKassa

Основные сценарии взаимодействия с платежной системой реализуются через REST API ЮKassa. Это современный и удобный стандарт, который поддерживается всеми популярными языками и фреймворками.

• Изучите справочник методов API ЮKassa в официальной документации - https://yookassa.ru/developers/api. Он содержит подробное описание всех доступных ресурсов, параметров запроса и ответа, возможных ошибок.
• Следите за версией API, которую вы используете. ЮKassa поддерживает обратную совместимость, но в новых версиях могут появляться дополнительные возможности и оптимизации.
• API работает только по защищенному протоколу HTTPS. Игнорируйте любые запросы к вашему серверу, пришедшие по незащищенному HTTP.
• В ответах от API может приходить дополнительная информация, которая не описана в документации. Не пытайтесь ее анализировать или использовать в логике работы вашего приложения. Ориентируйтесь только на документированные поля.
• Используйте уникальный ключ idempotence_key для каждого запроса, чтобы избежать дублирования операций. Он защитит от случайного создания двух одинаковых платежей, если у пользователя возникли проблемы с сетью.
• В процессе разработки сверяйтесь с примерами кода на вашем языке программирования. ЮKassa предоставляет готовые SDK библиотеки для популярных платформ и фреймворков - PHP, Java, Node.js, Python, .NET, 1C и других. Используйте их, чтобы сэкономить время и избежать рутинных операций.

Самые востребованные методы API - создание платежа, получение информации о транзакции, проведение возврата, обработка уведомлений. Рассмотрим их реализацию подробнее.

Прием платежей

Чтобы совершить платеж через ЮKassa, нужно создать объект Payment в API. Он содержит всю необходимую информацию - сумму, назначение платежа, способ оплаты, данные для чеков по 54-ФЗ.

• Минимально необходимые данные для создания платежа - Amount (сумма), Description (описание), Confirmation (способ подтверждения на стороне ЮKassa). 
• В ответ на запрос создания платежа придет объект Payment с присвоенным идентификатором в ЮKassa, ссылкой для перенаправления пользователя (если не встроенная форма) и другими параметрами.
• После создания платеж имеет статус Pending - "Ожидает оплаты покупателем". Когда пользователь завершит оплату, платеж изменит статус на Succeeded (успешно оплачен) или Canceled (неуспех).
• Следите за статусами платежа либо через ответы API, либо через уведомления, чтобы корректно отразить состояние заказа в вашей системе и предоставить товар или услугу.
• Используйте параметр Metadata для хранения внутреннего идентификатора заказа на вашей стороне. Это поможет связать транзакцию в ЮKassa с вашими бизнес-процессами.
• Настройте отправку чеков в соответствии с 54-ФЗ. Укажите номенклатуру товаров, ставку и сумму налога, электронную почту покупателя при создании платежа.
• Сохраняйте банковские карты плательщиков для оплаты в один клик. Повторные покупки без повторного ввода данных карты увеличат конверсию.

Если вы хотите минимизировать отказы платежей, можно дополнительно реализовать сценарии с двухстадийной оплатой. Сперва при создании платежа указать параметр Capture=false - это заморозка (холдирование) средств на счету покупателя. А после проверки данных и наличия товара на складе - прислать в API запрос на подтверждение платежа. Если что-то пойдет не так - можно отменить холдированный платеж.

Возвраты платежей

Иногда возникают ситуации, когда покупатель возвращает товар или отказывается от услуги и требует вернуть деньги. Благодаря API ЮKassa вы можете легко проводить полные или частичные возвраты на карту или электронный кошелек плательщика.

Основные моменты по работе с возвратами:

• Возврат может быть полным (на всю сумму платежа) или частичным (на любую сумму в пределах платежа). Частичные возвраты удобны в случае возврата только части товаров из заказа.
• Возвраты можно проводить только по успешно оплаченным (Succeeded) платежам. Для холдированных платежей нужно вместо возврата делать отмену.
• На обработку возврата может потребоваться до 30 дней, но обычно они проходят в течение нескольких минут. Следите за статусом возврата в ответах API или в личном кабинете.
• Укажите параметр Idempotence_key для каждого возврата, чтобы избежать случайного дублирования операции при повторных запросах.
• При проведении полного возврата сумма в запросе должна в точности совпадать с суммой изначального платежа. Иначе вернется ошибка.
• Комиссия ЮKassa за проведение платежа не возвращается при отмене или возврате. Учитывайте это в своей внутренней бухгалтерии.

В чеках возвратов нужно указывать те же данные, что и при изначальной оплате - номенклатуру, количество товаров, сумму и ставку налога. ЮKassa передаст информацию для формирования чека возврата в вашу онлайн-кассу.

Если покупатель оплатил заказ с нескольких платежей - возвраты необходимо проводить по каждому из них отдельно. Сумма возвратов по платежу не может превышать его изначальную сумму.

Использование Webhook-уведомлений

Рекомендуем настроить получение автоматических сообщений о событиях в ЮKassa - изменении статусов платежей, возвратов, сделок. Это можно сделать с помощью механизма Webhook.

• В личном кабинете ЮKassa укажите URL, на который будут приходить уведомления о событиях. Это должен быть публичный адрес вашего сервера.
• ЮKassa будет присылать HTTP-запросы с информацией о событии - успешной оплате, отмене платежа, проведении возврата на указанный URL.
• Ваш сервер должен отвечать на запрос с HTTP-кодом 200 или 202, чтобы ЮKassa зафиксировала успешное получение уведомления. Иначе будут повторные попытки отправки.
• Проверяйте подпись уведомления в заголовке Webhook-Signature, чтобы убедиться, что оно действительно пришло от ЮKassa, а не от злоумышленников. Для проверки используется секретный ключ.
• В полученных уведомлениях анализируйте объекты Payment, Refund, Deal (для сделок) и меняйте соответствующий статус заказа в вашей системе. 
• Обрабатывайте все возможные типы событий. Состав параметров может отличаться между уведомлениями, сверяйтесь с документацией. 

Webhook-уведомления надежнее и удобнее, чем опрос API по таймеру. Но на первых этапах можно дополнительно запрашивать состояние платежа через API для подстраховки.

Не забудьте протестировать получение и обработку Webhook на вашем сервере перед запуском в продакшн. Это одна из критически важных частей интеграции.

Онлайн-касса в соответствии с 54-ФЗ

С 2017 года в России действует закон 54-ФЗ, по которому интернет-магазины должны передавать данные о каждой оплате в онлайн-кассу, подключенную к ОФД. Онлайн-касса формирует фискальный чек и отправляет его в ОФД. Покупатель получает электронную копию чека.

ЮKassa позволяет соблюсти требования 54-ФЗ и работать с онлайн-кассой из единого интерфейса. Это удобнее и надежнее, чем отдельная интеграция с кассой.

• Подключите онлайн-кассу одного из партнеров ЮKassa - Атол, Orange Data, Штрих-М, Эвотор, Модуль и других. ЮKassa имеет готовые решения для популярных касс.
• Генерация фискальных чеков по 54-ФЗ будет происходить автоматически после получения информации о платеже из API ЮKassa. Вам не нужно отдельно взаимодействовать с онлайн-кассой.
• Укажите Налоговую систему (ОСН, УСН, ПСН) в личном кабинете ЮKassa, чтобы данные о налогах корректно отражались в чеках.
• При создании платежа через API передавайте в параметре Receipt данные для чека - наименования товаров, количество, цены, ставки НДС.
• За формирование и отправку чека отвечает онлайн-касса. Она передает чек в ОФД и возвращает его статус в ЮKassa.
• Если одновременно с платежом создается чек, статус чека можно получить в ответе метода создания платежа. Параметр "status" в блоке "receipt_registration" показывает успешность регистрации чека.
• Электронную копию чека ЮKassa отправит на email покупателя, указанный при создании платежа. Вы также можете получать информацию о чеках через Webhook.

Более подробную информацию о вариантах интеграции c онлайн-кассой вы найдете в специальном разделе технической документации ЮKassa.

SDK, CMS и готовые модули

Если вы используете один из популярных языков программирования или CMS, ЮKassa уже позаботилась о нативных библиотеках для упрощения разработки. 

Официальные SDK доступны для:

• PHP
• Java
• Node.js
• Python
• .NET 
• 1С

SDK включают в себя готовые методы для аутентификации, создания платежей и возвратов, обработки уведомлений. Это экономит время и избавляет от рутинных операций.

Для популярных CMS существуют готовые модули, позволяющие быстро настроить прием платежей:

• 1C-Bitrix
• WordPress/WooCommerce 
• OpenCart
• PrestaShop
• Magento
• UMI.CMS
• MODX Revolution
• Drupal/Ubercart
• HostCMS
• AmiroCMS

С полным списком модулей и CMS можно ознакомиться на сайте ЮKassa в разделе "Модули и плагины". Там же есть инструкции по установке и настройке.

Если вы используете Laravel, Symfony, Yii, Django, Ruby on Rails - высока вероятность найти неофициальную библиотеку для работы с API ЮKassa, созданную сообществом. Поищите решения на GitHub.

Тестирование интеграции

Перед запуском приема платежей в продакшне необходимо провести тщательное тестирование всех компонентов и сценариев - от создания платежа до получения уведомлений.

ЮKassa предоставляет все необходимое для этого:

• Тестовая среда, полностью имитирующая работу реального сервиса. Доступна по адресу демо магазина https://yoomoney.ru/demo .
• Специальные тестовые ключи shopId и secretKey для аутентификации запросов в тестовой среде. Не используйте боевые ключи для тестов!
• Генерация платежей с разными статусами - успех, неуспех, ожидание подтверждения. Карты и кошельки с определенным результатом.
• Управление статусами возврата - успех, неуспех, ожидание обработки.
• Эмуляция работы онлайн-кассы, формирование тестовых чеков с заданными настройками.
• Логирование и трассировка запросов в тестовой среде для удобства отладки.

Подробнее о тестировании написано в специальном разделе документации - "Тестирование интеграции". Следуйте приведенным там инструкциям.

Начните с простых сценариев - успешная оплата картой и кошельком, затем постепенно усложняйте: неуспех, двухстадийная оплата, возвраты, чеки.

Проверьте отображение всех статусов платежей и возвратов в вашей системе заказов. Убедитесь, что учтены как позитивные, так и негативные сценарии.

Смоделируйте ситуации с отменой и корректировкой заказов, перерасчетом суммы. Убедитесь, что данные консистентны.

Тщательное тестирование на этапе разработки поможет избежать проблем и потери денег в будущем. Уделите ему должное время!  

FAQ по работе с ЮKassa

Здесь мы собрали самые частые вопросы, которые возникают у разработчиков при интеграции ЮKassa.

Что делать, если платеж зависает в статусе "Pending"?

Такое возможно в случае, если пользователь начал оплату, но не завершил ее (например, закрыл страницу или не подтвердил в СМС от банка). По истечении определенного времени (зависит от способа оплаты) такие платежи автоматически отменяются. Вы также можете запросить отмену в API, если не хотите ждать.

Как проверить корректность подписи уведомления?

Уведомления от ЮKassa содержат HTTP-заголовок Webhook-Signature с подписью. Вам нужно:

1. Получить webhook_key из личного кабинета (настройки уведомлений)
2. Объединить строки метода, URL и тела запроса через символ "|" 
3. Вычислить HMAC-SHA256 хеш от получившейся строки, используя webhook_key
4. Сравнить хеш с подписью из заголовка Webhook-Signature

Если подписи совпадают - уведомление корректно и пришло от ЮKassa.

Безопасно ли сохранять карточные данные у себя?

Настоятельно не рекомендуем! Хранение карточных данных на своей стороне связано с высокими рисками компрометации и требует сертификации PCI-DSS. Используйте возможности ЮKassa для сохранения карт по токену.  

Как подключить Apple Pay, Google Pay, СБП?

Если вы интегрировали API ЮKassa по актуальной документации - эти способы оплаты подключатся автоматически, дополнительных настроек не требуется. 

В чем разница между встроенной формой оплаты и шаблоном по умолчанию?

Встроенная форма оплаты ЮKassa отрисовывается прямо на вашем сайте по ссылке, полученной при создании платежа, без редиректа. Страница оплаты по умолчанию открывается по прямой ссылке на сайте ЮKassa.

Какие ставки НДС поддерживаются в чеках?

ЮKassa позволяет указать ставку НДС 20%, 10%, 0% и без НДС. Это зависит от вашей системы налогообложения и типа товаров. Проконсультируйтесь с бухгалтером.

Как принимать платежи в долларах, евро или других валютах?

Если вы находитесь за пределами РФ, можно настроить прием платежей в долларах, евро, тенге и других валютах. Для этого нужно отдельно заключить договор с ЮKassa.

На этом мы завершаем наш обзор по интеграции ЮKassa. Надеюсь, эта информация поможет вам быстро и безошибочно подключить прием платежей!

Поддержка разработчиков

Если у вас возникли вопросы по работе с API ЮKassa или проблемы с интеграцией - не стесняйтесь обращаться к нам за помощью!

Доступные каналы поддержки:

• Документация по API, доступная по адресу https://yookassa.ru/developers/api Здесь вы найдете подробное описание методов, параметров, схемы взаимодействия.
• Раздел FAQ в документации со списком часто задаваемых вопросов и готовыми решениями типовых проблем.  
• Сообщество разработчиков https://github.com/yoomoney - можно задать вопрос опытным коллегам или поделиться своим опытом.
• Официальный Telegram-чат @yookassa_developers - оперативные ответы на вопросы по разработке от команды ЮKassa.
• Тикеты в службу поддержки из личного кабинета ЮKassa. Можно получить консультацию по нестандартным ситуациям, запросить

Связаться в Telegram

Следующие страницы вас также могут заинтересовать:

• Настройка Cloudflare для защиты и оптимизации сайта
• SEO умного фильтра Bitrix
• Калькулятор конверсии онлайн | Расчет конверсии сайта
• Робототехника
• «Оптимизация и продвижение в поисковых системах» Игоря Ашманова - настольная книга по SEO

Обновлено: 11.06.2024