API docs by Redocly

Wealth Reader (8.1.12)

Download OpenAPI specification:

E-mail: info@wealthreader.com

基于PSD2的监管API提供对某些金融信息的访问，如银行账户余额和交易。然而，还存在其他财富信息来源，这些信息无法通过这些API访问。Wealth Reader API通过提供对全球任何实体中额外财富来源的实时访问来扩展监管API提供的信息。还有两个其他相关文档将帮助您集成Wealth Reader API。一个是Javascript小部件集成指南：https://docs-en.wealthreader.com/ 另一个是基于此文档的Postman集合。 非常重要：此API定义适用于通过Widget集成的客户端，因此省略了一些对此类集成不必要的参数，例如银行认证参数，因为将使用令牌。

Core

标准集成所需的核心API

检索金融资产及其组成详情

检索金融资产及其组成详情，包括由股票或基金组成的投资组合、信用卡、保险和贷款。包括每个资产的所有权信息以及便于数据处理的唯一标识符。可以获取Mock数据。请咨询技术团队如何操作。

Request Body schema: application/x-www-form-urlencoded
api_key
string

在服务中标识客户端

code
string

实体名称。完整列表可通过GET获取

示例: caixabank

token
string

标识托管的凭据。获取令牌的流程在"Widget集成指南"文档中描述。可用的Mock用户如下：MOCKDATA，OK响应；MOCKOTP，带OTP挑战的响应；MOCKLOGINKO，带登录错误的响应

示例: MOCKDATA

product_types
string
Enum: "accounts" "portfolios" "cards" "receipts" "loans" "factoring" "confirming" "properties" "invoices" "files" "deposits" "leases" "insurances"

要检索信息的产品类型列表。接受多个用逗号分隔的值。

示例: accounts,portfolios

only_balances
boolean
Default: false

指示是否仅获取产品余额而不是所有可用信息。默认值：false。

示例: false

fetch_transaction_details
boolean
Default: false

指示当实体连接器支持时是否应获取扩展的交易详情。重要提示：启用它意味着对每笔交易执行一次或多次额外的导航以丰富返回的信息。这将不可避免地显著增加执行时间。额外导航的数量随交易量增加而增长。建议仅在确定需要超出默认返回的详细程度时才启用它。获取到的详情会插入到每笔交易级别的 additional_info 键中。使用此参数需要专用环境。

示例: false

date_from
string <date>

请求交易的起始日期，格式为YYYY-MM-DD。必须是今天之前的日期。

示例: 2024-01-01

date_to
string <date>

这仅适用于按未来日期限制贷款和确认产品，格式为YYYY-MM-DD。日期必须晚于今天

示例: 2025-12-31

required_products_schema
string

所需产品架构。指示需要从哪些账户或卡获取数据，以及附加配置。

示例: 

{
  "ACCOUNTS": {
    "0ae4d722b1c82feeafb4b36b2893230444071335": {
      "only_balances": false,
      "add_pdf_from_uuids": [
        "90763109952d4f2ebece8dceca8254078c5384a0"
      ],
      "date_from": "2024-04-03"
    }
  },
  "CARDS": {
    "957e6f63546f3fecacce80192b6f7436496dc057": {}
  }
}
add_pdf_from_uuids
string

接受用逗号分隔的交易uuid。仅当product_types为ALL或包含accounts时才考虑此参数。添加与每个请求的银行交易相关联的PDF文档。

示例: 

20966426721d0885ef9d4b95535e1d3198936f16,8772d6c978d37d7af83094abf380b8b703e94105,e59296b79e7f80cec26679d2c65883025fd59295
otp_method
string

当API返回错误码2017或20171（多种OTP方式）时，用于选择二次验证投递渠道。请使用同一响应中的会话标识再次调用，并将otp_method设为statistics.otpMethods中某一对象的otp_method字段的完整字符串——不要使用数组下标。首次凭据请求可省略；用户选择方式后必填。下方示例仅供参考；请始终复制statistics.otpMethods中返回的字符串。

示例: OTP_SMS ****1234

Responses

Request samples

