支付

支付意图与幂等性

支付意图在用户与小部件交互之前，会不变地确定交易的经济条款。这防止恶意客户端在前端篡改金额、目的账户或转账附言。

创建支付意向的参数（`POST /payments/?action=create`）

1. 商户标准模式（自有受益人）

在该模型中，商家定义了所有收款信息：

字段	类型	必填	描述与规则
`amount_minor`	整数	是的	金额以较小单位（分）表示。例如， `1500` 代表 `15,00 EUR`。
`currency`	文本字符串	是的	ISO 4217 三字母货币代码。目前 `EUR`。
`beneficiary`	JSON 数据对象	是的	目标账户数据： `name` （拥有者，1到140个文本字符）和 `iban` （有效IBAN ，不含空格，且校验位已经验证）。只支持这两个键。
`reference`	文本字符串	是的	银行对账单上可见概念（文本最多140个字符）。
`customer_reference`	文本字符串	是的	订单或客户的内部标识符（文本1至128个字符：字母、数字、 `.`、 `_`、 `:`、 `-`;必须以字母或数字开头）。
`allowed_origin`	文本字符串	是的	精确 HTTPS 源，可以嵌入小部件（例如 `https://tienda.example.com`），但没有路径。
`allowed_institution_codes`	数组	不	允许的实体代码列表（例如 `["santander-es", "bbva-es"]`）。如果省略，目录中的任何实体都被允许。
`locale`	文本字符串	不	控件接口的语言。本版本仅接受 `es`;其他值返回 `422 invalid_locale`。
`expected_mode`	文本字符串	不	`mock` 或 `live`。检查你是否调用了预期环境;环境不会改变。如果不匹配， `409 payment_mode_mismatch`。

正文是一个严格的 白名单：发送不在本表中的字段返回 422 invalid_request，省略强制字段亦然。 Content-Type: application/json 头是强制的（415 json_required），正文限制为32 KB。

2. 带有托管档案的模型（捐赠/演示）

对于受监管的案件或 cruz_roja_demo等公开演示，服务器会制定财务规则并设定官方目标账户：

字段	类型	必填	描述与规则
`profile`	文本字符串	是的	配置文件标识符（例如 `cruz_roja_demo`）。
`institution_code`	文本字符串	是的	用户选择的实体代码（来源于 `profile-institutions`）。
`amount_minor`	整数	是的	金额受配置规则限制（例如 1 至 100 欧分）。
`customer_reference`	文本字符串	是的	你系统自己的审计参考。
`allowed_origin`	文本字符串	是的	小工具 HTTPS 源。
`locale`	文本字符串	不	小部件语言（`es`）。
`expected_mode`	文本字符串	不	预期模式（`mock` 或 `live`）。

当 profile指定时，服务器会自动分配官方收款人及相应的付款说明。请不要在受管理配置文件下的请求发送 beneficiary 或 reference 。

`Idempotency-Key`法则

Idempotency-Key 头是创建支付意图请求中必不可少的。该头部必须包含16到128个可见的ASCII文本字符，且不得有空格（例如，v4 UUID）。其范围是认证公司独有的：

相同的幂等性密钥和相同的请求体： 返回之前与 idempotent_replay: true一起创建的原始意图。不生成新的费用，银行订单也未重复。
相同的幂等性密钥和不同的请求体： 立即用 HTTP 409 Conflict回应。
另一家公司使用相同的幂等性密钥：属于 另一个完全孤立的幂等性命名空间。

如果创建支付意向的请求发生网络中断或超时，请 用完全相同的头部 Idempotency-Key 和相同的请求体重试。在瞬态故障发生时，不要生成新密钥。

持续性与生命周期

先前持久化： 在返回响应或与任何银行连接器交互之前，意图会被记录在数据库中。
临时控件令牌： 响应 token （payment.widget.token）有效时间较短（通常为15到30分钟），只能从声明的 allowed_origin 中使用。
并发锁定： 系统实现了乐观控制和 leases 控制，以防止两个同时调用授权或修改相同的意图。

常见错误代码

HTTP	代码	原因	建议行动
`400`	`idempotency_key_required`	`Idempotency-Key`头缺失或格式错误。	生成一个有效密钥，字符介于16到128个字符之间，显示ASCII文本，且不带空格。
`409`	`idempotency_conflict`	密钥被重复使用，付款信息不同。	为不同的支付生成新的密钥，或重用完全相同的请求体。
`409`	`payment_mode_mismatch`	`expected_mode` 与你调用的环境模式不匹配。	检查你是针对沙盒还是生产环境;模式是由部署决定的，而不是调用。
`401`	`invalid_api_key`	`X-API-Key`头缺失、格式无效，或通行密钥不存在或处于非激活状态。	检查 API 凭据。绝不要把它包含在前端。
`403`	`payments_not_allowed`	API键没有启用产品`PAYMENTS`。	联系 Wealth Reader 客服，激活你的账户付款。
`403`	`payment_profile_not_allowed`	你的公司没有启用托管配置文件。	向 Wealth Reader申请启用该托管配置。
`429`	`api_limit_reached`	您的 API 凭据已耗尽累计调用额度。	重试或等待无法解决：没有窗口或自动重置。请求延长限制。
`415`	`json_required`	`Content-Type: application/json`头部缺失。	将请求体以 JSON 格式发送。
`422`	`invalid_request`	缺少必填字段或提交了未识别的字段。	查看参数表：请求体使用严格的允许列表。
`422`	`invalid_institution`	所选实体不可用或无效。	请参见 `GET /payments/entities/` 有效代码。
`422`	`invalid_amount`	金额低于最低要求（€0.01）或非整数。	确认你发送的是分（cent）的整数（`amount_minor`）。

下一步

继续状态、轮询和对账.

最后更新于 2026-09-10

创建支付意向的参数（POST /payments/?action=create）