api-gateway-general

Целевой публичный merchant API: сюда приходит всё, что мерчант делает через нашу интеграцию, кроме операций с номером карты. Шлюз убеждается, что запрос пришёл от известного мерчанта, приводит его к внутреннему формату, подписывает и передаёт в нужный внутренний сервис — чаще всего в ядро. Новая публичная ручка без карточных данных заводится именно здесь.

Стек: Kotlin, Spring Boot.

Чего не делает

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

Входы

• Публичные операции merchant API: создание платежа со ссылкой на нашу форму, платёж без заранее известной суммы, проверка статуса заказа, инициация выплаты и запрос доступного для выплат баланса.
• Продуктовые и региональные операции: крипто-онрамп — инициация, курс и проверка статуса, — а также аргентинские переводы: выпуск CVU и инициация перевода на него.
• Запросы нашей платёжной формы, в которых нет карты: данные транзакции, список доступных крипто-методов и мобильных кошельков, выбор метода оплаты и подтверждение операции одноразовым кодом.
• Колбеки о зачислениях по ARS: шлюз не разбирает их, а передаёт дальше ровно в том виде, в котором получил, чтобы подпись проверил сервис ордеров.
• Служебное: проверка карты внешним антифродом, справочник валют и запросы Kaspi по их собственному протоколу.

Выходы

• Ядро — основной адресат. Запрос переводится во внутренний формат, тело подписывается ключом KMS, ключ мерчанта уходит отдельным заголовком.
• Сервис крипто-онрампа и сервис ARS-ордеров: у них свои адреса и свои ключи подписи, но для мерчанта это тот же публичный домен.
• Сервис авторизации — проверить пару «ключ мерчанта — секрет» либо подпись тела.
• IP плательщика, вычисленный из заголовков Cloudflare, шлюз прокидывает дальше: на нём завязаны ограничения по адресам и проверки антифрода.

Не все входящие запросы подписаны мерчантом. Форма, справочник валют, колбеки ARS и трафик Kaspi приходят без подписи, поэтому шлюз подставляет в запрос к ядру собственные учётные данные: для Kaspi, например, мерчант и счёт берутся из отдельного секрета, а не из тела запроса.

Хранилища

Своих данных не держит. Адреса внутренних сервисов и ссылки на ключи подписи задаются переменными окружения, секреты приходят из AWS Secrets Manager. Подключение к MongoDB в сервисе сконфигурировано, но бизнес-данные он оттуда не читает и туда не пишет.

Участвует во флоу

• Платёж через нашу форму — создаёт транзакцию и возвращает мерчанту ссылку на форму.
• Платёж картой server-to-server — сам платёж идёт мимо шлюза, но проверку статуса мерчант делает уже здесь.
• Выплаты, крипто-онрамп и ARS-переводы.

Где искать

• Репозиторий: smartpayments-dev/superpos-api-gateway-general.
• Инфраструктура, домены и логи: карточка сервиса в описании прод-контура.
• Публичная документация: merchant API — это тот самый api-gateway.smartcore.pro; отсюда обслуживаются платёжная форма и выплаты. Сборка документации живёт в репозитории PCI-шлюза, по одной на бренд.
• Возвраты, рекуррентные и двухстадийные платежи пока остаются в историческом TypeScript-шлюзе superpos-api-gateway: если ручки здесь нет, работающий код ищите там.