Hyperswitch Prism

Hyperswitch Prism: Единая библиотека для интеграции с любыми платежными процессорами

В современном мире электронной коммерции интеграция платежных систем является одной из самых сложных задач для разработчиков. Каждый платежный процессор имеет свои уникальные API, наборы кодов ошибок, методы аутентификации и поведенческие нюансы, которые часто не совпадают с официальной документацией. Hyperswitch Prism — это инновационное решение, призванное устранить эти сложности, предоставляя единый, типизированный интерфейс для взаимодействия с глобальными платежными шлюзами.

Что такое Hyperswitch Prism?

Hyperswitch Prism представляет собой легковесную stateless (без сохранения состояния) библиотеку коннекторов, которая позволяет подключаться к любому платежному процессору через одну унифицированную интеграцию. Этот инструмент был извлечен из надежной кодовой базы Juspay Hyperswitch — платформы с открытым исходным кодом, имеющей более 40 000 звезд на GitHub и используемой ведущими предприятиями по всему миру.

Основная философия Hyperswitch Prism заключается в предоставлении разработчикам свободы выбора без привязки к конкретному поставщику (zero lock-in). Библиотека выступает в роли трансформационного слоя, который переводит универсальные запросы вашего приложения в специфические форматы, понятные таким гигантам, как Stripe, Adyen, Braintree, Worldpay и многие другие.

Ключевые особенности Hyperswitch Prism

Hyperswitch Prism спроектирован с упором на безопасность, производительность и удобство разработки. Вот основные характеристики, которые выделяют эту библиотеку:

1. Единая схема запросов для всех платежей

Одной из главных проблем интеграции является необходимость писать отдельный код для каждого процессора. С Hyperswitch Prism один и тот же вызов authorize будет работать для Stripe, Adyen и любого другого поддерживаемого коннектора без изменения бизнес-логики вашего приложения. Это значительно ускоряет масштабирование на новые рынки.

2. Полная независимость от состояния (Stateless)

Библиотека не использует базу данных и не сохраняет персональные данные (PII). Ваши учетные данные (Credentials) не логируются и не хранятся внутри системы — они существуют ровно столько, сколько живет ваш HTTP-клиент. Это обеспечивает максимальную прозрачность и безопасность транзакций.

3. Сокращение области действия PCI DSS

Hyperswitch Prism позволяет вам самостоятельно решать, как обрабатывать карточные данные. Вы можете использовать хранилище (vault) платежного процессора или собственное сертифицированное хранилище PCI. Библиотека не хранит данные карт, что упрощает прохождение аудита безопасности.

4. Типизированные и идиоматичные SDK

Библиотека предоставляет многоязыковую поддержку, включая Node.js, Python, Java и Rust. Все интерфейсы строго типизированы, что позволяет отлавливать ошибки на этапе компиляции, а не в процессе выполнения платежа.

Как использовать Hyperswitch Prism (How to Use)

Интеграция начинается с установки библиотеки для вашего языка программирования и настройки конфигурации коннектора.

Установка библиотеки

Для среды Node.js:

npm install hyperswitch-prism

Для разработчиков на Python:

pip install hyperswitch-prism

Для проектов на Java/Kotlin добавьте зависимость в pom.xml:

<dependency>
    <groupId>io.hyperswitch</groupId>
    <artifactId>prism</artifactId>
    <version>0.0.4</version>
</dependency>

Пример проведения платежа (Node.js)

После установки вы можете инициировать авторизацию платежа следующим образом:

import { PaymentClient, types } from 'hyperswitch-prism';

// Настройка конфигурации для Stripe
let config: types.ConnectorConfig = {
    connectorConfig: {
        stripe: {
            apiKey: { value: "sk_test_..." }
        }
    }
}

const main = async () => {
    let client = new PaymentClient(config);
    let request: types.PaymentServiceAuthorizeRequest = {
        merchantTransactionId: "order_555",
        amount: {
            minorAmount: 1000, // $10.00
            currency: types.Currency.USD,
        },
        captureMethod: types.CaptureMethod.AUTOMATIC,
        paymentMethod: {
            card: {
                cardNumber: { value: "4111111111111111" },
                cardExpMonth: { value: "12" },
                cardExpYear: { value: "2050" },
                cardCvc: { value: "123" },
                cardHolderName: { value: "Test User" },
            },
        },
        authType: types.AuthenticationType.NO_THREE_DS,
        address: {},
        orderDetails: [],
    }

    let response = await client.authorize(request);
    if (response.status === types.PaymentStatus.CHARGED) {
        console.log("Платеж успешно проведен!");
    }
}

Сценарии использования (Use Case)

Динамическая маршрутизация между провайдерами

Наиболее мощный сценарий использования Hyperswitch Prism — это возможность мгновенного переключения между платежными процессорами на основе бизнес-правил. Например, вы можете направлять транзакции в EUR через Adyen, а транзакции в USD — через Stripe, изменив всего одну строку кода в логике инициализации клиента.

Пример логики: Если валюта транзакции равна EUR, библиотека использует конфигурацию Adyen; для всех остальных случаев — Stripe. При этом сам вызов метода авторизации остается идентичным.

Это позволяет предприятиям минимизировать комиссии за трансграничные платежи и внедрять стратегии умных повторных попыток (smart retries), если основной процессор временно недоступен.

Что Hyperswitch Prism не делает (пока что)?

Проект имеет четкие границы проектирования, чтобы оставаться легким и эффективным инструментом:

1. Встроенное хранилище (Vault): Prism не предоставляет сервис токенизации. Это осознанный выбор — вы можете использовать решение от процессора или свое собственное.
2. Логика ретраев и маршрутизации: Сама библиотека является лишь слоем трансформации. Интеллектуальная логика управления платежами реализована в полной версии Juspay Hyperswitch.
3. Сервисы помимо платежей: На данный момент функционал сфокусирован на платежах, но в будущем планируется поддержка подписок, предотвращения мошенничества и налоговых расчетов.

Часто задаваемые вопросы (FAQ)

В: Насколько безопасно использование Hyperswitch Prism? О: Библиотека полностью stateless. Она не хранит ваши API-ключи, PII или данные карт в базе данных или логах. Все данные передаются только в рамках жизненного цикла HTTP-запроса.

В: Какие платформы поддерживаются? О: SDK включает нативные библиотеки для macOS (Apple Silicon, arm64) и Linux (x86_64).

В: Как узнать, поддерживает ли Prism конкретный метод оплаты для моего процессора? О: Состояние каждой интеграции отслеживается в реальном времени. В документации используется система легенд: ✓ (Поддерживается), x (Не поддерживается), ⚠ (В разработке), ? (Требуется валидация).

В: Можно ли использовать ИИ-ассистентов для написания кода с Prism? О: Да, разработчики предусмотрели специальный файл документации для LLM, который можно передать вашему ИИ-помощнику (например, через curl), чтобы он получил полный контекст по SDK и методам обработки ошибок.