CrypaxDocs

개요

Crypax는 암호화폐 결제 게이트웨이입니다. SDK와 REST API를 사용하여 암호화폐 결제를 서비스에 연동하세요.

Crypax란?

Crypax는 Stripe의 PaymentIntent 패턴과 동일한 방식으로 동작합니다. 서버에서 비밀 키로 결제를 생성하고, 클라이언트에서 공개 키로 확인합니다. client secret은 프론트엔드가 비밀 키 노출 없이 결제를 완료할 수 있게 해주는 단기 토큰입니다.

핵심 개념

API 키

각 계정에는 두 종류의 키가 있습니다. 비밀 키(sk_live_)는 서버에서만 사용합니다. 공개 키(pk_live_)는 클라이언트 코드에 노출해도 안전합니다.

키 종류접두사사용처
비밀 키sk_live_서버 전용 — 결제 생성/조회, 웹훅 검증
공개 키pk_live_클라이언트 — SDK로 결제 확인

결제 상태 흐름

결제는 다음 상태를 거칩니다: created → processing (txHash 제출) → confirmed (온체인 검증). expiresAt 이전에 확인되지 않으면 expired가 됩니다. 검증 실패 시 failed가 됩니다.

Client Secret 패턴

서버에서 결제를 생성하면 응답에 clientSecret(cs_live_ 접두사)이 포함됩니다. 이를 프론트엔드에 전달하세요 — 특정 결제 확인에만 사용 가능하므로 노출되어도 안전합니다. SDK는 이를 사용하여 결제 모달을 열고 트랜잭션을 제출합니다.

웹훅 이벤트

결제 상태가 변경될 때 Crypax가 웹훅 URL로 서명된 POST 요청을 보냅니다. 이벤트 종류: payment.created, payment.confirmed, payment.expired, payment.failed. HMAC-SHA256으로 x-crypax-signature 헤더를 반드시 검증하세요.

SDK 패키지

Crypax는 4가지 패키지를 제공합니다. 사용 환경에 맞는 패키지를 선택하세요.

@crypax/jsBrowser

코어 브라우저 SDK. ShadowDOM 결제 모달, 프레임워크 의존성 없음.

@crypax/reactReact

React 훅 및 컴포넌트. CrypaxProvider, useConfirmPayment, useWallet, CheckoutButton.

@crypax/vueVue

Vue 컴포저블 및 컴포넌트. CrypaxPlugin, useConfirmPayment, useWallet, CheckoutButton.

@crypax/nodeNode.js

서버 사이드 SDK. 결제 생성/관리, 웹훅 검증.

설치

$ npm install @crypax/react

코드 예제

서버에서 생성하고 클라이언트에서 확인하는 완전한 결제 플로우입니다.

서버 (Node.js)

server.ts
import { Crypax, PLUMISE_MAINNET } from '@crypax/node';

const crypax = new Crypax('sk_live_your_secret_key', {
  apiUrl: 'https:0
});

const payment = await crypax.payments.create({
  amount: '1.0',
  recipientAddress: '0xYourWalletAddress',
  chainId: PLUMISE_MAINNET.chainId,  1
  currency: 'native',
  orderId: 'order_123',
  description: 'Premium Plan',
  expiresInMinutes: 30,
});

// payment.clientSecret → send to frontend

클라이언트

Checkout.tsx
import { CrypaxProvider, useConfirmPayment } from '@crypax/react';

function App() {
  return (
    <CrypaxProvider publishableKey="pk_live_your_key">
      <Checkout clientSecret="cs_live_..." />
    </CrypaxProvider>
  );
}

function Checkout({ clientSecret }: { clientSecret: string }) {
  const { confirmPayment, status } = useConfirmPayment();

  return (
    <button
      onClick={() => confirmPayment(clientSecret)}
      disabled={status !== 'idle'}
    >
      {status === 'idle' ? 'Pay Now' : status}
    </button>
  );
}
Quick Start →React SDK →API 레퍼런스 →웹훅 →
문서 | Crypax