Content type
application/x-www-form-urlencoded
api_key=a1b2c3d4e5f6g7h8i9j0&code=caixabank&token=1234Asdf&product_types=accounts%2Cportfolios&only_balances=false&date_from=2024-01-01&date_to=2025-12-31&required_products_schema=%7B%22ACCOUNTS%22%3A%7B%220ae4d722b1c82feeafb4b36b2893230444071335%22%3A%7B%22only_balances%22%3Afalse%2C%22add_pdf_from_uuids%22%3A%5B%2290763109952d4f2ebece8dceca8254078c5384a0%22%5D%2C%22date_from%22%3A%222024-04-03%22%7D%7D%2C%22CARDS%22%3A%7B%22957e6f63546f3fecacce80192b6f7436496dc057%22%3A%7B%7D%7D%7D&add_pdf_from_uuids=20966426721d0885ef9d4b95535e1d3198936f16%2C8772d6c978d37d7af83094abf380b8b703e94105

Response samples

Content type
application/json
[
  • {
    }
]

交易类型列表

query Parameters
lang
string
Default: "es"
Enum: "es" "en"

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

查询与api_key关联的令牌

使用此方法查询与特定 api_key 关联的令牌。结果分页返回：limit 设置每页的令牌数量（最多 500），page 选择要返回的页。api_key、method 和 limit 为必填参数；如果缺少任何一个或其无效，API 将返回 HTTP 400 和错误代码 2。

Request Body schema: application/x-www-form-urlencoded
required
api_key
required
string^[a-z0-9]{8}$

api_key用于在服务中识别客户端

method
required
string
Value: "get"

要执行的操作。唯一支持的值是 get。

示例: get

limit
required
integer [ 1 .. 500 ]

每页的令牌数量。最小值 1，最大值 500。

示例: 100

page
integer >= 1
Default: 1

指定要检索的页码。每页最多包含 limit 个令牌。如果未提供，默认值为1。

示例: 1

code
string

用于筛选令牌的实体代码。如果省略，则返回所有实体的令牌。

示例: bbva

sort_by
string
Default: "created_at"
Enum: "created_at" "accesed_at"

用于排序结果的字段：created_at（创建日期）或 accesed_at（最后访问日期）。默认值为 created_at。

示例: created_at

sort_order
string
Default: "DESC"
Enum: "ASC" "DESC"

排序方向：ASC（升序）或 DESC（降序）。默认值为 DESC。

示例: DESC

Responses

Request samples

Content type
application/x-www-form-urlencoded
api_key=a1b2c3d4&method=get&limit=100&page=1

Response samples

Content type
application/json
{
  • "success": true,
  • "payload": {
    },
  • "pagination": {
    },
  • "statistics": {
    }
}

撤销令牌

此方法允许撤销现有令牌以取消授权未来的API访问请求。

Request Body schema: application/x-www-form-urlencoded
required
api_key
string

在服务中标识客户端

token
string

要撤销的令牌。

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Token successfully revoked."
}

将令牌重新分配给不同的api_key

此方法允许将令牌从一个api_key重新分配到另一个。两个api_key都必须处于激活状态并属于同一公司，且令牌必须属于api_key_source。

Request Body schema: application/x-www-form-urlencoded
required
api_key_source
string

从中重新分配令牌的api_key。

api_key_target
string

要将令牌重新分配到的api_key。

token
string

要重新分配的令牌。

示例: FRJ0mHlaqZwLzu

Responses

Request samples

Content type
application/x-www-form-urlencoded
api_key_source=a1b2c3d4e5f6g7h8i9j0&api_key_target=b2c3d4e5f6g7h8i9j0k1&token=FRJ0mHlaqZwLzu

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Token successfully reassigned."
}

添加新域名

添加将托管小部件的域名与目标webhook之间的关联。要编辑或测试您的域名，请使用 https://www.wealthreader.com/clients/

Request Body schema: application/x-www-form-urlencoded
required
method
required
string

Method to execute.

示例: add

api_key
required
string

User's API key.

domain
required
string

Domain to add.

示例: http://desarrollo.cliente.es

url_callback
required
string

URL for callback.

示例: https://desarrollo.cliente.es/hooks/wealthreader

tokenize
required
string
Enum: "1" "0"

控制小部件是否启动令牌化流程：

  • 1 - 用户在金融机构进行身份验证（登录、授权同意、2FA（如需要）），并返回一个可重复使用的令牌
  • 0 - 不执行令牌化。必须在请求中包含之前获取的令牌值

示例: 1

Responses

Request samples

Content type
application/x-www-form-urlencoded
method=add&api_key=a1b2c3d4e5f6g7h8i9j0&domain=https%3A%2F%2Fwww.cliente.com&url_callback=https%3A%2F%2Fwww.cliente.com%2Fwebhooks%2Fwealthreader&tokenize=1

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

