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

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

В качестве примера архитектуры возьмем один из наших проектов. Он чуть сложнее, чем базовый магазин: здесь платежи зачисляются нескольким мерчантам, представленным небольшим фиксированным списком. Для каждого мерчанта был написан свой микросервис со своей базой, и для общения со шлюзом используется отдельный сервис 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 все это выглядит как-то так:

Данные стоит хранить в трех коллекциях:

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

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

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

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

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

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

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

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

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

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

Сертификаты

Как известно, Сбер под санкциями, и у него недавно протухли международные сертификаты безопасности. Значит, придется ставить сертификаты от НУЦ Минцифры (обратите внимание, лучше ставить именно сертификаты для бэкенда по ссылке, а не клиентские сертификаты с Госуслуг и прочих мест — хотя в нашем случае хватило и их). Они потребуются сервису, который непосредственно обращается к шлюзу — если он работает в докер-контейнере, значит, прокидываем их туда.

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