Интеграция с Альфа-Банком

Интернет-эквайринг Альфа-Банка позволяет принимать оплату заказов банковской картой или через СБП прямо при оформлении заказа. Покупатель нажимает «Оформить заказ», попадает на защищённую платёжную страницу Альфа-Банка, оплачивает и возвращается в ваш магазин. Addshop сам отмечает заказ как оплаченный, как только банк подтвердит платёж, — вам не нужно сверять выписки вручную.

Вы можете создать интернет магазин за 1 вечер. Просто выберите готовый шаблон интернет магазина и установите его. Останется только наполнить его своими товарами.

В этой статье — подробная инструкция: что получить у банка, как заполнить настройки в Addshop, как создать способ оплаты, как проверить подключение и что делать, если что-то не работает.

Что понадобится

Договор интернет-эквайринга с Альфа-Банком. Его заключают в банке, условия и комиссию сообщает менеджер Альфа-Банка.
Логин и пароль API. Банк присылает их после подключения эквайринга. Это не логин от интернет-банка и не логин от личного кабинета эквайринга, а отдельная пара для обмена данными между магазином и банком.
Ключ подписи уведомлений. Его выдаёт банк, когда вы включаете уведомления об оплате (callback-уведомления) с симметричной подписью.
Доступ в админку магазина на Addshop.
Если вы хотите, чтобы чеки 54-ФЗ пробивала касса банка, — подключённая у Альфа-Банка онлайн-касса. Если чеки пробивает другая касса, например АТОЛ Онлайн, это тоже подходит, подробнее ниже.

Шаг 1. Подготовка в личном кабинете Альфа-Банка

Точные названия разделов зависят от версии кабинета, поэтому ориентируйтесь на смысл, а если не нашли нужную настройку — попросите менеджера банка включить её за вас.

Убедитесь, что у вас есть логин и пароль API для боевой (рабочей) среды. Если вы сначала хотите проверить всё без настоящих денег, попросите у банка ещё и доступ к тестовой среде — у неё свой логин и пароль.
В личном кабинете Альфа-Банка (раздел «Настройки» → «Callback-уведомления») или через менеджера банка включите уведомления об оплате.
Тип подписи уведомлений выберите симметричный (HMAC-SHA256). Addshop проверяет именно такую подпись.
Адрес для уведомлений укажите такой: https://ваш-домен/alfa-handler/. Вместо «ваш-домен» подставьте адрес вашего магазина — тот же, что в адресной строке, когда вы открываете админку. Точный адрес показан на странице настроек Альфа-Банка в Addshop, его удобно скопировать оттуда.
Скопируйте ключ подписи, который выдаст банк. Он понадобится на следующем шаге.

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

Шаг 2. Настройка в Addshop

Откройте админку магазина, перейдите в «Остальные настройки» → «Интеграции» и в блоке «Платежные системы» нажмите на логотип Альфа-Банка. Можно открыть страницу и сразу по ссылке: настройки Альфа-Банка.

На странице есть такие поля.

Принимать оплату

Главный переключатель. Пока он выключен, Addshop не отправляет заказы в банк. Включить его можно, только если заполнены API логин, API пароль и ключ подписи уведомлений — иначе при сохранении появится сообщение «Для приёма оплаты укажите логин и пароль API и ключ для подписи уведомлений».

API логин

Логин API, который прислал банк. Вводите его без пробелов в начале и в конце.

API пароль

Пароль API от банка. После сохранения пароль не показывается в поле — вместо него видна подсказка «сохранён — оставьте пустым, чтобы не менять». Если поле оставить пустым и нажать «Сохранить», сохранённый пароль останется прежним. Чтобы заменить пароль, просто впишите новый.

Ключ подписи уведомлений

Ключ, который банк выдал при включении callback-уведомлений с симметричной подписью. Addshop проверяет этим ключом каждое уведомление от банка: если подпись не сходится, уведомление отклоняется. Ключ, как и пароль, после сохранения скрыт.

Передавать чек

Если включить, Addshop вместе с заказом передаёт в банк его состав: товары, доставку и наценку за способ оплаты. Это нужно, только если чеки 54-ФЗ пробивает касса банка. Подробнее — в разделе «Чеки 54-ФЗ» ниже.

Тестовая среда

Если включить, заказы отправляются в тестовую среду Альфа-Банка — деньги не списываются. Для тестовой среды нужны тестовые логин и пароль, боевые там не работают. После проверки обязательно выключите переключатель и впишите боевые логин и пароль.

Заполнив поля, нажмите «Сохранить». Если всё в порядке, появится надпись «Изменения успешно внесены», а у логотипа Альфа-Банка в списке интеграций — зелёная галочка.

