# Как подключить платежный шлюз на примере Сбера

Привет, меня зовут Евгений Думчев, я разработчик в DD Planet. Сегодня хочу поделиться опытом подключения платежного шлюза Сбера, чем мы занимались в рамках одного из проектов. Кажется, это будет полезная история, ведь в нынешние непростые времена многие из нас задумываются о том, чтобы открыть свой «маленький свечной заводик» – какой-нибудь небольшой бизнес на черный день. Тортики там печь, платы паять, в общем, что-нибудь, что бы обеспечило дополнительный доход. Раньше для коммерции подобных сайд-проектов не требовалось ничего, кроме условного Пейпала (к тому же он расширял географию продаж). А теперь волей-неволей приходится задумываться об отечественных решениях для проведения оплат.

Платежный шлюз – как раз такое решение. И оно на самом деле очень простое, любой посетитель Хабра, скорее всего, сможет его развернуть, достаточно хотя бы примерно представлять устройство REST API. В этой статье я расскажу, как подключить и настроить шлюз от Сбера – но в принципе эта инструкция пригодится со шлюзом от любого банка.

<cut>

### Терминология

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

**Эквайринг** – сервис, позволяющий принимать оплату за товары и услуги с банковских карт с помощью платежных терминалов.

**Интернет-эквайринг** – то же, но через платежные шлюзы в интернете (сайты, социальные сети, мессенджеры). В отличие от не совсем легальной схемы «переведите мне на карту», которой часто пользуются совсем маленькие предприниматели, здесь все делается вбелую.

**Банк-эквайер** – банк, реализующий и эксплуатирующий платежный шлюз. Он не всегда очевиден, если шлюз предоставляет третья сторона.

**Банк-эмитент** – банк, выпустивший карту клиента.

**Мерчант** – магазин, обладающий доступом к платежному шлюзу и его админке. Для банка это учетная запись конкретного торгово-сервисного предприятия.

Как работает платежный шлюз? С точки зрения пользователя – просто. Набрал корзину, нажал «купить», перешел на сайт, ввел данные карты и CVC и нажал кнопку «оплатить». Для банка цепочка чуть длиннее – после «оплатить» банк делает запрос в платежную систему (сейчас в РФ – в национальную НСПК), эта платежная система делает запрос к банку-эмитенту, тот сообщает, может ли пользователь оплатить и проводит обычную транзакцию. Дальше ответ идет в платежную систему, затем в платежный шлюз, и оттуда уже получает ответ страница магазина.


С чего начать подключение платежного шлюза? Для начала стоит изучить, какие вообще существуют интернет-эквайринги, их условия и способы подключения. Обычно эта информация есть на сайте банка-эквайера. Затем выбрать и подписать соглашение, есть разные способы это сделать, конкретно у Сбера удобнее всего использовать сервис «Сбер бизнес», там все понятно и есть персональный консультант.

### Требования к сайту мерчанта

Интернет-магазин должен осуществлять деятельность в соответствии с законодательством РФ. Есть определенные запрещенные виды деятельности и товаров: порнография, подделки, любой алкоголь, редкие экзотические животные, казино и т.д. Не стоит пытаться сделать ширму – сайт вроде как продает тортики, а на самом деле к тортикам прикладывается алкоголь, потому что это неизбежно вскроется. Также не должно быть ссылок и баннеров на подозрительные сайты.

Перечень товаров и услуг должен соответствовать роду деятельности, сообщенному в банк. При подключении вы описываете, что будете продавать, и именно это должно присутствовать на витрине магазина.

Сайт не должен располагаться на бесплатных серверах, потому что это небезопасно. Как правило, требуется доступ по https; в реальности это требование иногда можно обойти, но надо договариваться с платежным шлюзом – разрешение дают не всегда. Для тестовой среды достаточно http.

Есть отдельный список обязательной к размещению информации. Например, рядом с кнопкой «оплатить» должны быть разъяснены все основные моменты, связанные с покупкой:
* Сведения о местонахождении организации, адрес для корреспонденции, ИНН, контактные номера телефонов и email, по которым покупатель сможет связаться с мерчантом.
* Сведения о процедуре покупки, способах оплаты, вариантах доставки, условиях возврата и обмена товара или услуги.
* Информация о том, что делать, если возникли проблемы с оплатой
* Сведения об обработке персональных данных при оплате.