错误代码列表

错误代码列表。请特别注意，并非所有错误代码都应该由您的应用程序以相同方式处理。对于密码错误，您不应该使用相同的参数重试调用，但对于指示实体正在维护的错误，您可以重试。请与我们的团队请求技术会议，以解决有关错误管理的任何问题。

query Parameters
lang
string
Default: "es"
Enum: "es" "en"

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

警告代码列表

警告代码列表。

query Parameters
lang
string
Default: "es"
Enum: "es" "en"

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Advanced

可选端点，不需要用于标准集成。仅在 Wealth Reader 明确指示时使用。

检索支持的实体列表

检索支持的实体列表以及绘制实体登录表单所需的信息。

query Parameters
show_only_tested
integer
Default: 0
Enum: 0 1

Indicates whether to show only tested entities. Default value is 0. In production environments, always use 1.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

注册新用户

此端点是可选的，不需要用于标准集成。仅在Wealth Reader明确指示时使用。 此端点允许基于唯一标识符在投资组合转移平台Easytransfer或报告工具Acumulas上注册用户。

Request Body schema: application/x-www-form-urlencoded
required
api_key
required
string

Authentication key (8 alphanumeric characters)

user_id
required
string

User identification document.

示例: 12345678A

service
required
string
Enum: "integra" "easy-transfer"

Service associated with the user. Determines the data flow.

示例: easy-transfer

email
required
string <email>

User email, used according to service type.

示例: sai_banker@singularbank.com

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "User registered successfully"
}

检查用户注册状态

此端点是可选的，不需要用于标准集成。仅在Wealth Reader明确指示时使用。 检查用户是否已在Easytransfer或Acumulas系统中注册，并返回用户的唯一访问链接。

Request Body schema: application/x-www-form-urlencoded
required
api_key
required
string

Authentication key

user_id
required
string

User identification document.

示例: 12345678A

Responses

Response samples

Content type
application/json
{}

撤销之前注册的用户

此端点是可选的，不需要用于标准集成。仅在Wealth Reader明确指示时使用。 此端点允许从Easytransfer或Acumulas平台服务中注销用户。

Request Body schema: application/x-www-form-urlencoded
required
api_key
required
string

Authentication key (8 alphanumeric characters)

user_id
required
string

User identification document.

示例: 12345678A

service
required
string
Enum: "integra" "easy-transfer" "all"

Service from which to unregister the user. 'all' for all services.

示例: easy-transfer

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "User unregistered successfully"
}

批量连接加载

此端点是可选的，不需要用于标准集成。仅在Wealth Reader明确指示时使用。 重要：要使用Wealthreader端的批量进程管理，需要专用环境。此端点在api.wealthreader.com上不可用。 在"batch"标签下分组的端点允许异步处理多个银行连接，与同步的/entities/方法不同。非常适合处理大量连接并避免超时。

Request Body schema: application/json
required
api_key
required
string

Identifies the client in the service

notification_url
required
string <uri>

Webhook URL. A notification is sent to this URL for each individual credential as soon as it completes processing, not only once all connections in the batch are done.

示例: https://example.com/webhook/batch-complete

required
Array of objects (batch-connection) non-empty

List of connections to process

Responses

Callbacks

Request samples

Content type
application/json
{
  • "api_key": "a1b2c3d4e5f6g7h8i9j0",
  • "notification_url": "https://example.com/webhook/batch-complete",
  • "connections": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "batch_id": "batch_20250120_a1b2c3d4",
  • "total_connections": 5,
  • "estimated_completion_time": "2025-01-20T10:45:00Z"
}

Callback payload samples

Callback
POST: Webhook fired when a credential finishes processing
Content type
application/json
{
  • "batch_id": 10863151,
  • "credential_id": "cred_demo_002",
  • "status": "completed",
  • "timestamp": "2026-05-13T08:02:47+00:00"
}

获取批量连接的一般统计信息

此端点是可选的。检索批次中所有连接处理结果的一般统计信息。

Request Body schema: application/json
required
api_key
required
string

Identifies the client in the service

batch_id
required
string

Batch ID

Responses

Request samples

Content type
application/json
{
  • "api_key": "string",
  • "batch_id": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "batch_id": "batch_20250120_a1b2c3d4",
  • "status": "completed",
  • "statistics": {
    }
}

