CrypaxDocs

@crypax/react

Crypax 결제 연동을 위한 React 훅 및 컴포넌트.

설치

$ npm install @crypax/react @crypax/node

설정

앱을 CrypaxProvider로 감싸세요. 모든 훅과 컴포넌트는 프로바이더 안에서 사용해야 합니다.

App.tsx
import { CrypaxProvider } from '@crypax/react';

function App() {
  return (
    <CrypaxProvider
      publishableKey="pk_live_..."
      options={{
        theme: 'dark',   // 'light' | 'dark' | 'auto'
        locale: 'ko',    // 'en' | 'ko'
        mode: 'wallet',  // 'wallet' | 'qr'
        chainId: 41956,
      }}
    >
      <YourApp />
    </CrypaxProvider>
  );
}
프롭타입설명
publishableKeystring공개 키 (pk_live_). 필수.
options.theme?"light" | "dark" | "auto"UI 테마: 'light' | 'dark' | 'auto'
options.locale?"en" | "ko"UI 언어: 'en' | 'ko'
options.mode?"wallet" | "qr"결제 모드: 'wallet' | 'qr'
options.chainId?number기본 체인 ID

컴포넌트

CheckoutButton

원클릭 결제 버튼. 내부적으로 confirmPayment를 호출하고 로딩/에러 상태를 관리합니다.

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

export default function App() {
  return (
    <CrypaxProvider publishableKey="pk_live_...">
      <CheckoutButton
        clientSecret={clientSecret}
        onSuccess={(result) => console.log('Paid!', result.txHash)}
        onCancel={() => console.log('Cancelled')}
        onError={(err) => console.error(err)}
      >
        Pay Now
      </CheckoutButton>
    </CrypaxProvider>
  );
}
프롭타입설명
clientSecretstring서버에서 받은 client secret (cs_live_...)
onSuccess?(result: PaymentResult) => void성공 시 PaymentResult와 함께 호출
onCancel?() => void사용자가 모달을 닫을 때 호출
onError?(err: Error) => void실패 시 Error와 함께 호출

PaymentElement

인라인으로 렌더링되는 임베드형 결제 UI.

PaymentForm.tsx
import { PaymentElement } from '@crypax/react';

function PaymentForm({ clientSecret }: { clientSecret: string }) {
  return (
    <PaymentElement
      clientSecret={clientSecret}
      onSuccess={(result) => console.log('txHash:', result.txHash)}
      onError={(err) => console.error(err)}
    />
  );
}

PaymentStatusBadge

실시간 결제 상태 배지. 주기적으로 상태를 폴링하여 자동 업데이트합니다.

import { PaymentStatusBadge } from '@crypax/react';

<PaymentStatusBadge clientSecret="cs_live_..." />

훅

useCrypax()

CrypaxProvider가 초기화한 Crypax 클라이언트 인스턴스를 반환합니다.

import { useCrypax } from '@crypax/react';

function MyComponent() {
  const crypax = useCrypax();
  // crypax is the Crypax client instance
}

useConfirmPayment()

결제 확인을 위한 훅. 지갑 상호작용, 상태, 에러를 관리합니다.

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

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

  const handlePay = async () => {
    const res = await confirmPayment(clientSecret);
    if (res.status === 'confirmed') {
      console.log('txHash:', res.txHash);
    }
  };

  return (
    <div>
      <button onClick={handlePay} disabled={status !== 'idle'}>
        {status === 'idle' ? 'Pay Now' : status}
      </button>
      {error && <p className="error">{error.message}</p>}
      {status !== 'idle' && <button onClick={reset}>Reset</button>}
    </div>
  );
}
반환값타입설명
confirmPayment(clientSecret: string) => Promise<PaymentResult>주어진 client secret으로 결제 플로우를 트리거합니다.
status"idle" | "processing" | "confirmed" | "failed"현재 상태: 'idle' | 'processing' | 'confirmed' | 'failed'
resultPaymentResult | null확인 후 PaymentResult 객체 (완료 전까지 null).
errorError | null결제 실패 시 에러 객체, 아니면 null.
reset() => voidstatus와 error를 idle로 초기화합니다.

useWallet()

사용자 지갑을 감지하고 상호작용하기 위한 훅.

WalletInfo.tsx
import { useWallet } from '@crypax/react';

function WalletInfo() {
  const { wallet, loading, detect } = useWallet();

  if (loading) return <p>Detecting wallet...</p>;

  return (
    <div>
      {wallet ? (
        <>
          <p>Address: {wallet.address}</p>
          <p>Chain ID: {wallet.chainId}</p>
        </>
      ) : (
        <button onClick={detect}>Detect Wallet</button>
      )}
    </div>
  );
}
반환값타입설명
wallet{ address: string; chainId: number; provider: any } | null감지된 지갑 객체 (address, chainId, provider).
loadingboolean지갑 감지 중일 때 true.
detect() => void지갑 감지를 수동으로 재실행합니다.

usePaymentStatus(clientSecret)

client secret으로 결제 상태를 폴링하여 반환합니다.

import { usePaymentStatus } from '@crypax/react';

function StatusDisplay({ clientSecret }: { clientSecret: string }) {
  const { status, payment, loading, error } = usePaymentStatus(clientSecret);

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return <p>Status: {status}</p>;
}
반환값타입설명
statusstring | null현재 결제 상태 문자열.
paymentPayment | null전체 payment 객체.
loadingboolean로딩 중일 때 true.
errorError | null요청 실패 시 에러.

useChains()

Crypax API에서 지원 체인 목록을 가져옵니다.

import { useChains } from '@crypax/react';

function ChainList() {
  const { chains, loading, error } = useChains();

  if (loading) return <p>Loading chains...</p>;

  return (
    <ul>
      {chains.map((chain) => (
        <li key={chain.chainId}>{chain.name} ({chain.chainId})</li>
      ))}
    </ul>
  );
}

전체 예제

PaymentPage.tsx
import { CrypaxProvider, CheckoutButton } from '@crypax/react';

// Server-side: create payment and pass clientSecret as prop
export default function App({ clientSecret }: { clientSecret: string }) {
  return (
    <CrypaxProvider publishableKey="pk_live_...">
      <CheckoutButton
        clientSecret={clientSecret}
        onSuccess={(result) => {
          console.log('Payment confirmed! tx:', result.txHash);
        }}
        onCancel={() => console.log('User cancelled')}
        onError={(err) => console.error('Payment failed:', err)}
      >
        Pay Now
      </CheckoutButton>
    </CrypaxProvider>
  );
}
Vue SDK →Node.js SDK →API 레퍼런스 →
React SDK | Crypax