JSPM

@hello-pay/react

0.2.0
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 2948
  • Score
    100M100P100Q109309F
  • License UNLICENSED

HelloPay Elements React bindings (custom card form for merchants)

Package Exports

  • @hello-pay/react

Readme

@hello-pay/react

HelloPay Elements の React バインディング。加盟店ページ上で任意のレイアウトのカード入力フォームを構築できる。

実体のカード情報は HelloPay 管理ドメイン (js.hello-pay.app) から配信される 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>
  );
}

Scripts

Script 内容
bun run build tsup で dist/ に ESM + CJS + .d.ts を出力
bun run demo ローカル demo サーバー (http://localhost:18901) を起動。先に just dev が必要
bun run typecheck 型チェックのみ(tsc --noEmit
bun run test bun test 実行

Demo

# ターミナル1
just dev   # HelloPay サーバー起動(js.lvh.me / api.lvh.me / cde.lvh.me を公開)

# ターミナル2
cd js_sdk/react && bun run demo
open http://localhost:18901

.dev-ports からサーバーポートを自動検出するため、worktree を跨いで設定不要で動作する。

Architecture

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

より詳細な設計は public_docs/src/content/docs/integration/custom-form.md を参照。