获取批次中特定连接的单独结果

此端点是可选的。检索批次中特定连接的结果。

Request Body schema: application/json
required
api_key
required
string

Identifies the client in the service

batch_id
required
string

Batch ID

credential_id
required
string

Filter by specific credential_id

Responses

Request samples

Content type
application/json
{
  • "api_key": "string",
  • "batch_id": "string",
  • "credential_id": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "payload": {
    },
  • "statistics": {
    }
}

MyBankMatch

账户所有权验证：通过与您的许可证关联的银行所提供的 SEPA 收款人验证（VoP），检查某个 IBAN 是否属于指定的账户持有人。分步指南：MyBankMatch。

验证 IBAN 是否属于账户持有人（MyBankMatch）

通过与您的 WealthReader 许可证关联的您自己银行所提供的 SEPA 收款人验证（VoP），检查 IBAN 是否属于指定的账户持有人。返回银行的判定结果：不会以本地姓名相似度计算替代该结果，也不会创建、授权或执行任何支付指令。

首次调用之前

  1. 确保拥有包含 MY_BANK_MATCH 产品且配额可用的有效许可证。
  2. 打开 客户 · MyBankMatch，点击 连接银行，并在 WealthReader 托管窗口中完成身份验证。令牌化连接将与您的 api_key 关联；银行令牌不会传递给浏览器，也不是查询参数。

请求：表单编码的请求体（application/x-www-form-urlencoded），包含 api_key、iban 和 name，与 /entities/ 相同。不发送 JSON，也不使用 X-API-Key 请求头。请将 api_key 保存在您的后端。

响应：HTTP 200 表示已获得产品结果，而不表示姓名匹配。请先检查 success，再检查 payload.result：

payload.result 含义 附加字段 是否计费
MATCH 银行认为姓名与账户持有人一致。 无。 是，0.10 EUR。
PARTIAL_MATCH 银行返回部分匹配（CLOSE_MATCH）。 suggested_name。 是，0.10 EUR。
NO_MATCH 银行表示姓名不匹配。 无。 是，0.10 EUR。
NOT_CONFIGURED 许可证尚未关联银行。 setup_url。 否。
REAUTH_REQUIRED 银行连接需要重新进行身份验证。 setup_url、reason_code。 否。
NOT_POSSIBLE 无法获得可用的判定结果。不等同于 NO_MATCH。 reason。 否。

只有 MATCH、PARTIAL_MATCH 和 NO_MATCH 消耗配额。输入错误和非结论性结果不计费。

不提供幂等键，也不提供免费重试。 如果响应丢失（超时、网络故障或无法解析的响应体），您的应用可能无法得知结果及其配额消耗情况。请勿自动重新发送相同的查询：请在“客户”中查看历史记录，并在联系技术支持时提供 statistics.SESSION。

完整指南：MyBankMatch。

Request Body schema: application/x-www-form-urlencoded
required
api_key
required
string

包含 MY_BANK_MATCH 产品且配额可用的有效许可证的 8 位十六进制密钥。请将其保存在您的后端。

iban
required
string

SEPA 国家/地区的 IBAN。系统会删除空格、转换为大写，并校验其所属国家/地区的长度和 mod-97 校验位。

示例: ES9321005707250200257112

name
required
string <= 140 characters

账户持有人姓名。不得为空，须为有效的 UTF-8，不含控制字符，最多 140 个字符。系统会去除首尾空格并合并内部连续空格。

示例: Wealthreader S.L.

Responses

Request samples

Content type
application/x-www-form-urlencoded
api_key=a1b2c3d4&iban=ES9321005707250200257112&name=Wealthreader%20S.L.

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "payload": {
    },
  • "statistics": {
    }
}

Payments

从付款人银行发起的 SEPA 账户到账户支付。有两种集成方式：

  • Fast Track：只需一次 POST /payments/?action=fast-track 调用即可返回支付 URL，Wealth Reader 会以 OK 或 KO 通知您的 notification_url。请参阅 Fast Track 支付。
  • Widget：您的后端通过 POST /payments/?action=create 创建不可变的支付意图，使用返回的令牌打开 Widget，并通过 POST /payments/?action=status 确认结果。请参阅 支付简介 和 状态、轮询与对账。

