JavaScript / ブラウザ SDK

@lartech/infraio-checkout-js は現在公開している唯一の SDK です。 ブラウザで動作し、ホスト型チェックアウトを開きます。バックエンド SDK (Node、Go、Python) はロードマップ上にあります; それまでの間は ゲートウェイに直接通信してください — HMAC 署名ヘルパーは クイックスタート を参照してください。

• 現在のバージョン: 0.1.1-beta.17 (1.0 未満; マイナーな破壊的変更があり得ます)
• フォーマット: ESM (index.js)、CJS (index.cjs)、IIFE (index.global.js)
• 型定義同梱 (index.d.ts)
• ランタイム依存ゼロ — React、jQuery などの依存なし

インストール

npm install @lartech/infraio-checkout-js

pnpm add @lartech/infraio-checkout-js

yarn add @lartech/infraio-checkout-js

bun add @lartech/infraio-checkout-js

<script src="https://unpkg.com/@lartech/infraio-checkout-js/dist/index.global.js"></script>
<script>
  const sdk = await InfraIo.loadInfraIo("pk_live_yourkeyhere");
  sdk.checkout({ sessionId, checkoutUrl });
</script>

loadInfraIo(publicKey, options?)

Promise<InfraIoInstance> を返します。

import { loadInfraIo } from "@lartech/infraio-checkout-js";
 
const sdk = await loadInfraIo("pk_live_yourkeyhere", {
  // 任意。本番以外の環境を指す場合のみ上書きしてください。
  checkoutUrl: "https://checkout-dev.infraio.xyz",
});

sdk.checkout({ … })

ホスト型チェックアウトを開きます。void を返します (状態はコールバックで取得)。

sdk.close()

開いている popup または embed をプログラムから閉じます。redirect モードでは何もしません。

sdk.checkout({ sessionId, mode: "popup", /* … */ });
// 後で、たとえばユーザーがページ遷移するときに
sdk.close();

sdk.openRefundRequest({ … })

バックエンドが POST /b2b/v1/merchants/{merchant_id}/refund-requests で発行したワンタイムトークン向けに、ホスト型の 返金リクエスト フォーム を開きます。バイヤーは弊社のページで返金先アドレス + 理由 + (任意の) メタデータを入力します; あなたのページは開閉のライフサイクルを 扱うだけです。close() 関数 を返します — 呼び出すと popup を プログラムから閉じる、または embed iframe をデタッチします。redirect モードでは返される関数は何もしません。

import { loadInfraIo } from "@lartech/infraio-checkout-js";
 
const sdk = await loadInfraIo("pk_live_yourkeyhere");
 
// トークンをサーバー側で発行し、ブラウザの SDK に渡します。
const { token } = await fetch("/api/mint-refund-token", { method: "POST" }).then(r => r.json());
 
const close = sdk.openRefundRequest({
  token,
  mode: "popup",
  onSuccess: ({ linkToken, refundId }) => {
    // バイヤーがフォームを送信しました。
    // linkToken → /r/:linkToken ステータスページ (バイヤーと共有)。
    // refundId  → B2B API で承認 / 拒否に使用。
    window.location.href = `/r/${linkToken}`;
  },
  onCancel: () => { /* バイヤーが送信せずに閉じた */ },
});
 
// 必要に応じて後で popup をプログラムから閉じる:
// close();

onError で表面化するトークン状態

バイヤーが古いトークンを開いた場合、ページ自体が表示を処理し (「期限切れ — 新しいリンクをリクエスト」のプロンプトなど)、SDK は そのケースで onError を 発火しません — バイヤーはフォームフロー内に おり、あなたのコードは反応する必要がありません。onError は、あなたの コードが対処できることだけに発火します (不正な引数、iframe を読み込む ネットワーク障害)。

エラークラス

import { InfraIoError } from "@lartech/infraio-checkout-js";
 
