銀行・支店選択フォームを組み込むWidget

概要

銀行・支店選択ウィジェットは、銀行名・支店名の検索と選択UIを提供するWeb Componentです。

UIはShadow DOM内に描画されます。name-prefixを指定した場合は、フォーム送信用のhidden inputをcustom elementのLight DOM直下に生成します。

フォーム送信、確認画面、最終確定ボタン、入力値の保存処理は、呼び出し元サイト側で実装します。

• 銀行・支店選択UIを自前実装せずに組み込める
• API Keyをブラウザに埋め込まない
• Public ClientのPublic Keyを利用する
• 選択結果はhidden inputまたはイベントで取得できる
• inline表示とdialog表示に対応する

Search API / Resolve API β との違い

配信URL

scriptタグでウィジェット本体を読み込みます。

<script src="https://js.bankcode-jp.com/widgets/bank-branch-selector/v1/bank-branch-selector.js"></script>

• v1 はメジャーバージョン固定のURLです。
• 互換性を重視する場合は、固定バージョンURLの利用も検討できます。

現在公開中のバージョン

通常は v1 のメジャー alias を利用してください。 v1.0.0 のような固定バージョンURLは、特定バージョンに固定したい場合に利用します。

現在、v1 は v1.0.0 と同一内容です。

Quick Start

public-keyには、ダッシュボードで作成したPublic ClientのPublic Keyを指定します。API Keyはブラウザに埋め込まないでください。

<script src="https://js.bankcode-jp.com/widgets/bank-branch-selector/v1/bank-branch-selector.js"></script>

<bankcodejp-bank-branch-selector
  public-key="YOUR_PUBLIC_KEY"
  name-prefix="bank_account"
  display-mode="dialog"
  search-mode-switch="fallback">
</bankcodejp-bank-branch-selector>

<script>
  document
    .querySelector("bankcodejp-bank-branch-selector")
    .addEventListener("bcjp:select", (event) => {
      console.log(event.detail);
    });
</script>

• public-keyにはPublic ClientのPublic Keyを指定します。
• API Keyをブラウザに埋め込まないでください。
• name-prefixを指定するとhidden inputが生成されます。
• 推奨設定では、フォーム上には選択ボタンと選択結果だけを表示し、検索UIはダイアログ内に表示します。
• 銀行名・銀行コードでの検索を主導線にし、頭文字検索は補助導線として利用できます。

表示方式

inline

display-mode未指定時の初期表示です。フォーム内に銀行・支店選択UIをそのまま表示します。

<bankcodejp-bank-branch-selector
  public-key="YOUR_PUBLIC_KEY"
  name-prefix="bank_account">
</bankcodejp-bank-branch-selector>

dialog

display-mode="dialog" を指定すると、選択UIをdialogで表示できます。長いフォームやスマートフォン画面でフォームの高さを抑えたい場合に向いています。

<bankcodejp-bank-branch-selector
  public-key="YOUR_PUBLIC_KEY"
  name-prefix="bank_account"
  display-mode="dialog"
  search-mode-switch="fallback">
</bankcodejp-bank-branch-selector>

manual trigger

trigger-mode="manual" を指定すると、ウィジェット側の自動triggerを使わず、任意のボタンからopen()でdialogを開けます。

<button type="button" id="open-bank-selector">
  金融機関・支店を選択
</button>

<bankcodejp-bank-branch-selector
  id="bank-selector"
  public-key="YOUR_PUBLIC_KEY"
  name-prefix="bank_account"
  display-mode="dialog"
  trigger-mode="manual">
</bankcodejp-bank-branch-selector>

<script>
  const selector = document.getElementById("bank-selector");

  document.getElementById("open-bank-selector").addEventListener("click", () => {
    selector.open();
  });
</script>

検索UIの表示方式

search-mode-switch で、検索方式切替UIの見せ方を変更できます。

<bankcodejp-bank-branch-selector
  public-key="YOUR_PUBLIC_KEY"
  name-prefix="bank_account"
  display-mode="dialog"
  search-mode-switch="fallback">
</bankcodejp-bank-branch-selector>

属性一覧

allowed-business-type-codes には、5桁の金融機関種別コードをカンマ区切りで指定します。

Methods

const selector = document.querySelector("bankcodejp-bank-branch-selector");

selector.open();
selector.close();
selector.reset();

const value = selector.getValue();

getValue() は銀行・支店が選択済みの場合に選択内容を返します。未選択の場合は null を返します。

フォーム送信値

name-prefixを指定すると、フォーム送信用のhidden inputをcustom elementのLight DOM直下に生成します。

