Hyperswitch Prism

Hyperswitch Prism: 하나의 통합으로 모든 결제 프로세서를 연결하는 혁신적인 솔루션

현대 이커머스와 디지털 서비스 환경에서 결제 프로세서(Payment Processor) 통합은 비즈니스 성장의 핵심입니다. 하지만 각기 다른 결제 프로세서의 API, 복잡한 오류 코드, 인증 방식, 그리고 실제 환경과 문서 간의 차이를 극복하는 것은 매우 어려운 과제입니다. Hyperswitch Prism은 이러한 복잡성을 해결하기 위해 탄생한 무상태(Stateless) 통합 커넥터 라이브러리입니다.

Hyperswitch Prism이란 무엇인가?

Hyperswitch Prism은 모든 결제 프로세서에 연결할 수 있는 단일화된 커넥터 라이브러리입니다. 이 라이브러리는 수년간 Juspay Hyperswitch 내부에서 사용되며 수많은 테스트와 반복적인 버그 수정을 거쳐 검증된 강력한 통합 기능을 추출하여 만들어졌습니다.

결제 프로세서 통합이 어려운 이유는 무엇일까요? 모든 프로세서는 각기 다른 API 사양을 가지고 있으며, 오류 코드가 제각각이고, 문서화되지 않은 동작 차이가 존재하기 때문입니다. 작은 실수 하나가 비즈니스에 막대한 재정적 손실을 초래할 수 있습니다. Hyperswitch Prism은 이러한 '기업 내부 지식(Tribal Knowledge)'으로 갇혀 있던 결제 최적화 노하우를 전 세계 개발자들이 무료로 사용할 수 있도록 가볍고, 벤더 종속성이 없는 오픈소스 라이브러리로 제공합니다.

---

Hyperswitch Prism의 주요 특징 (Features)

Hyperswitch Prism은 단순한 연동 도구를 넘어 결제 시스템의 아키텍처를 혁신하는 다음과 같은 특징을 보유하고 있습니다.

1. 단일 요청 스키마 (Unified Schema)

Hyperswitch Prism을 사용하면 모든 결제에 대해 하나의 스키마만 사용하면 됩니다. 동일한 authorize 호출 코드가 Stripe, Adyen 등 다양한 프로세서에서 추가적인 코드 수정 없이 그대로 작동합니다.

2. 무상태성 (Stateless)

이 라이브러리는 데이터베이스를 사용하지 않으며, 개인 식별 정보(PII)를 저장하지 않습니다. 결제 수단 정보나 인증 자격 증명은 라이브러리에 의해 로깅되거나 저장되지 않으며, 오직 HTTP 클라이언트의 수명 주기 동안만 유지됩니다.

3. PCI 보안 범위 축소 (PCI Scope Reduction)

카드 데이터가 라이브러리를 통해 흐르게 할지 여부는 전적으로 사용자의 선택에 달려 있습니다. 결제 프로세서의 자체 보관함(Vault)이나 사용자의 PCI 인증 보관함을 자유롭게 활용할 수 있으며, Hyperswitch Prism 내에는 어떤 데이터도 기록되지 않아 보안 관리가 용이합니다.

4. 다양한 언어 SDK 지원

Hyperswitch Prism은 Rust로 작성되었지만, 다양한 환경에서 사용할 수 있도록 Node.js, Python, Java/Kotlin, Rust용 SDK를 제공합니다.

---

주요 사용 사례 (Use Case)

Hyperswitch Prism은 특히 다국적 결제 처리나 결제 다변화가 필요한 환경에서 빛을 발합니다.

• 결제 라우팅(Routing): 특정 통화나 지역에 따라 결제 프로세서를 실시간으로 전환해야 할 때 유용합니다. 예를 들어, USD 결제는 Stripe로, EUR 결제는 Adyen으로 처리하도록 단 몇 줄의 코드로 설정할 수 있습니다.
• 결제 프로세서 전환: 기존 프로세서의 장애나 수수료 정책 변경 시, 전체 시스템을 수정할 필요 없이 설정값만 변경하여 즉시 다른 프로세서로 전환할 수 있습니다.
• 멀티 프로세서 전략: 단일 프로세서에 대한 의존도를 낮추고 비즈니스 연속성을 확보하려는 기업에 최적입니다.

---

사용 방법 (How to Use)

Hyperswitch Prism을 시작하는 방법은 매우 간단하며, 각 언어별 패키지 관리자를 통해 즉시 설치할 수 있습니다.

1. 라이브러리 설치

• Node.js:

  npm install hyperswitch-prism
  

• Python:

  pip install hyperswitch-prism
  

• Java/Kotlin (Maven):

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

2. 결제 요청 예시 (Node.js)

다음은 Hyperswitch Prism을 사용하여 Stripe를 통해 결제를 승인하는 간단한 예제 코드입니다.

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

let config = {
    connectorConfig: {
        stripe: { apiKey: { value: "sk_test_..." } }
    }
};

const main = async () => {
    const client = new PaymentClient(config);
    const request = {
        merchantTransactionId: "auth_123",
        amount: { minorAmount: 1000, currency: types.Currency.USD },
        captureMethod: types.CaptureMethod.AUTOMATIC,
        paymentMethod: {
            card: {
                cardNumber: { value: "4111..." },
                cardExpMonth: { value: "12" },
                cardExpYear: { value: "2050" },
                cardCvc: { value: "123" },
                cardHolderName: { value: "Test User" },
            },
        },
        authType: types.AuthenticationType.NO_THREE_DS,
    };
    
    const response = await client.authorize(request);
    if (response.status === types.PaymentStatus.CHARGED) {
        console.log("결제 성공!");
    }
};

main();

3. 프로세서 간 라우팅

통화에 따라 프로세서를 변경하는 로직도 매우 직관적입니다.

Tip: 통화가 USD일 경우 Stripe를 사용하고, EUR일 경우 Adyen을 사용하도록 설정 파일(config)만 교체하면 됩니다. 나머지 호출 로직은 동일합니다.

---

자주 묻는 질문 (FAQ)

Q: Hyperswitch Prism은 자체 카드 보관함(Vault) 기능을 제공하나요?

A: 아니요, 이는 의도된 설계입니다. Hyperswitch Prism은 무상태 라이브러리로서 데이터 보관 기능을 포함하지 않습니다. 대신 결제 프로세서의 Vault나 사용자의 PCI 인증 Vault를 그대로 사용할 수 있습니다.

Q: 재시도(Retry)나 지능형 라우팅 로직이 포함되어 있나요?

A: Hyperswitch Prism은 순수한 변환 레이어(Transformation Layer) 역할에 집중합니다. 복잡한 재시도나 지능형 라우팅 로직이 필요하다면 상위 플랫폼인 Juspay Hyperswitch를 함께 사용하는 것이 권장됩니다.

Q: 결제 외에 구독이나 세금 계산 기능도 지원하나요?

A: 현재는 결제(Payments) 기능에 집중하고 있습니다. 향후 구독, 사기 방지, 세금, 정산 등을 아우르는 무상태 커머스 라이브러리로 진화할 계획을 가지고 있습니다.

Q: 지원되는 플랫폼과 아키텍처는 무엇인가요?

A: 현재 macOS (Apple Silicon, arm64) 및 Linux (x86_64) 환경을 위한 네이티브 라이브러리를 포함하고 있습니다.

---

Hyperswitch Prism은 복잡한 결제 생태계를 단순화하고, 개발자가 비즈니스 핵심 로직에 집중할 수 있도록 돕습니다. 지금 바로 Hyperswitch Prism 공식 문서를 방문하여 더 자세한 내용을 확인해 보세요.