決済連携とウィジェット

API キー（X-API-Key）を HTML、クライアント側 JavaScript、ブラウザーのログ、URL パラメーターに含めてはいけません。

1. 銀行ディレクトリ

利用可能な銀行とそのロゴ、名称、要件は、バックエンドから金融機関エンドポイントを直接照会して取得できます。各金融機関には 2 つのロゴがあります。logo は Wealth Reader が表示を推奨するロゴです（自社のベクターロゴがあればそれを、なければプロバイダーのロゴを使用し、logo_source で判別します）。logo_fallback はプロバイダーのロゴで、最初のロゴを読み込めない場合に使用します。

curl --request GET 'https://api.wealthreader.com/payments/entities/?country=ES'

このエンドポイントは公開されています。X-API-Key を送信しないでください。送信しても応答は変わらず、呼び出し枠を 1 回消費します。さらに、アカウントで決済が無効なら、本来成功する照会が 503 になります。

次の任意のクエリパラメーターも使用できます。

• country: 2 文字の ISO 国コード（ES、FR、DE、IT、PT など）。ALL または空なら国で絞り込みません。
• search（別名 q）: 名前またはコードの文字列検索（santander、bbva など）。
• code: 完全一致するコードで特定の金融機関を取得します。
• payment_method: 対応する方法で絞り込みます（sepa_credit_transfer など）。
• limit と offset: 結果のページング。

省略した応答例:

{
  "success": true,
  "total": 2,
  "entities": [
    {
      "code": "santander-es",
      "name": "Banco Santander",
      "country": "ES",
      "logo": "https://cdn.wealthreader.com/santander.svg",
      "logo_fallback": "https://assets.exthand.com/bsdk/banks/logos/ES/santander.svg",
      "logo_source": "wealthreader",
      "payment_methods": ["sepa_credit_transfer", "instant_sepa_credit_transfer"],
      "requires_debtor_iban": true
    },
    {
      "code": "bbva-es",
      "name": "BBVA",
      "country": "ES",
      "logo": "https://cdn.wealthreader.com/bbva.svg",
      "logo_fallback": "https://assets.exthand.com/bsdk/banks/logos/PT/bbva.svg",
      "logo_source": "wealthreader",
      "payment_methods": ["sepa_credit_transfer", "instant_sepa_credit_transfer"],
      "requires_debtor_iban": false
    }
  ]
}

ロゴを表示し、読み込み失敗時に自動で代替する推奨パターン:

<img src="https://cdn.wealthreader.com/santander.svg"
     data-fallback="https://assets.exthand.com/bsdk/banks/logos/ES/santander.svg"
     alt="Banco Santander" width="160" height="48"
     onerror="if (this.dataset.fallback && this.src !== this.dataset.fallback) { this.src = this.dataset.fallback; } else { this.hidden = true; }">

/payments/entities/ では両フィールドが常に存在し、ロゴがなければ null です。POST /payments/?action=profile-institutions とウィジェットの金融機関情報にも同じ logo と logo_fallback がありますが、任意項目のため、使用可能なロゴがない場合は含まれません。ロゴの参照先は cdn.wealthreader.com または assets.exthand.com のみです。ページで CSP を使用する場合は、両ホストを img-src に追加してください。

管理対象プロファイル（寄付デモなど）: cruz_roja_demo のような設定済みプロファイルを使用する場合は、POST /payments/?action=profile-institutions を呼び出し、本文に {"profile": "cruz_roja_demo"} を指定して、サーバーが定めた金融機関と条件を取得します。

2. バックエンドで決済インテントを作成する

顧客がチェックアウトで支払いを選ぶと、サーバーが一意の冪等性キーを生成し、Wealth Reader API に変更不能な決済の作成を要求します。

加盟店向け標準モデル（受取人を自社で指定）

加盟店は入金先口座、セント単位の金額（amount_minor）、決済参照、ウィジェットを読み込む Web オリジンを指定します。

: "${WR_API_KEY:?Defina WR_API_KEY en el entorno seguro de su backend}"
: "${WR_PAYMENT_IDEMPOTENCY_KEY:?Genere una clave UUID v4 o de alta entropía para este intento}"