Для соответствия федеральному закону 54 «Об обязательном применении онайн-касс для интернет-магазинов» у мерчанта должен быть заключен договор с оператором фискальных данных (ОФД), который их хранит, обрабатывает, передает их в налоговую и формирует чек. Если такого нет, то можно подключить один из тех, с которыми уже есть интеграция у Сбера – АТОЛ, КОМТЕТ Касса, OFD.ru, Цифровая касса и пр. Нюансы разных ОФД лучше изучить заранее. Запрос в ОФД идет после того, как клиент произвел оплату – либо это делает шлюз, если использовать ОФД от Сбера, либо это должен делать сам магазин, если у него подключен свой.

Все эти требования проверяются при подключении шлюза к продакшн-среде. Когда вы готовы выйти в свет, представитель банка-эквайера зайдет на тестовый сайт и либо попросит что-то исправить, либо подключит продакшн.

### Как будем интегрироваться?

Возможные способы интеграции по возрастанию уровня автоматизации:
- выставление счета через ЛК Сбера. Можно обойтись без собственного сайта, просто заходим, получаем ссылку и отправляем ее клиенту. Если у нас продаж три-четыре в день, это нормально.
- платежная кнопка, она есть у Сбера. По сути это скрипт с токеном, минус такого подхода – ловкий вредитель может подправить скрипт в браузере и поменять, например, сумму платежа. Это небезопасная история, ее лучше не использовать.
- готовый плагин для CMS. У Сбера есть из коробки возможность подключить такой способ оплаты. Не самый продвинутый, но работает.
- API. Можно использовать WSDL (SOAP) или REST, нам кажется удобнее REST, потому что он проще и гибче, плюс данные передаются в JSON, а не в XML.

### API Сбера

Итак, мы подключились и готовы отправлять запросы к шлюзу. Для начала надо знать, что существует три вида платежей:
- **одностадийный**, когда клиент заходит на страницу оплаты, вводит данные карты, и деньги моментально списываются;
- с **предавторизацией**, т.н. «холдирование» средств: клиент вводит данные на странице оплаты, но деньги не списываются, а замораживаются, и для списания позже надо сделать отдельный запрос. Это делается, например, в сервисах проката: привязывается карта, на ней замораживается какая-то сумма, а когда услуга завершается, списывается столько, сколько было реально использовано. Преимущество холдирования – быстрый возврат средств на карту. С одностадийным платежом возврат средств, если день закончился, занимает до месяца. Кроме того, при возврате банк оставляет себе комиссию, поэтому их лучше минимизировать;
- **автоплатежи**, как правило, какие-то подписки. Мы создаем один заказ на оплату, пользователь знакомится с условиями подписки и разово ее подтверждает. Больше ему ничего делать не нужно, а мы должны будем хранить связку («биндинг») и дальше делать регистрацию заказа через нее.

Итак, главный запрос API – Регистрация заказа на оплату или Регистрация заказа с предавторизацией: мы отправляем API некий набор данных (см. ниже), шлюз в ответ присылает id заказа и ссылку на оплату.


Из остальных запросов стоит отметить:
- Завершение оплаты заказа, нужен для оплат с предавторизацией;
- Отмена оплаты, тоже работает с холдированными оплатами;
- Возврат средств – используется, когда было проведено фактическое списание (возвращать, кстати, можно неполную сумму);
- Возврат средств по устаревшему заказу сроком более 2 лет;
- Статус заказа – по этому запросу можем понять, что произошло у пользователя, ведь после регистрации заказа на оплату он ушел на страницу шлюза и мы не знаем, что там происходит. Провел ли он оплату?
- Проверка наличия у карты 3DS (если ее нет, то по идее можно проводить оплату даже не заходя на шлюз);
- Отмена неоплаченного заказа – иногда может оказаться полезным. Заказ на оплату живет определенное количество времени (это можно указать, например, 30 минут). Но в некоторых бизнесах надо иметь возможность отменить заказ преждевременно, например, если сумма изменилась в течение этих 30 минут;
- Сведения о кассовом чеке – стоит учесть, что чек доступен не сразу, надо периодически повторять запрос;
- Запросы активации, деактивации и прочие действия с привязанными картами.