适用于所有 /payments/?action=... 调用的通用规则

  • 使用 POST 方法，携带 Content-Type: application/json 请求头，请求体为 JSON 对象（最大 32768 字节）。
  • 仅通过包含 PAYMENTS 产品的有效许可证的 X-API-Key 请求头进行身份验证（wr_live_ 后跟 72 个字母或数字）。该密钥绝不在请求体中发送。每次经过身份验证的调用都会计入许可证的调用限额。
  • 请求体采用白名单校验：缺少必填字段或包含未预期的字段时，返回 422 invalid_request。
  • 唯一的正面财务确认是 payment_status: settled。Widget 事件、SCA 返回或 interaction_status: completed 均不表示支付已结算。

错误格式：application/json（非 problem+json），带有稳定的 error.code；error.message 仅供参考，可能会变化。

{"success": false, "error": {"code": "invalid_request", "message": "The request body has an invalid schema."}}
HTTP error.code 原因
400 invalid_json 请求体为空、无效或不是 JSON 对象。
401 invalid_api_key X-API-Key 缺失、格式错误、未知或未激活。
403 payments_not_allowed 许可证不包含 PAYMENTS 产品。
404 action_not_found 未知的 action。
405 method_not_allowed 方法不是 POST。
413 request_too_large 请求体超过 32768 字节。
415 json_required Content-Type 不是 application/json。
422 invalid_request 缺少字段或包含未预期的字段。
429 api_limit_reached 已达到许可证的调用限额。
500 internal_error 意外错误。
503 payments_disabled, payments_accept_new_disabled, payment_storage_unavailable, payment_state_unavailable 服务暂时不可用或新支付已暂停。

Fast Track 支付的 OK 或 KO 通知 Webhook

当 Wealth Reader 检查 Fast Track 支付的状态并发现其处于最终状态时，会向该支付的 notification_url 发送此 POST。reconciliation_required 不是最终状态，不会发送通知：请通过 status 进行确认。

  • 仅当银行已结算支付（settled）时，outcome 才为 ok；rejected、cancelled、expired 和 failed 会通知 ko。
  • 在付款人停留在支付页面期间（该页面会持续查询，直至获得最终结果或支付会话过期），以及每次您调用 status 时，都会检查状态。没有单独的定时发送：如果付款人在银行得出结论前离开，或您的服务器未返回 2xx，通知将在下一次检查时发送。如果在重定向付款人几分钟后仍未收到通知，请使用 payment_intent_id 调用 status；该调用也会触发待发的通知。
  • 以任意 2xx 响应即视为已送达。Wealth Reader 不会跟随重定向，最多等待 3 秒。
  • 同一通知可能会多次送达：请将 customer_reference 加 outcome 视为幂等处理。
  • 该请求未经签名。在交付贵重商品之前，请使用您的 X-API-Key 和通知中的 payment_intent_id，通过 status 确认结果。
header Parameters
User-Agent
required
string
Value: "WealthReader-Payments"
Request Body schema: application/json
required
outcome
required
string
Enum: "ok" "ko"

仅在 settled 时为 ok。

payment_status
required
string
Enum: "settled" "rejected" "cancelled" "expired" "failed"

最终财务结果。

customer_reference
required
string

您在创建支付时发送的 Idempotency-Key。

payment_intent_id
required
string <uuid>

由 fast-track 返回的标识符。请使用它通过 status 确认结果。

Responses

Request samples

Content type
application/json
Example
{
  • "outcome": "ok",
  • "payment_status": "settled",
  • "customer_reference": "11111111-1111-4111-8111-111111111111",
  • "payment_intent_id": "3f2b8c1e-5d4a-4b6f-9e21-7c0d4a1b2e3f"
}

创建支付并获取其 URL（Fast Track）

一次调用即可返回支付 URL。付款人打开该 URL 并在其银行中授权；当支付达到最终状态时，Wealth Reader 会以 OK 或 KO 通知您的 notification_url（请参阅 notification_url Webhook）。在底层，系统会创建与 create 相同的不可变意图：金额、收款人和附言在到达浏览器之前即已固定。

Idempotency-Key 请求头同时也是您的商户参考号（通知中的 customer_reference）：它不在请求体中发送。如果使用相同的密钥和相同的请求体重复调用，您将收到相同的 URL；如果使用其他数据（包括不同的 logo）重复使用该密钥，响应为 409 idempotency_conflict。

在此 API 中，即时转账没有自身的上限：银行会拒绝其无法接受的转账（包括因金额原因），该拒绝将以 KO 的形式送达。

