支付

使用 Wealth Reader 进行支付

Wealth Reader 支持从后端准备不可更改的付款指令，并在专用的安全组件中完成银行授权（PSD2 / PIS - Payment Initiation Services）。API 凭据、敏感的收款账户和内部连接详情绝不会传给浏览器。

确定性沙盒可让您在不转移真实资金的情况下完成集成，但它不是通过参数启用的：沙盒是单独的部署，具有自己的基础 URL 和凭据，Wealth Reader 可应要求提供（参见安全与测试）。沙盒中的 profile-institutions 只返回一个模拟金融机构。expected_mode 不会切换环境，只会核对请求是否指向预期环境；不匹配时返回 409 payment_mode_mismatch。

银行支持数据聚合并不意味着同样支持支付发起。在生产环境中，Wealth Reader 的金融机构目录覆盖西班牙及整个欧洲。

两步架构

支付集成通过两个步骤严格分离职责：

sequenceDiagram
autonumber
actor Usuario as 用户
participant Front as 前端（商户）
participant Back as 后端（商户）
participant API as Wealth Reader API
participant Widget as 支付组件
participant Banco as 银行（SCA）
Note over Back,API: 预备步骤（仅托管配置）
Back->>API: POST /payments/?action=profile-institutions
API-->>Back: 配置对应的目录（institution_code）
Note over Back,API: 步骤1：创建不可更改的支付意图（Server-to-Server）
Back->>API: POST /payments/?action=create（使用X-API-Key和Idempotency-Key）
API-->>Back: 201及payment.id + 短期payment.widget.token
Note over Front,Widget: 步骤2：加载组件并授权（浏览器）
Back->>Front: 传递payment.id和payment.widget.token
Front->>Widget: WealthReaderPayments.mount(...)或load-payments.js
Widget->>Usuario: 展示不可更改的银行、金额和付款说明
Usuario->>Widget: 授权付款
Widget->>Banco: 重定向 / App to App（SCA）
Banco->>API: SCA返回Wealth Reader的callback
API-->>Widget: 授权的技术确认
Note over Back,API: 对账与资金结算确认
loop 直到最终状态
Back->>API: POST /payments/?action=status
API-->>Back: payment_status: not_initiated | pending | settled | ...
end

步骤 1（安全后端）：服务器创建一个支付意图（POST /payments/?action=create），并使用 X-API-Key、Idempotency-Key 和 Content-Type: application/json。此调用将金额（amount_minor，单位为分）、币种（currency，目前仅 EUR）、收款人（beneficiary.name 和 beneficiary.iban）、银行对账单中的付款说明（reference）、内部参考号（customer_reference）及允许的 Web 来源（allowed_origin）固定为不可更改的值。这六项均为必填，请求体使用严格的允许列表：任何未知字段都会返回 422 invalid_request。
响应：返回 201 和 {"success": true, "payment": {…}}；幂等重放则返回 200。意图标识符位于 payment.id，组件的短期令牌位于 payment.widget.token。
步骤 2（商户前端）：浏览器通过官方脚本 load-payments.js 或函数 WealthReaderPayments.mount() 挂载组件，仅传入 payment.id 和 payment.widget.token。用户选择银行（如果意图中未预先选择），并在银行界面完成强客户认证（SCA）。
资金结算确认：后端通过 POST /payments/?action=status 查询状态，请求体必须恰好为 {"payment_intent_id": "<id>"}。没有 webhook：请定期查询，直到达到最终状态。

两种收款模式

Wealth Reader 根据业务需求提供两种模式：

商户标准集成（自行指定收款人）：
- 商户自由指定收款人的姓名和 IBAN、金额、币种（EUR）、付款说明及订单参考号。
- 可通过 allowed_institution_codes 限制用户可选的银行，或允许整个目录。
托管配置（如 cruz_roja_demo）：
- 用于捐赠和公开演示。
- 服务器固定官方收款账户，确保资金只能流向慈善机构（例如西班牙红十字会，金额限制在 0,01 EUR 至 1,00 EUR 之间）。

统一银行目录

Wealth Reader 通过以下端点提供支持 PSD2 支付发起的欧洲金融机构统一目录：

GET https://api.wealthreader.com/payments/entities/?country=ES

可获取银行的标准化名称、标识、支持的转账方式和技术要求（例如是否需要向付款人索取扣款账户 IBAN）。支持 country、search（别名 q）、code、payment_method、limit 和 offset 筛选。

此端点公开，无需 X-API-Key。发送密钥没有任何好处，还会消耗该凭据的一次调用额度。

请始终按 code 返回的原样使用代码。创建意图只会验证 allowed_institution_codes 的格式，不会检查代码是否存在于目录中：拼写错误的代码在创建时不会报错，但稍后会导致银行选择器为空。

interaction_status: completed 仅表示屏幕上的技术交互已结束。只有 payment_status 为 settled 时，才能认定付款已最终完成。payment_status 的可能值为 not_initiated、pending、settled、rejected、cancelled、expired、failed 和 unknown，详见状态、轮询和对账。

职责分离

支付凭据（X-API-Key）仅用于服务器间通信。绝不能放入前端或公开代码仓库。
浏览器只接收意图标识符及与 HTTPS 来源绑定的短期令牌。
组件不能更改金额、币种、收款人、付款说明或允许的金融机构。
关闭模态窗口或组件不能代替后端的资金状态查询。
支付功能不与 Wealth Reader 银行数据聚合产品共享凭据、令牌或 callback。

凭据与调用额度

支付凭据必须启用 PAYMENTS 产品，否则 API 返回 403 payments_not_allowed。凭据缺失或格式错误会返回 401 invalid_api_key。

每次经过身份验证的调用都会消耗 API 密钥累计计数器的一单位。 此计数器覆盖整个使用期，没有时间窗口，也不会自动补充：用尽后，所有支付调用都会持续返回 429 api_limit_reached，直到提高限额。等待或重试无法解决。如果预计调用量较高，或用于公开演示（每次加载页面会消耗一次调用），请在发布前与 Wealth Reader 商定限额。

下一步

继续阅读集成与组件。

最后更新于 2026-09-10