curl --request POST 'https://api.wealthreader.com/payments/?action=create' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${WR_API_KEY}" \
  --header "Idempotency-Key: ${WR_PAYMENT_IDEMPOTENCY_KEY}" \
  --data '{
    "amount_minor": 1500,
    "currency": "EUR",
    "beneficiary": {
      "name": "Comercio Online S.L.",
      "iban": "ES9121000418450200051332"
    },
    "reference": "Pedido #78901",
    "customer_reference": "pedido-78901",
    "allowed_origin": "https://tienda.example.com",
    "allowed_institution_codes": ["santander-es", "bbva-es", "caixabank-es", "sabadell-es"],
    "locale": "es"
  }'

注: allowed_institution_codes は任意です。省略すると、ユーザーはカタログ内のすべての金融機関から選択できます。

管理対象プロファイルのモデル（寄付デモ）

管理対象プロファイル cruz_roja_demo を連携する場合:

curl --request POST 'https://api.wealthreader.com/payments/?action=create' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${WR_API_KEY}" \
  --header "Idempotency-Key: ${WR_PAYMENT_IDEMPOTENCY_KEY}" \
  --data '{
    "profile": "cruz_roja_demo",
    "institution_code": "santander-es",
    "amount_minor": 100,
    "customer_reference": "donativo-demo-0042",
    "allowed_origin": "https://tienda.example.com",
    "locale": "es",
    "expected_mode": "live"
  }'

API の応答

API は変更不能なインテントの作成を確認し、ウィジェットの初期化に必要なデータを返します。

{
  "success": true,
  "payment": {
    "id": "11111111-1111-4111-8111-111111111111",
    "amount_minor": 1500,
    "currency": "EUR",
    "state": "ready",
    "interaction_status": "not_started",
    "payment_status": "not_initiated",
    "payment_attestation": {
      "mode": "live",
      "provider_binding": "PROVIDER_BINDING"
    },
    "widget": {
      "url": "https://widget.wealthreader.com/payments/",
      "token": "SHORT_LIVED_WIDGET_TOKEN",
      "expires_at": "2026-09-04T15:30:00+00:00"
    }
  }
}

バックエンドがユーザーのブラウザーに渡すのは、payment.id と payment.widget.token のみです。

3. フロントエンドにウィジェットを組み込む

Web 画面への組み込み方法は、公式の宣言的スクリプトと、プログラムから使用する JavaScript API の 2 つです。

方法 A: 宣言的スクリプト（load-payments.js）

チェックアウトページにコンテナーとローダーを埋め込みます。

<div id="wr-payment-container"></div>

<script>
  document.querySelector('#wr-payment-container').addEventListener(
    'wealthreader:payment',
    (event) => {
      console.log('Evento de pago recibido:', event.detail.type, event.detail);

      if (event.detail.type === 'payment_status') {
        console.log('Estado actual:', event.detail.status);
      }

      if (event.detail.type === 'flow_closed') {
        // La interacción del usuario ha finalizado.
        // Consulte el estado financiero definitivo desde su backend.
      }
    }
  );
</script>

<script
  src="https://widget.wealthreader.com/js/load-payments.js"
  data-target="#wr-payment-container"
  data-payment-intent-id="11111111-1111-4111-8111-111111111111"
  data-widget-token="SHORT_LIVED_WIDGET_TOKEN"
  data-locale="es">
</script>

方法 B: JavaScript API（WealthReaderPayments.mount）

React、Vue、Angular などのフレームワークや SPA フローを使用する場合:

import { useEffect, useRef } from 'react';

// Cargue previamente https://widget.wealthreader.com/js/load-payments.js
const target = document.getElementById('wr-payment-container');

// Los eventos llegan como CustomEvent del DOM sobre el propio contenedor.
target.addEventListener('wealthreader:payment', (event) => {
  const detail = event.detail;
  if (detail.type === 'payment_status') {
    console.log('Estado del pago:', detail.status);
  }
  if (detail.type === 'flow_closed') {
    // Notificar al backend para comprobar la liquidación
  }
});

window.WealthReaderPayments.mount({
  target: target,
  paymentIntentId: '11111111-1111-4111-8111-111111111111',
  widgetToken: 'SHORT_LIVED_WIDGET_TOKEN',
  locale: 'es'
});

ウィジェットは、1 回のみ使用可能なトークンを使い、Wealth Reader のサーバーから直接設定を取得します。銀行がリダイレクト前に引落口座の特定を要求する場合、ウィジェットが支払人に直接 IBAN を入力させます。加盟店が処理する必要はありません。

ウィジェットの主なイベント

次の手順

インテントと冪等性を確認してください。