header Parameters
X-API-Key
required
string

包含 PAYMENTS 产品的许可证的 API 密钥。请将其保存在您的后端。

Idempotency-Key
required
string [ 16 .. 128 ] characters

16 至 128 个字符；必须以字母或数字开头，且只能包含字母、数字以及 . _ : -。UUID v4 有效。它也是通知中返回的商户参考号。

Request Body schema: application/json
required
amount
required
string

以主货币单位表示的金额，格式为 JSON 字符串。"15.50" 表示 15.50 EUR；也接受不带小数的整数（"15"）。最多两位小数，因此 "15.5" 与 "15.50" 是同一金额。最小值为 0.01。最大值受每位客户在其银行中设置的限额约束。

示例: 15.50

currency
required
string
Value: "EUR"

ISO 4217 货币代码。在此版本中，仅支持 EUR。

示例: EUR

required
object (payments-beneficiary)

转账的收款人。支付创建后不可更改。

reference
required
string [ 1 .. 140 ] characters

对账单中的附言，最多 140 个字符。

示例: Pedido 78901

priority
required
string
Enum: "normal" "instant"

normal（SEPA 转账）或 instant（SEPA 即时转账）。

示例: normal

notification_url
required
string <= 2000 characters

接收 OK 或 KO 通知的公共 https URL。不得包含凭据；如指定端口，须为 443；不得使用私有地址、本地地址或元数据地址。

示例: https://tienda.example.com/pagos/aviso

logo
string <= 2048 characters

可选。您商户 SVG 格式徽标的公共 https URL（路径必须以 .svg 结尾；允许包含查询参数），不得包含凭据、片段或私有地址，最多 2048 个 ASCII 字符。支付页面会将其显示在摘要上方；Wealth Reader 不会下载该文件，而由付款人的浏览器加载。任何其他值都会返回 422 invalid_logo。

示例: https://tienda.example.com/marca/logo.svg

Responses

Request samples

Content type
application/json
{}

Response samples

创建支付意图（Widget）

创建不可变的支付意图，并返回一个短期令牌，用于在付款人的浏览器中打开 Widget。金额、收款人和附言在后端固定，无法从浏览器修改。Widget 关闭后，请从您的后端通过 status 确认结果。

请求体有两种变体：

  • 标准：由您设置 amount_minor、currency、beneficiary、reference、customer_reference 和 allowed_origin。
  • 托管配置文件（例如 cruz_roja_demo）：由 Wealth Reader 设置收款人、附言和限额；您发送 profile、institution_code、amount_minor、customer_reference 和 allowed_origin。可通过 profile-institutions 获取银行列表。

如果使用相同的 Idempotency-Key 和相同的请求体重复调用，您将收到相同的意图（200，idempotent_replay: true）；如果使用其他数据重复使用该密钥，响应为 409 idempotency_conflict。该密钥仅在您的公司范围内有效。

指南：意图与幂等性 和 Widget 集成。

header Parameters
X-API-Key
required
string

包含 PAYMENTS 产品的许可证的 API 密钥。请将其保存在您的后端。

Idempotency-Key
required
string [ 16 .. 128 ] characters

16 至 128 个可见 ASCII 字符。请为每笔支付生成一个密钥（UUID v4 有效），并在重试调用时重复使用。

Request Body schema: application/json
required
One of
amount_minor
required
integer >= 1

以辅币单位（分）表示的金额，格式为 JSON 整数。1500 表示 15.00 EUR。最大值受每位客户在其银行中设置的限额约束。

示例: 1500

currency
required
string
Value: "EUR"
required
object (payments-beneficiary)

转账的收款人。支付创建后不可更改。

reference
required
string [ 1 .. 140 ] characters

对账单中的附言，最多 140 个字符。

示例: Pedido 78901

customer_reference
required
string <= 128 characters

您的内部支付参考号。1 至 128 个字符；以字母或数字开头，且只能包含字母、数字以及 . _ : -。

示例: order-78901

allowed_origin
required
string

打开 Widget 的页面的源（https://host[:puerto]; 不含路径、查询或片段）。Widget 仅在该源中可用。

示例: https://tienda.example.com

locale
string
Value: "es"

可选。Widget 的语言；在此版本中仅支持 es。

expected_mode
string
Enum: "mock" "live"

可选。如果与环境不一致，调用将返回 409 payment_mode_mismatch，而不会创建支付。