sdk.checkout({
  sessionId,
  onError: (err: InfraIoError) => {
    switch (err.code) {
      case "invalid_request_error":   /* 不正な sessionId / 引数 */ break;
      case "iframe_load_error":       /* iframe ロード失敗 */ break;
      case "iframe_timeout_error":    /* timeoutMs を超過 */ break;
      case "already_open_error":      /* 別のチェックアウトが既に開いている */ break;
      case "network_error":           /* チェックアウト origin との通信での一時的なネットワーク障害 */ break;
      case "api_error":               /* SDK が発行した呼び出しに対しバックエンドが non-2xx を返した */ break;
    }
  },
});

sdk.openRefundRequest() は invalid_request_error (トークン / 引数の 欠落または不正) のみを同期的に throw します。iframe_load_error (返金リクエスト iframe のロード失敗) は onError 経由で非同期に 配信され、throw はされません。iframe_timeout_error や already_open_error は 発火しません — 返金リクエストの popup には ロードタイムアウトはなく、複数の popup を同時に開けます。

モードの注意点

Popup

• 中央寄せのオーバーレイ、半透明の暗い背景
• z-index: 2147483647 (int32 最大値) — 他のすべての上に乗ります
• 開いている間は body のスクロールがロックされ、閉じると復元されます
• 閉じるボタンが初期フォーカスを取得; Tab は popup 内にトラップ
• 閉じる手段: 閉じるボタン、Escape、外側クリック、sdk.close()。 これらすべてが onCancel を呼び出します
• チェックアウトページは postMessage でリサイズを要求できます — SDK は width/height の制限内にクランプします

Redirect

• window.location.href によるハードナビゲーション
• 自動的に ?return_url=<current-page> を付加するので、バイヤーが 来た場所に戻れます。セッションの success_url / cancel_url が 既にこれをカバーしている場合、往復は return_url を無視します

Embed

• allow="payment; clipboard-write" (HTML5 Feature Policy ディレクティブ — sandbox 属性ではありません) の iframe。iframe はチェックアウトの origin から配信されるため、ウォレット popup とクリップボード書き込みは バイヤー側からそれ以上のオプトインなしに動作します。
• コンテナ幅は 100%、高さは INFRAIO_RESIZE postMessage で自動サイズ調整、 [200, 2000]px にクランプ
• iframe 境界を越える CSS の分離はありません — 親ページのスタイルが 入り込むことはありません
• チェックアウトがインタラクティブになったときに自前のローディング状態を 隠せるよう、必ず onReady を結線してください

TypeScript

すべての型は同梱されています。よく使うエクスポート:

import type {
  CheckoutOptions,
  RefundRequestOptions,
  LoadOptions,
  InfraIoInstance,
  InfraIoErrorCode,
} from "@lartech/infraio-checkout-js";
import { loadInfraIo, InfraIoError, VERSION } from "@lartech/infraio-checkout-js";

VERSION は SDK 自身のバージョン文字列です — バグレポートに便利です。

次に

• React / Vue フレームワークラッパー — パイロットマーチャント間で バニラ JS サーフェスが安定したら、ローンチ後のイテレーションで予定。 バニラ SDK は React 内でも問題なく動作します; ラッパーは手動の useRef + ライフサイクル配線を省略するだけです。
• タブ間セッション再開 — タブ A でチェックアウトを開き、タブ B で 完了。バイヤーが流れの途中でマジックリンクをフォローしたときに便利です。 次のマイナーリリースで追跡中。
• CSS 変数によるテーマ設定 — iframe に小さなデザイントークン群 (半径、アクセントカラー) を公開し、マーチャントがページをフォークせずに ブランドに合わせられるようにします。
• サーバーサイドヘルパー — 小さな @lartech/infraio-server パッケージで verifyWebhook() + signedRequest() を公開し、バックエンドコードが HMAC の儀式をコピーする必要をなくします。出荷までの間は 署名検証ページ に TypeScript、 Go、Python、Ruby のドロップイン実装があります。