Шаг 3. Способ оплаты

Сама интеграция ещё не показывает покупателю новый способ оплаты. Его нужно создать отдельно.

Откройте раздел «Оплата» в верхнем меню админки.
Нажмите «Добавить».
В поле «Название» напишите то, что увидит покупатель, например «Картой или через СБП онлайн».
В поле «Описание» можно коротко пояснить: «После оформления заказа вы перейдёте на защищённую страницу Альфа-Банка».
В поле «Система оплаты» выберите Альфа-Банк. Именно это поле связывает способ оплаты с интеграцией. Если оставить его пустым, заказ просто оформится без перехода к оплате.
В поле «Наценка %» при необходимости укажите процент, который добавится к сумме заказа при выборе этого способа. Наценка входит в сумму, которую заплатит покупатель, и отдельной строкой попадает в чек.
В блоке «Связь со способами доставки» отметьте доставки, при которых доступна онлайн-оплата. Например, онлайн-оплату можно разрешить для курьера и пунктов выдачи, а для самовывоза оставить оплату на месте.
Сохраните способ оплаты.

Чеки 54-ФЗ

Есть два варианта, выберите один.

Вариант 1. Чеки пробивает касса Альфа-Банка

Если у вас подключена онлайн-касса через банк, включите «Передавать чек» в настройках Альфа-Банка. Тогда в банк уходит состав заказа: каждый товар с ценой и количеством, доставка и наценка за способ оплаты (как услуга). Сумма всех строк чека всегда равна сумме заказа.

Признаки для чека берутся так:

ставка НДС, способ расчёта и предмет расчёта — из карточки товара, а если там не заданы — из «Настроек платежей» магазина (поля «Налог», «Метод платежа», «Объект платежа»)
система налогообложения — из поля «Система налогообложения» в «Настройках платежей»
e-mail и телефон покупателя — из заказа

Особый случай — НДС 22 %. Для ставок 22 % и 22/122 код банка для чека пока не подтверждён. Если такая ставка выбрана у магазина или у товара в заказе и при этом включено «Передавать чек», заказ в банк не передаётся. Покупатель увидит сообщение «Оплата картой сейчас недоступна: не удалось сформировать чек. Заказ сохранён, магазин свяжется с вами». Решение — пробивать чеки через АТОЛ Онлайн (вариант 2) или временно выключить передачу чека, если касса банка вам не нужна.

Вариант 2. Чеки пробивает АТОЛ Онлайн

Если касса у вас своя в АТОЛ Онлайн, выключите «Передавать чек» в настройках Альфа-Банка, а в настройках АТОЛ Онлайн отметьте Альфа-Банк среди способов оплаты. Иначе чек будет пробит дважды. Подробно — в статье Чеки 54-ФЗ через АТОЛ Онлайн. Общие сведения о чеках — в статье Как настроить онлайн-чеки 54-ФЗ.

Как проверить

Получите у банка тестовые логин и пароль API. Включите в настройках Альфа-Банка «Тестовая среда», впишите тестовые данные и сохраните.
Убедитесь, что в тестовой среде банка тоже включены уведомления на адрес https://ваш-домен/alfa-handler/ и что ключ подписи в Addshop — от этой среды.
Откройте витрину магазина в другом браузере или в режиме инкогнито, положите товар в корзину и оформите заказ, выбрав созданный способ оплаты.
Вы должны попасть на платёжную страницу Альфа-Банка. Оплатите тестовой картой, которую даст банк.
После оплаты вы вернётесь в магазин на страницу «Заказ оформлен».
Откройте заказ в админке. Через несколько секунд или минут после оплаты у него должна стоять отметка «Оплачен».
Если всё сработало — выключите «Тестовая среда», впишите боевые логин и пароль, при необходимости обновите ключ подписи и снова сохраните.

Совет: после перехода на боевую среду сделайте одну настоящую покупку на небольшую сумму и верните её через кабинет банка — так вы проверите и рабочие уведомления.

Как это работает после подключения