<bankcodejp-bank-branch-selector
  public-key="YOUR_PUBLIC_KEY"
  name-prefix="bank_account">
</bankcodejp-bank-branch-selector>

生成例です。

<input type="hidden" name="bank_account[bank_code]" value="0001">
<input type="hidden" name="bank_account[bank_name]" value="みずほ銀行">
<input type="hidden" name="bank_account[branch_code]" value="001">
<input type="hidden" name="bank_account[branch_name]" value="本店">

• hidden inputはShadow DOM内ではなく、custom elementのLight DOM直下に生成されます。
• 未選択時は空文字です。
• 銀行選択時は bank_code / bank_name を更新し、branch_code / branch_name を空に戻します。
• 支店選択完了時に4項目すべてを更新します。

Events

すべてのイベントは bubbles: true / composed: true でdispatchされます。外部出力は snake_case です。

bcjp:bank-select

銀行選択時に発火します。

{
  "bank_code": "0001",
  "bank_name": "みずほ銀行",
  "bank_hiragana": "みずほぎんこう"
}

bcjp:select

支店まで選択されたときに発火します。

{
  "bank_code": "0001",
  "bank_name": "みずほ銀行",
  "bank_hiragana": "みずほぎんこう",
  "branch_code": "001",
  "branch_name": "本店",
  "branch_hiragana": "ほんてん"
}

bcjp:open / bcjp:close

dialogが開いたとき、閉じたときに発火します。

bcjp:error

エラー発生時に発火します。

{
  "code": "rate_limited",
  "message": "銀行・支店候補を取得できませんでした。しばらくしてから再度お試しください。",
  "status": 429
}

HTTPレスポンス由来のエラーでは detail.status にHTTP status codeが含まれます。ローカル設定エラーなどHTTPレスポンス由来でない場合は、status が含まれない場合があります。

const selector = document.querySelector("bankcodejp-bank-branch-selector");

selector.addEventListener("bcjp:select", (event) => {
  console.log(event.detail.bank_code);
  console.log(event.detail.branch_code);
});

selector.addEventListener("bcjp:error", (event) => {
  console.warn(event.detail.code, event.detail.status);
});

エラー表示と bcjp:error

銀行・支店選択ウィジェットでは、フォーム利用者向けには分かりやすいメッセージを表示し、導入先サイト向けには bcjp:error イベントで詳細を通知します。

エンドユーザー向け画面表示では、Public Client、Origin、HTTP 429などの技術用語を直接表示しません。導入先サイト側では bcjp:error の detail.code / detail.status を使ってログ記録や独自表示を行えます。

認証

Bank Branch Selector Widget は、API Key ではなく Public Client の Public Key を使います。

Public Key は、ダッシュボードの Public Client 画面から作成・取得できます。取得した Public Key を public-key 属性に設定すると、Widget が短期 access token の取得と銀行・支店候補の取得を自動で行います。

<bankcodejp-bank-branch-selector
  public-key="YOUR_PUBLIC_KEY"
  name-prefix="bank_account"
  display-mode="dialog"
  search-mode-switch="fallback">
</bankcodejp-bank-branch-selector>

内部的な動作

Widget は内部的に短期 access token を取得し、Widget 用の public route から銀行・支店候補を取得します。通常の導入では、これらのrouteを直接呼び出す必要はありません。

POST /public/v1/sessions
GET /public/v1/bank-branch-selector/banks
GET /public/v1/bank-branch-selector/banks/{bankCode}/branches
GET /public/v1/bank-branch-selector/freeword/banks
GET /public/v1/bank-branch-selector/freeword/banks/{bankCode}/branches

利用上限

銀行・支店選択ウィジェットは、Search APIとは独立して利用プランを有効化できるサービスです。

利用プランごとにリクエスト上限・レート制限があります。利用上限やレート制限を超えた場合、銀行・支店候補の取得が一時的にできなくなる場合があります。

その場合、画面上は候補取得に失敗した旨のメッセージを表示し、bcjp:error で code: "rate_limited" を通知します。HTTPレスポンス由来であれば detail.status に 429 が含まれます。

よくある実装パターン

• 通常フォームにinlineで埋め込む
• 長いフォームやスマホ向けフォームではdialog modeを使う
• 自前ボタンで開きたい場合は trigger-mode="manual" と open() を使う
• フォーム送信時は hidden input を利用する
• SPA / React / Vue / Angular では DOM element を取得して addEventListener でイベント購読する
• エラー監視や独自表示は bcjp:error を購読して実装する

関連ページ