### Параметры регистрации заказа на оплату

По умолчанию API ждет в теле запроса поля `userName`, `password`, `orderNumber`, `amount` и `returnUrl`. Первые два – логин и пароль мерчанта. Номер заказа создается и хранится в бэкенде магазина, как его создавать, мы решаем сами, но он всегда должен быть уникальный. Сумма платежа в минимальных единицах валюты (копейки, центы и т.д.). returnUrl – куда вернуть клиента со страницы шлюза. В урле можно передать сколько угодно параметров, чтобы вернуться на полезную страницу, например, с обновленным балансом лицевого счета или информацией о заказе.

Опциональные поля надо подключать через службу поддержки, написав соответствующий запрос. В Сбере это единственный способ – никаких галочек в ЛК нет. К опциональным полям относятся:
- `currency` – валюта платежа;
- `failUrl` – если у нас есть страница про неуспешную оплату, ее можно засунуть сюда;
- `description` – описание заказа в свободной форме;
- `clientId` – id клиента в базе магазина;
- `jsonParams` – дополнительные параметры. Мы их используем в ситуации, когда надо проводить оплаты на разные расчетные счета, и чтобы их разнести и в дальнейшем понимать, что было оплачено и какой формировать чек, вставляем в это поле уникальные идентификаторы;
- `sessionTimeoutSecs` – срок жизни сессии оплаты. По идее, у всех шлюзов есть значения по умолчанию, но лучше всегда передавать это значение самостоятельно, чтобы точно знать, что сессия не зависнет навсегда;
- `bindingId` – уникальный идентификатор связки постоянного пользователя с картой;
- `features` – булевые параметры из определенного набора готовых значений, например, провести оплату без перехода на страницу оплаты (`AUTO_PAYMENT`)
- `email`, `phone` – лучше тоже подключить и передавать, потому что после проведения оплаты Сбер умеет направлять уведомление на электронную почту клиента.

В ответе шлюз возвращает строку `orderId` и ссылку на страницу оплаты `formUrl`.

### Архитектура клиент-серверного взаимодействия

В качестве примера архитектуры возьмем один из наших проектов. Он чуть сложнее, чем базовый магазин: здесь платежи зачисляются нескольким мерчантам, представленным небольшим фиксированным списком. Для каждого мерчанта был написан свой микросервис со своей базой, и для общения со шлюзом используется отдельный сервис SberAPI.

Итак, клиент (веб-страница или мобильное приложение) делает запрос на бэкенд, в какой-то из микросервисов. У каждого из них есть своя база, он заполняет параметры для регистрации заказа и дальше делает запрос на SberAPI, который также хранит данные по оплате и созданным заказам. Получив запрос, SberAPI обогащает его дополнительными параметрами (юзернейм и пароль нашего мерчанта, у которого есть учетная запись в банке), сохраняет заказ и делает запрос в Сбер.
Сбер возвращает id заказа и ссылку, это тоже сохраняется, после чего передается в микросервис, который может что-то с информацией сделать и затем вернет все в клиентское приложение, где уже откроется полученная ссылка на оплату.

Дальше надо как-то сообщить клиенту, успешно он оплатил или нет. Узнать это можно двумя способами: отправив запрос или же получив запрос от самого шлюза через опцию «Обратный вызов» (Callback, о нем ниже). Для ошибок у Сбера есть целая страница с кодами, рекомендованным и фактическим текстом ошибки. Рекомендованный надо показать пользователю, а фактический может содержать специфическую информацию типа «банковская карта замечена в мошеннических операциях».

Помимо того, что выдается в клиентском интерфейсе, надо сохранить информацию о результате проведения операции в бэкенд (в нашем случае – и в базу микросервиса, и в базу SberAPI). Такое дублирование мы сделали, потому что микросервис должен уметь быстро показывать историю операций клиенту, а сервис шлюза хранит ее на случай возможных ошибок, требующих обращения в службу поддержки Сбера.

