@hello-pay/react

HelloPay 公式の React SDK。React アプリ内に任意のレイアウトでカード決済フォームを組み込める。

カード情報は HelloPay 配信の iframe に隔離されるため、PCI DSS SAQ A を維持したまま React コンポーネントとして UI を組み立てられる。

Install

npm install @hello-pay/react
# or: pnpm add @hello-pay/react / bun add @hello-pay/react

Usage

import {
  loadHelloPay,
  Elements,
  CardNumberElement,
  CardExpiryElement,
  CardCvcElement,
  CardholderNameElement,
  useHelloPay,
  useElements,
} from '@hello-pay/react';

// SDK のロードは module スコープで 1 回だけ（Stripe と同じ挙動）。
// SSR / Next.js でも安全に module top-level に置ける。
const helloPayPromise = loadHelloPay('pk_test_xxx');

export default function Checkout() {
  return (
    <Elements hellopay={helloPayPromise}>
      <PaymentForm />
    </Elements>
  );
}

function PaymentForm() {
  const hellopay = useHelloPay();
  const elements = useElements();

  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    if (!hellopay || !elements) return;

    const cardNumber = elements.getElement('cardNumber');
    const { token, card, error } = await hellopay.createToken(cardNumber);

    if (error) {
      // error.type は 'validation_error' | 'api_error' | 'config_error'
      showError(error.message);
      return;
    }
    // 以降は token / card が必ず non-null（Discriminated Union）
    await fetch('/api/charge', {
      method: 'POST',
      body: JSON.stringify({ token, last4: card.last4 }),
    });
  }

  return (
    <form onSubmit={handleSubmit}>
      <CardNumberElement />
      <CardExpiryElement />
      <CardCvcElement />
      <CardholderNameElement />
      <button type="submit">支払う</button>
    </form>
  );
}

Architecture

• コア SDK (hellopay-elements.js) は HelloPay の公式 CDN (js.hello-pay.app) から配信される。npm パッケージは ローダーと型定義のみを提供する（PCI DSS 要件）。
• 各 Element コンポーネントは 1 つの <div> を描画するだけで、カード情報の入力 iframe はコア SDK が差し込む。
• iframe 間通信は BroadcastChannel（同一オリジン）で行い、ホストページ側のコードは一切経由しない。
• トークン化は iframe 内で直接 HelloPay の API に POST する。