Оформление. Покупатель выбирает способ оплаты, связанный с Альфа-Банком, и нажимает «Оформить заказ». Addshop сохраняет заказ, регистрирует его в банке на итоговую сумму (товары со скидкой по промокоду, доставка и наценка) и перенаправляет покупателя на страницу оплаты Альфа-Банка.
Если банк не принял заказ. Покупатель видит сообщение «Не удалось перейти к оплате в банке Альфа-Банк. Заказ сохранён, магазин свяжется с вами». Заказ остаётся в админке неоплаченным — свяжитесь с покупателем.
Оплата прошла. Покупатель возвращается на страницу «Заказ оформлен». Параллельно банк присылает уведомление на /alfa-handler/.
Проверка оплаты. Получив уведомление, Addshop сначала проверяет подпись ключом. Затем сам запрашивает у банка состояние заказа и ставит отметку «Оплачен», только если банк подтвердил оплату именно этого заказа и на его текущую сумму. Так поддельное уведомление не может отметить заказ оплаченным.
Если банк временно не ответил. Addshop отвечает банку ошибкой, и банк присылает уведомление повторно — заказ отметится при следующей попытке.
Оплата не прошла. Покупатель попадает на страницу «Оплата не прошла». Заказ остаётся в админке неоплаченным.
Если магазин заблокирован за неоплату тарифа. Адрес уведомлений продолжает работать, поэтому уже оплаченные покупателями заказы всё равно отметятся.

Частые проблемы и решения

Деньги списались, а заказ не отмечен «Оплачен»

Почти всегда причина в уведомлениях. Проверьте в кабинете банка, что уведомления включены, адрес указан точно https://ваш-домен/alfa-handler/ (со слешем в конце), тип подписи — симметричный, а ключ в Addshop совпадает с ключом в кабинете. Если ключ меняли в банке — впишите новый и в Addshop.

Сумма заказа изменилась после оформления

Addshop отмечает заказ оплаченным, только если оплаченная сумма совпадает с текущей суммой заказа. Если вы после оформления изменили состав заказа, доставку или скидку, а покупатель оплатил старую сумму, отметка не поставится автоматически. Сверьте сумму в кабинете банка и, если всё верно, поставьте отметку «Оплачен» в заказе вручную.

При сохранении настроек ошибка «Для приёма оплаты укажите логин и пароль API и ключ для подписи уведомлений»

Включён переключатель «Принимать оплату», но не заполнено одно из трёх полей. Заполните все три и сохраните ещё раз.

Покупатель видит «Не удалось перейти к оплате в банке Альфа-Банк»

Банк отклонил регистрацию заказа. Частые причины: неверный логин или пароль API, боевые данные при включённой тестовой среде (или наоборот), эквайринг ещё не активирован банком. Проверьте данные и режим, при необходимости уточните у менеджера банка.

Покупатель видит «Оплата картой сейчас недоступна: не удалось сформировать чек»

Включено «Передавать чек», а у магазина или у товара в заказе стоит ставка НДС 22 % или 22/122. Подробности и решение — в разделе «Чеки 54-ФЗ» выше.

Покупатель оформил заказ, но не попал на страницу оплаты

Проверьте, что в настройках Альфа-Банка включено «Принимать оплату», а у способа оплаты в разделе «Оплата» в поле «Система оплаты» выбран именно Альфа-Банк. Если переключатель выключен, заказ сохраняется, но к оплате покупатель не переходит.

Чек пробился дважды

Включены одновременно «Передавать чек» в Альфа-Банке и отправка чеков через АТОЛ Онлайн для Альфа-Банка. Оставьте что-то одно.

Тест прошёл, а боевые платежи не отмечаются

После перехода на рабочую среду проверьте, что выключен переключатель «Тестовая среда», вписаны боевые логин и пароль и что уведомления с правильным адресом и ключом включены в рабочем кабинете банка, а не только в тестовом.

Вопросы и ответы

Какие способы оплаты увидит покупатель на странице банка?

Это определяет банк по вашему договору: обычно банковские карты и СБП. Addshop передаёт только заказ и сумму.

Сколько стоит подключение?

Addshop не берёт отдельной платы за интеграцию. Комиссию за эквайринг устанавливает Альфа-Банк по вашему договору.

Можно ли подключить Альфа-Банк вместе с другими платёжными системами?

Да. Создайте в разделе «Оплата» отдельный способ оплаты для каждой системы, и покупатель выберет удобный.

Где посмотреть, пришло ли уведомление от банка?

Addshop записывает каждое уведомление — и принятое, и отклонённое. Если заказ не отмечается, напишите в поддержку Addshop номер заказа — мы проверим журнал уведомлений. Со своей стороны проверьте историю операций в кабинете банка.

Нужно ли что-то менять, если я подключил свой домен?

Да. Адрес для уведомлений должен вести на рабочий домен магазина. Если вы перешли на свой домен, укажите в кабинете банка https://ваш-новый-домен/alfa-handler/.

Что будет, если покупатель закрыл страницу банка, не оплатив?

Заказ останется в админке неоплаченным. Вы можете связаться с покупателем и договориться об оплате другим способом.