### Обратный вызов

Уведомление обратного вызова, оно же callback-уведомление, подключается через службу поддержки. Такие уведомления бывают двух типов: без контрольной суммы (не рекомендуется, потому что любой пользователь, зная url нашего сервиса, может делать туда запросы) и с контрольной суммой (симметричная или асимметричная криптография). Сбер предлагает примеры криптоалгоритмов на php и Java, они вполне понятные, их нетрудно переписать на нужный язык (в нашем случае это был C#).

Если нужен, вот наш работающий алгоритм на C#:

public bool VerifyRequestSignature(IQueryCollection requestQueryParams, string certificatePublicKey)
{
	var checksum = requestQueryParams["checksum"].ToString().ToLower();
	if (string.IsNullOrEmpty(checksum))
		return false;

	var data = string.Join(string.Empty, requestQueryParams
		.Where(q => !q.Key.IgnoreCaseEquals("checksum") && !q.Key.IgnoreCaseEquals("sign_alias"))
		.OrderBy(q => q.Key)
		.Select(q => $"{q.Key.Trim()};{q.Value.ToString().Trim()};"));

	using var sha512 = SHA512.Create();
	var hashedData = sha512.ComputeHash(Encoding.UTF8.GetBytes(data));

	using var x509Cert = new X509Certificate2(Convert.FromBase64String(certificatePublicKey));
	using var rsa = x509Cert.GetRSAPublicKey();

	var signature = checksum
		.Where((item, index) => index % 2 == 0)
		.Select((item, index) => $"{item}{checksum[index * 2 + 1]}")
		.Select(str => Convert.ToByte(str, 16))
		.ToArray();

	return rsa.VerifyHash(hashedData, signature, HashAlgorithmName.SHA512, RSASignaturePadding.Pkcs1);
}

Итак, чтобы callback работал, нужно создать свой API, к которому будет стучаться Сбер c запросами, содержащими данные об операции, начиная с orderId. При обращении Сбер ожидает получить ответ 200, если приходит что-то другое, он делает еще несколько попыток с интервалом 10 минут.

Когда платежный шлюз производит редирект по нашему returnUrl, он параллельно делает запрос на наш бэкенд по callback-урлу, указанному в ЛК Сбера. Времени хватает, чтобы по callback-урлу актуализировать статус заказа на оплату и отобразить корректную информацию пользователю. Но в реальности бывают случаи, когда запрос по callback приходит позже или вовсе не приходит. Например, в нашем опыте был случай, когда во время ночных технических работ на стороне Сбера отчеты о проведенных платежных операциях не пришили через callback, и мы мы не могли вовремя актуализировать статус некоторых заказов. Поэтому надо иметь запасной план – собственно, сам Сбер рекомендует опрашивать их сервис по каждому проведенному платежу.

Таким образом, дополнительно к callback-обработке, статус заказа на оплату нужно актуализировать и на запросах от нашего клиентского приложения, которые выполняются после того, как мы вернулись в приложение по returnUrl. И периодически их актуализировать – это дает дополнительную надежность и гарантию хранения информации по заказам на оплату в актуальном состоянии. Для этого мы используем планировщик, который периодически прогрессивным способом (сперва раз в минуту, потом каждые десять минут и т.д.) опрашивает API банка о проведенной операции. Не стоит стучаться туда постоянно, может сработать ddos-защита, но вообще подобные запросы помогают. Например, пока мы работали только через callback, пользователь ждал статуса около 30 секунд, когда стали актуализировать заказы на оплату по запросам с клиентского приложения или планировщика – время снизилось до секунды.

### Как хранить данные об операциях

Наиболее удобный и предпочтительный способ хранения – документоориентированная СУБД. Запрос на создание заказа и оплату содержит большой набор параметров, а ответ – еще больше, в нем три уровня данных, и раскладывать все это в реляционную СУБД – затратная операция. А в noSQL базе можно просто сохранить пришедший JSON, не пытаясь его распарсить. Мы используем MongoDB, но можно выбрать и другую СУБД, позволяющую хранить и обрабатывать данные в json формате.

В Mongo все это выглядит как-то так:


Данные стоит хранить в трех коллекциях:
- коллекция заказов, в которой хранятся параметры запроса, результат выполнения запроса, статус и опциональные параметры;
- коллекция связок (bindings) по картам пользователя (чтобы быстро показывать их клиенту);
- callback уведомления от Сбера и время, когда они пришли.

### Работа с маркетплейсами

Особенность маркетплейсов в том, что на них можно набрать в одну корзину товаров от разных поставщиков, причем сам список поставщиков не постоянен. Как же продавцы получат деньги, если все запросы на регистрацию заказа идут от одного мерчанта – маркетплейса? В случае Сбера есть специальные запросы API: запрос распределения платежа по конечным получателям и возврат статуса перечисления платежей поставщикам.

Пример: пользователь купил десять товаров от десяти разных поставщиков, платеж прошел. Через некоторое время Сбер делает запрос информации о том, как нужно распределить этот платеж. Приходит id платежа, а мы должны предоставить детализацию заказа, сколько кому надо перевести. Надо учитывать, что Сбер может повторить этот запрос, и мы должны будем вернуть тот же самый ответ. После того, как шлюз распределит платеж по расчетным счетам, он сделает еще один callback-запрос, сообщающий, что деньги успешно разошлись.

### Техническая поддержка

В целом, поддержка Сбера скорее помогает, чем нет, но делает она это не слишком быстро и не всегда с первого раза. Как правило, алгоритм такой: пишешь вопрос, в течение получаса отвечают – либо по существу, либо просят подождать еще два часа. После чего история может повториться, затянуться, и в конце концов вопрос через пару недель будет автоматически закрыт без ответа.

Когда ответ приходит, он не всегда отличается содержательностью. Придется снова спрашивать, при этом вы попадете на нового сотрудника, который снова даст столь же полезный ответ...

Например, у нас ушло два дня на то, чтобы получить корректный ключ для расшифровки подписи. Я переписал алгоритм шифрования на C# – там все просто, занимает пару часов. Но когда начали тестировать с предоставленным ключом, он не работал. Пошли к поддержке узнать, в чем дело, – и после нескольких часов ожидания получили ссылки на те же самые страницы с алгоритмами на php и Java, которые я переписал (и которые, разумеется, были упомянуты в вопросе). Пришлось ставить php и Java, чтобы точно понять, что проблема в ключе и, в конце концов, получить его правильный вариант.

Еще одну историю пришлось решать почти три месяца, но она была связана с особенностью проекта, где присутствовало несколько мерчантов, а клиенты были одни и те же и, соответственно, хотели привязать одну карту для оплаты всех услуг. В этом случае был обнаружен баг на стороне шлюза, пришлось много общаться, в том числе и с лидами проекта от Сбера, а проблему закрывать собственными костылями. В конце концов, баг шлюза был поправлен, но наше решение к тому времени уже работало.

Тем не менее, стоит признать, что поддержка Сбера работает – просто не нужно ожидать чудес и мгновенного решения всех проблем.

### Сертификаты

Как известно, Сбер под санкциями, и у него недавно протухли международные сертификаты безопасности. Значит, придется ставить [сертификаты от НУЦ Минцифры](https://securepayments.sberbank.ru/wiki/doku.php/certificates:add:backend) (обратите внимание, _лучше_ ставить именно сертификаты для бэкенда по ссылке, а не клиентские сертификаты с Госуслуг и [прочих мест](http://www.sberbank.ru/ru/certificates) – хотя в нашем случае хватило и их). Они потребуются сервису, который непосредственно обращается к шлюзу – если он работает в докер-контейнере, значит, прокидываем их туда.

Для покупателей же Сбер, к счастью, подготовил лазейку в виде «альтернативных доменов платежных страниц», сертифицированных в Let’s Encrypt. Чтобы их подключили именно вам, надо написать в поддержку. Насколько долго и надежно это будет работать – никто не знает, но хотя бы пока можно не утруждать клиентов установкой «отечественных браузеров» и «сертификатов Минцифры».