支付

Fast Track 支付

选择这种方式后，您无需嵌入组件，也无需遵循支付部分的其他章节。只需一次 POST 即可返回支付 URL，当结果为 OK 或 KO 时，Wealthreader 会通知您的服务器。作为备用手段，请保存响应中的 payment_intent_id：如果通知未送达，您可以用它查询状态。

付款人打开该 URL，并在自己的银行完成授权。在底层，系统会创建与 API 其他部分相同的不可更改的意图：金额、收款人和付款说明在到达浏览器之前即已固定，而 Idempotency-Key 请求头可在调用中断时避免重复扣款。

创建支付

POST /payments/?action=fast-track

必填请求头：Content-Type: application/json、X-API-Key 和 Idempotency-Key。该键长度为 16 至 128 个字符，必须以字母或数字开头，且只允许使用字母、数字以及 . _ : -；UUID v4 可用。如果缺少该键或其长度无效，响应为 400 idempotency_key_required；如果使用了其他字符，响应为 422 invalid_customer_reference。该键同时也是商户参考号：无需在请求体中发送。如果使用相同的键和相同的请求体重复请求，将再次收到相同的 URL。如果使用其他数据重复使用该键，响应为 409 idempotency_conflict。

字段	类型	说明
`amount`	字符串	以主货币单位表示的金额，使用 JSON 字符串。`"15.50"` 表示 15.50。也接受不带小数的整数（`"15"`）。最多两位小数：`"15.5"` 和 `"15.50"` 表示相同金额。最小值为 `0.01`。最大值受每位客户在其银行中设置的限额限制。不符合这些格式规则时，返回 `422 invalid_amount`。
`currency`	字符串	ISO 4217 货币代码。在此版本中为 `EUR`。
`beneficiary`	对象	收款人：`name`（1 至 140 个字符）和 `iban`（不含空格，带校验位）。
`reference`	字符串	银行对账单上的付款说明，最多 140 个字符。
`priority`	字符串	`normal` 或 `instant`。
`notification_url`	字符串	用于通知 OK 或 KO 的公开 `https` URL。
`logo`	字符串	可选。您商户的 SVG 格式徽标的公开 `https` URL：路径必须以 `.svg` 结尾（允许查询参数），不得包含凭据或私有地址，最多 2048 个 ASCII 字符。支付页面会将其显示在摘要上方、收款人名称旁边；没有 `logo` 时，不显示商户页头。Wealthreader 不会下载该 URL，而是由付款人的浏览器加载。任何其他值都会返回 `422 invalid_logo`。

除 logo 外，所有字段均为必填。请求体采用白名单机制。多出一个字段或缺少一个必填字段，都会返回 422 invalid_request。logo 属于支付的一部分：使用相同的 Idempotency-Key 但不同的 logo 重复请求，同样会返回 409 idempotency_conflict。

即时转账在此 API 中没有单独的上限。银行会拒绝其无法接受的转账（包括因金额原因），该拒绝会以 KO 的形式发送到 notification_url。

: "${WR_API_KEY:?Defina WR_API_KEY en el entorno seguro de su backend}"
: "${WR_PAYMENT_IDEMPOTENCY_KEY:?Genere un UUID v4 para este pago}"

curl --request POST 'https://api.wealthreader.com/payments/?action=fast-track' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${WR_API_KEY}" \
  --header "Idempotency-Key: ${WR_PAYMENT_IDEMPOTENCY_KEY}" \
  --data '{
    "amount": "15.50",
    "currency": "EUR",
    "beneficiary": {
      "name": "Comercio Online S.L.",
      "iban": "ES9121000418450200051332"
    },
    "reference": "Pedido 78901",
    "priority": "normal",
    "notification_url": "https://tienda.example.com/pagos/aviso",
    "logo": "https://tienda.example.com/marca/logo.svg"
  }'

首次请求时响应为 201，如果该键已存在则为 200，其中包含 URL 和支付标识符：

{
  "url": "https://widget.wealthreader.com/payments/pay/#payment_intent_id=…&widget_token=…&api_origin=https%3A%2F%2Fapi.wealthreader.com",
  "payment_intent_id": "22222222-2222-4222-8222-222222222222"
}

请将付款人重定向到该 URL。令牌位于片段中，与组件同时过期（通常为 15 分钟），不得记录在您的日志中。请将 payment_intent_id 与您的订单一起保存。

OK 或 KO 通知

当 Wealthreader 检查支付状态并发现其处于最终状态时，会发送 POST 到 notification_url，并使用 Content-Type: application/json 和 User-Agent: WealthReader-Payments：

{
  "outcome": "ok",
  "payment_status": "settled",
  "customer_reference": "11111111-1111-4111-8111-111111111111",
  "payment_intent_id": "22222222-2222-4222-8222-222222222222"
}

outcome 为 ok 的唯一情形是银行已完成结算（settled）。rejected、cancelled、expired 和 failed 会通知为 ko。不确定的结果（reconciliation_required）不是最终状态，不会发送通知。
customer_reference 是您的 Idempotency-Key，payment_intent_id 是创建支付时返回的标识符。
请以 2xx 响应，表示通知已送达。Wealthreader 最多等待 3 秒，且不跟随重定向。
同一通知可能会多次送达：请将 customer_reference 加 outcome 视为幂等。
非公开 https 的 URL 会在创建支付时被拒绝，并在每次发送前再次检查。

何时送达。 在付款人仍停留在支付页面期间（该页面会持续查询，直到得到最终结果或支付会话过期），以及您每次调用 POST /payments/?action=status 查询时，系统都会检查状态。没有单独的定时发送：如果付款人在银行完成处理前关闭了页面，或者您的服务器未以 2xx 响应，通知会在下一次检查时发送。因此，如果在重定向付款人几分钟后仍未收到通知，请使用 payment_intent_id 查询状态；该查询也会触发待发送的通知。参见状态、轮询和对账。

通知未签名。 在交付贵重商品或服务之前，请通过 POST /payments/?action=status 确认结果，并使用您的 X-API-Key 和 payment_intent_id：只有该响应中的 payment_status: settled 才是资金上的确认。

最后更新于 2026-11-08