支付集成与组件

API 密钥（X-API-Key）绝不能出现在 HTML、客户端 JavaScript、浏览器日志或 URL 参数中。

1. 银行目录

您可以从后端直接查询金融机构端点，获取可用银行及其标识、名称和要求。每个机构包含两个标识：logo 是 Wealth Reader 推荐展示的版本（有自有矢量标识时使用它，否则使用供应商标识，由 logo_source 指示）；logo_fallback 是供应商标识，供界面在前者无法加载时使用：

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

此端点公开：不要发送 X-API-Key。发送密钥不会改变响应，却会消耗一次调用额度；如果账户禁用了支付，还会使原本成功的查询变成 503。

还支持以下可选查询参数：

• country：两位 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。

方式 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'
});

组件使用一次性 token 直接从 Wealth Reader 服务器获取配置。如果银行要求在重定向前识别扣款账户，组件会直接向付款人索取该账户的 IBAN，无需商户处理。

组件的主要事件

下一步

请阅读支付意图与幂等性。