api-gateway-pci

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

Стек: Kotlin, Spring Boot. Репозиторий называется superpos-api-gateway-kotlin — имя историческое, речь именно про PCI-шлюз.

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

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

Входы

• Операции merchant API с картой: платёж server-to-server, выплата на карту получателя, авторизация в двухстадийной схеме, эмиссия и погашение emoney.
• Запросы нашей платёжной формы, в которых плательщик ввёл карту: оплата, сохранение карты, подтверждение суммы для платежей с отложенной суммой, а также оплата через Apple Pay и Google Pay.
• Отдельные ручки токенизации для тех, кому нужно получить токен, не проводя платёж, — в том числе пакетная токенизация списка карт.
• Выплата на карту из личного кабинета мерчанта: реквизиты вводит сотрудник мерчанта, поэтому запрос обязан прийти в PCI-контур.
• Проверка карты во внешнем сервисе TrustLayer.
• Служебный API учётных данных мерчанта: создать, сменить пароль, проверить Basic или подпись, подписать сообщение. Им пользуются другие наши сервисы, включая обычный шлюз.

Выходы

• Сервис токенизации — первое, куда уходит карта. Шлюз запрашивает сразу несколько токенов: постоянный токен карты, токен без срока действия и краткоживущую сессию, в которой лежат CVV и имя держателя.
• Ядро — с токенами, маскированным номером и определённым брендом карты вместо карточных данных. Тело подписывается ключом KMS.
• TrustLayer — когда нужно проверить карту во внешнем сервисе.

В ядро запрос уходит обычным HTTP-вызовом. В коде есть и альтернативный транспорт через брокер сообщений, включаемый настройкой, но он не задействован: принимающей стороны для таких сообщений в системе нет.

Хранилища

Собственной базы нет. Redis используется как кэш учётных данных мерчанта, чтобы не ходить в Secrets Manager на каждый запрос; сами учётные данные, доступы к внутренним сервисам и ссылки на ключи хранятся в AWS Secrets Manager, а подпись и проверка подписи делаются ключами KMS. Карточные данные не попадают ни в одно из этих хранилищ: в логах номер маскируется, а в ядро уходит уже обрезанный.

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

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

Где искать

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