allowed_institution_codes
Array of strings <= 2500 items

可选。付款人可从中选择的唯一银行代码的非空列表（请参阅 /payments/entities/）。

示例: 

[
  "bbva-es",
  "santander-es"
]
logo
string or null

可选。您 SVG 格式徽标的公共 https URL（路径以 .svg 结尾），不得包含凭据、片段或私有地址，最多 2048 个字符。

Responses

Request samples

Content type
application/json
Example
{
  • "amount_minor": 1500,
  • "currency": "EUR",
  • "beneficiary": {
    },
  • "reference": "Pedido 78901",
  • "customer_reference": "order-78901",
  • "allowed_origin": "https://tienda.example.com"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "payment": {
    }
}

查询支付状态

服务器到服务器查询支付状态，直至获得银行的最终结论。回调、SCA 返回或 Widget 关闭都不是财务确认：只有 payment_status: settled 才是。

Wealth Reader 会限制每个意图的外部查询次数；请同样在您的后端实施退避（backoff），并且在结果不明确时不要创建新的意图。

结果不明确：在发出发起请求后，如果发生网络中断、超时或无法识别的响应，意图将变为 reconciliation_required，并带有 payment_status: unknown，响应中包含 reconciliation。发起操作绝不会自动重复。请保留标识符和幂等键，不要创建新的意图或重新授权；当 automatic_recovery 为 false 时，请停止轮询，并凭 reconciliation.reference 上报技术支持。

对于 Fast Track 支付，当支付已达到最终状态时，此查询还会向 notification_url 发送待发的 OK/KO 通知。

指南：状态、轮询与对账。

header Parameters
X-API-Key
required
string

创建该支付的许可证的 API 密钥。

Request Body schema: application/json
required
payment_intent_id
required
string <uuid>

由 create 返回的 payment.id（对于 Fast Track，为 fast-track 返回的 payment_intent_id）。

示例: 3f2b8c1e-5d4a-4b6f-9e21-7c0d4a1b2e3f

refresh
boolean
Default: true

可选。true 会在适当时向银行查询最新状态；false 返回已存储的状态。

Responses

Request samples

Content type
application/json
{
  • "payment_intent_id": "3f2b8c1e-5d4a-4b6f-9e21-7c0d4a1b2e3f",
  • "refresh": true
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "payment": {
    }
}

列出托管配置文件的银行和条件

返回为您的公司启用的托管配置文件的条件（收款人、附言、金额限额）以及付款人可选择的银行。请将所选的 code 用作 create 中的 institution_code。

header Parameters
X-API-Key
required
string

包含 PAYMENTS 产品的许可证的 API 密钥。

Request Body schema: application/json
required
profile
required
string

托管配置文件的代码。

示例: cruz_roja_demo

Responses

Request samples

Content type
application/json
{
  • "profile": "cruz_roja_demo"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "profile": {
    }
}

列出可用于支付的银行

可发起支付的银行目录，包含其徽标及支持的支付方式。X-API-Key 为可选项；如果发送，将对其进行校验并计为一次调用。也支持使用 POST 在 JSON 请求体中传递相同的筛选条件，以及使用必须携带 X-API-Key 的 POST /payments/?action=entities。

未知的筛选条件将被忽略，绝不会产生校验错误。

query Parameters
country
string
Example: country=ES

ISO 3166-1 alpha-2 国家/地区代码。ALL 或空值表示不筛选。

示例: ES

search
string

名称或代码中包含的文本，不区分大小写（别名 q）。

code
string
Example: code=santander-es

银行的精确代码，不区分大小写。

示例: santander-es

payment_method
string
Enum: "sepa_credit_transfer" "instant_sepa_credit_transfer"

仅限支持该支付方式的银行。

limit
integer [ 1 .. 2000 ]

每页大小（1 至 2000）。

offset
integer >= 0

要跳过的结果数。

header Parameters
X-API-Key
string

可选。如果发送，将对其进行校验并计为一次调用。

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "total": 1,
  • "entities": [
    ]
}

Cards (real time)

Real-time card expense synchronization from the Open Sync mobile app: per-customer employee pre-registration, signed webhooks (card_transaction.created / card_enrollment.confirmed), and REST query / backfill.

Register or rotate the real-time cards webhook

