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/reactUsage
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 を参照。