Creates or updates the webhook URL of the customer for the card_transaction.created and card_enrollment.confirmed events (see the cards-webhook-delivery schema for the delivery format and signature). On first setup, or when rotate_secret is true, a new webhook_secret (64 hex characters) is generated and returned once; in any other case webhook_secret comes back as null in the response and cannot be retrieved again. webhook_url must always be https:// and must resolve to a publicly routable host: localhost, private, loopback, link-local (including the cloud metadata address), CGNAT, multicast and reserved addresses are rejected, in any notation (hexadecimal, decimal, octal, short dotted or IPv4-mapped IPv6), and so is a hostname that does not resolve at all. The same check runs again right before every delivery, not only at registration: if the host is repointed at an internal address afterwards (DNS rebinding) the delivery is closed as failed with response_excerpt "blocked_host". Sending null in webhook_url disables webhooks for that customer; omitting the field leaves the stored URL untouched, which is how the secret is rotated without changing the URL.

Request Body schema: application/json
required
api_key
required
string

API key of the customer.

webhook_url
string or null

https:// URL that will receive the events, on a publicly routable host that resolves in DNS. null disables webhooks; omitting the field leaves the stored URL unchanged.

示例: https://cliente.example.com/webhooks/wealthreader-cards

rotate_secret
boolean
Default: false

When true, generates and returns a new webhook_secret.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Pre-register the email of an employee

Creates an enrollment request in pending status with a short expiry (ttl_minutes, 20 by default, between 1 and 60) for the employee to confirm by opening the mobile app and entering that email (POST /user-sync-validation/, no contract change for the app). It is idempotent: repeating the call for the same (api_key, email) while it is still pending and not expired returns the same request. If the email is already linked to the calling customer, it returns status "active" directly. If it is already linked to a different customer, it returns 409. Rate limit: at most 60 calls to this endpoint per api_key every 60 seconds, counting every attempt and not only the ones that create a row, checked before anything else so the answers that create nothing (200 already active, 409 linked to another customer, 400) cannot be walked as an enumeration oracle. Exceeding it returns 429 with code rate_limited.

Request Body schema: application/json
required
api_key
required
string

API key of the customer.

email
required
string <email>

Email of the employee to pre-register.

示例: empleado@cliente.com

ttl_minutes
integer [ 1 .. 60 ]
Default: 20

Minutes the request stays valid before expiring.

Responses

Request samples

Content type
application/json
{
  • "api_key": "a1b2c3d4",
  • "email": "empleado@cliente.com",
  • "ttl_minutes": 20
}

Response samples

Content type
application/json
{
  • "success": true,
  • "payload": {
    }
}

Check the status of an enrollment

Read-only status of an enrollment request. It has no side effects on card users, unlike POST /user-sync-validation/, which does confirm. The only write allowed is lazily marking a pending enrollment whose expiry date has already passed as expired.

query Parameters
api_key
required
string
Example: api_key=a1b2c3d4

API key of the customer. Note it travels in the query string, so it ends up in access logs and intermediary proxies.

示例: a1b2c3d4

enrollment_id
required
string
Example: enrollment_id=0f3a9c7b1d2e4f5a6b7c8d9e0f1a2b3c

Identifier returned by POST /cards/enrollments/.

示例: 0f3a9c7b1d2e4f5a6b7c8d9e0f1a2b3c

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "payload": {
    }
}

Query / backfill real-time card transactions

Returns the real-time card transactions received for the employees linked to this api_key, ordered by ascending id. Meant both for periodic backfill (poll with date_from/date_to and paginate with since_id) and for one-off queries. This is the same transaction object carried by the card_transaction.created webhook.

query Parameters
api_key
required
string
Example: api_key=a1b2c3d4

API key of the customer. Note it travels in the query string, so it ends up in access logs and intermediary proxies.

示例: a1b2c3d4

date_from
string <date>
Example: date_from=2026-07-01

YYYY-MM-DD, on the operation date. Default: today minus 3 days.

示例: 2026-07-01

date_to
string <date>
Example: date_to=2026-07-11

YYYY-MM-DD, on the operation date. Default: today.

示例: 2026-07-11

email
string <email>
Example: email=empleado@cliente.com

Filters by the email of the employee.

示例: empleado@cliente.com

since_id
integer
Example: since_id=216

Exclusive cursor on the transaction id, for pagination.

示例: 216

limit
integer <= 1000
Default: 500
Example: limit=500

Maximum number of transactions to return (500 by default, 1000 max).

示例: 500

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "payload": {
    }
}