API docs by Redocly

Wealth Reader (8.1.12)

Download OpenAPI specification:

E-mail: info@wealthreader.com

Regulatory APIs based on PSD2 provide access to certain financial information such as bank account balances and transactions. However, there are other sources of wealth information that are not accessible through these APIs. The Wealth Reader API extends the information offered by regulatory APIs by providing real-time access to additional wealth sources in any entity worldwide. There are two other related documents that will help you integrate the Wealth Reader API. One is the Javascript widget integration guide: https://docs-en.wealthreader.com/ and the other is a Postman collection based on this documentation. Very important: This API definition is adapted for clients integrating via Widget, so some parameters that are not necessary for this type of integration have been omitted, such as bank authentication parameters, as a token will be used.

Core

Core API required for standard integrations

Retrieves financial assets and their composition details

Retrieves financial assets and details of their composition including investment portfolios (stocks, funds, bonds, pension plans, alternative investments, crypto), credit cards, insurance, and loans. Includes ownership information for each asset as well as unique identifiers that facilitate data processing. It is possible to obtain Mock data. Check with the technical team on how to do this.

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

Identifies the client in the service

code
string

Name of the entity. The complete list is available with GET

Example: caixabank

token
string

Identifies the custodied credential. The flow by which the token has been obtained is described in the 'Widget Integration Guide' document. The following Mock users are available: MOCKDATA, OK response; MOCKOTP, response with OTP challenge; MOCKLOGINKO, response with login error

Example: MOCKDATA

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

List of product types from which information is to be retrieved. Accepts multiple values separated by commas.

Example: accounts,portfolios

only_balances
boolean
Default: false

Indicates whether to obtain only the balances of the products instead of all available information. Default value: false.

Example: false

fetch_transaction_details
boolean
Default: false

Indicates whether extended transaction details should be retrieved when the entity connector supports it. IMPORTANT: Enabling it implies performing one or more additional navigations per transaction to enrich the returned information. This will inevitably and significantly increase the execution time. The number of additional navigations grows with the volume of transactions. It is recommended to enable it only when you are certain that a level of detail beyond the one returned by default is required. The retrieved details are inserted into the additional_info key at the level of each transaction. The use of this parameter requires a dedicated environment.

Example: false

date_from
string <date>

Date from which transactions are requested, in YYYY-MM-DD format. Must be a date before today.

Example: 2024-01-01

date_to
string <date>

This only applies to restricting by future dates for products loan and confirming, in YYYY-MM-DD format. The date must be later than today

Example: 2025-12-31

required_products_schema
string

Required products schema. Indicates the accounts or cards from which data is desired, with additional configurations.

Example: 

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

Accepts transaction uuids separated by commas. Parameter that is only taken into account if product_types is ALL or includes accounts. Adds the PDF document associated with each of the requested bank transactions.

Example: 

20966426721d0885ef9d4b95535e1d3198936f16,8772d6c978d37d7af83094abf380b8b703e94105,e59296b79e7f80cec26679d2c65883025fd59295
otp_method
string

Selects which second-factor delivery channel to use when the API returned error code 2017 or 20171 (multiple OTP methods available). Call again with the same session identifier from that response and set this form field to the exact value of the otp_method property from one object in statistics.otpMethods (not the array index). Omit on the first credential-based request; send after the end user chooses a method. The example value below is illustrative only—always copy the string returned in statistics.otpMethods for your entity (wording may be OTP_SMS ****1234, SMS *****1234, or another label depending on the bank).

Example: 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
[
  • {
    }
]

List of transaction types

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Query tokens associated with an api_key

Use this method to query the tokens linked to a specific api_key. Results are paginated: limit sets the number of tokens per page (maximum 500) and page selects the page to return. api_key, method and limit are required; if any of them is missing or invalid, the API responds with HTTP 400 and error code 2.

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

api_key to identify the client in the service

method
required
string
Value: "get"

Operation to perform. The only supported value is get.

Example: get

limit
required
integer [ 1 .. 500 ]

Number of tokens per page. Minimum 1, maximum 500.

Example: 100

page
integer >= 1
Default: 1

Specify the page number you want to retrieve. Each page contains up to limit tokens. If not provided, the default value is 1.

Example: 1

code
string

Entity code used to filter the tokens. If omitted, the tokens of all entities are returned.

Example: bbva

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

Field used to sort the results: created_at (creation date) or accesed_at (last access date). Default created_at.

Example: created_at

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

Sort direction: ASC (ascending) or DESC (descending). Default DESC.

Example: 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": {
    }
}

Revoke a token

This method allows revoking an existing token to disauthorize future API access requests.

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

Identifies the client in the service

token
string

Token to be revoked.

Responses

Response samples

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

Reassign a token to a different api_key

This method allows reassigning a token from one api_key to another. Both api_keys must be active and belong to the same company, and the token must belong to api_key_source.

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

api_key from which to reassign the token.

api_key_target
string

api_key to which to reassign the token.

token
string

Token to be reassigned.

Example: 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."
}

Add a new domain

Adds the association between the domain that will host the widget and the destination webhook. To edit or test your domains, use https://www.wealthreader.com/clients/

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

Method to execute.

Example: add

api_key
required
string

User's API key.

domain
required
string

Domain to add.

Example: http://desarrollo.cliente.es

url_callback
required
string

URL for callback.

Example: https://desarrollo.cliente.es/hooks/wealthreader

tokenize
required
string
Enum: "1" "0"

Controls whether the widget initiates a tokenization flow:

  • 1 - The user authenticates with the financial institution (login, consent, 2FA if required) and a reusable token is returned for future queries
  • 0 - No tokenization is performed. The previously obtained token value must be included in the request

Example: 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"
}

List of error codes

List of error codes. Pay special attention to the fact that not all error codes should receive the same treatment from your application. For an incorrect password error, you should not retry the call with the same parameters, but for an error indicating that the entity is under maintenance, you can retry. Request a technical session with our team to resolve any questions about error management.

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

List of warning codes

List of warning codes.

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Advanced

Optional endpoints not required for standard integrations. Use only if explicitly instructed by Wealth Reader.

Retrieves the list of supported entities

This endpoint is optional and not required for standard integrations. Use only if explicitly instructed by Wealth Reader. Retrieves the list of supported entities and the information needed to draw the entity's login form.

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
[
  • {
    }
]

Register a new user

This endpoint is optional and not required for standard integrations. Use only if explicitly instructed by Wealth Reader. This endpoint allows registering a user either on the portfolio transfer platform, Easytransfer, or on the reporting tool, Acumulas, based on a unique identifier.

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.

Example: 12345678A

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

Service associated with the user. Determines the data flow.

Example: easy-transfer

email
required
string <email>

User email, used according to service type.

Example: sai_banker@singularbank.com

Responses

Response samples

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

Check user registration status

This endpoint is optional and not required for standard integrations. Use only if explicitly instructed by Wealth Reader. Checks if a user is registered in the Easytransfer or Acumulas system and returns the unique access link for the user.

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

Authentication key

user_id
required
string

User identification document.

Example: 12345678A

Responses

Response samples

Content type
application/json
{}

Revoke a previously registered user

This endpoint is optional and not required for standard integrations. Use only if explicitly instructed by Wealth Reader. This endpoint allows unregistering a user from the Easytransfer or Acumulas platform service.

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.

Example: 12345678A

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

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

Example: easy-transfer

Responses

Response samples

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

Batch connection loading

This endpoint is optional and not required for standard integrations. Use only if explicitly instructed by Wealth Reader.

Important: To use batch process management on Wealthreader's side, a dedicated environment is required. This endpoint is not available on api.wealthreader.com.

The endpoints grouped under the "batch" tag allow processing multiple bank connections asynchronously, unlike the /entities/ method which is synchronous. Ideal for:

  • Processing large volumes of connections, delegating the process to Wealthreader
  • Avoiding timeouts on slow connections
  • Getting a webhook notification per completed credential

This method starts asynchronous processing of one or multiple bank connections. Immediately returns a batch_id for tracking. A webhook notification is sent to notification_url for each individual credential as soon as it completes, with the following payload fields: batch_id, credential_id, status, timestamp.

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.

Example: 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"
}

Get general statistics about batch connections

This endpoint is optional and not required for standard integrations. Use only if explicitly instructed by Wealth Reader. Retrieves general statistics about the processing result of all connections in a batch.

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": {
    }
}

Get individual result of a specific connection within a batch

This endpoint is optional and not required for standard integrations. Use only if explicitly instructed by Wealth Reader. Retrieves the result of a specific connection from the batch.

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

Account-holder verification: check whether an IBAN belongs to a holder name through the SEPA Verification of Payee (VoP) of the bank linked to your licence. Step-by-step guide: MyBankMatch.

Verify that an IBAN belongs to a holder (MyBankMatch)

Checks whether an IBAN belongs to the indicated holder through the SEPA Verification of Payee (VoP) of your own bank, linked to your WealthReader licence. It returns the bank's verdict: it does not compute a local name similarity and it does not create, authorise or execute any payment order.

Before the first call

  1. Have an active licence with the MY_BANK_MATCH product and available quota.
  2. Open Clients · MyBankMatch, press Connect bank and complete the authentication in the WealthReader hosted window. The tokenised connection is linked to your api_key; the bank token is never returned to the browser nor sent as a parameter.

Request: form-encoded body (application/x-www-form-urlencoded) with api_key, iban and name, like /entities/. No JSON body and no X-API-Key header. Keep the api_key in your backend.

Response: HTTP 200 means a product result was obtained, not that the name matches. Check success and then payload.result:

payload.result Meaning Extra fields Billable
MATCH The bank considers that the name matches the holder. None. Yes, 0.10 EUR.
PARTIAL_MATCH The bank returns a partial match (CLOSE_MATCH). suggested_name. Yes, 0.10 EUR.
NO_MATCH The bank states that the name does not match. None. Yes, 0.10 EUR.
NOT_CONFIGURED The licence has no linked bank yet. setup_url. No.
REAUTH_REQUIRED The bank connection needs a new authentication. setup_url, reason_code. No.
NOT_POSSIBLE A usable verdict could not be obtained. It is not a NO_MATCH. reason. No.

Only MATCH, PARTIAL_MATCH and NO_MATCH consume quota. Input errors and inconclusive results are not billed.

No idempotency key and no free retry. If the response is lost (timeout, network or an unreadable body), the result and its quota consumption may be unknown to your application. Do not resend the same query automatically: check the history in Clients and contact support with statistics.SESSION.

Full guide: MyBankMatch.

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

8 hexadecimal characters of an active licence with the MY_BANK_MATCH product and available quota. Keep it in your backend.

iban
required
string

IBAN of a SEPA country. Spaces are removed, it is uppercased and the country length and the mod-97 check digits are validated.

Example: ES9321005707250200257112

name
required
string <= 140 characters

Holder name. Not empty, valid UTF-8, no control characters and up to 140 characters. It is trimmed and its inner spaces are collapsed.

Example: 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

Account-to-account SEPA payments initiated from the payer's bank. There are two ways to integrate:

  • Fast Track: a single POST /payments/?action=fast-track returns the payment URL and Wealth Reader notifies your notification_url with OK or KO. See Payments Fast Track.
  • Widget: your backend creates an immutable payment intent with POST /payments/?action=create, opens the widget with the returned token and confirms the result with POST /payments/?action=status. See Payments introduction and States and reconciliation.

Common rules for every /payments/?action=... call

  • Method POST with header Content-Type: application/json and a JSON object body (maximum 32768 bytes).
  • Authentication only with the X-API-Key header (wr_live_ followed by 72 letters or digits) of an active licence with the PAYMENTS product. It is never sent in the body. Each authenticated call counts towards the licence call limit.
  • The body is a whitelist: a missing required field or an unexpected one responds 422 invalid_request.
  • The only positive financial confirmation is payment_status: settled. A widget event, an SCA return or interaction_status: completed never mean the payment is settled.

Error format: application/json (not problem+json) with a stable error.code; error.message is informative and may change.

{"success": false, "error": {"code": "invalid_request", "message": "The request body has an invalid schema."}}
HTTP error.code Reason
400 invalid_json Empty or invalid body, or not a JSON object.
401 invalid_api_key Missing, malformed, unknown or inactive X-API-Key.
403 payments_not_allowed The licence does not have the PAYMENTS product.
404 action_not_found Unknown action.
405 method_not_allowed Method other than POST.
413 request_too_large Body larger than 32768 bytes.
415 json_required Content-Type other than application/json.
422 invalid_request Missing or unexpected fields.
429 api_limit_reached The licence call limit has been reached.
500 internal_error Unexpected error.
503 payments_disabled, payments_accept_new_disabled, payment_storage_unavailable, payment_state_unavailable Service temporarily unavailable, or new payments paused.

OK or KO notification of a Fast Track payment Webhook

Wealth Reader sends this POST to the notification_url of a Fast Track payment when it checks the payment status and finds it in a final state. reconciliation_required is not final and is not notified: confirm it with status.

  • outcome is ok only when the bank has settled the payment (settled); rejected, cancelled, expired and failed notify ko.
  • The status is checked while the payer stays on the payment page (it polls until the final result or until the payment session expires) and every time you call status. There is no separate scheduled sender: if the payer leaves before the bank concludes, or your server does not answer 2xx, the notification is sent in the next check. If it has not arrived a few minutes after redirecting the payer, call status with the payment_intent_id; that call also triggers the pending notification.
  • Respond with any 2xx to mark it as delivered. Wealth Reader does not follow redirects and waits at most 3 seconds.
  • The same notification may arrive more than once: treat customer_reference plus outcome as idempotent.
  • The request is not signed. Before delivering valuable goods, confirm the result with status using your X-API-Key and the payment_intent_id of the notification.
header Parameters
User-Agent
required
string
Value: "WealthReader-Payments"
Request Body schema: application/json
required
outcome
required
string
Enum: "ok" "ko"

ok only for settled.

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

Final financial result.

customer_reference
required
string

The Idempotency-Key you sent when creating the payment.

payment_intent_id
required
string <uuid>

Identifier returned by fast-track. Use it to confirm the result with 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"
}

Create a payment and get its URL (Fast Track)

Single call that returns the payment URL. The payer opens it and authorises in their bank; when the payment reaches a final state, Wealth Reader notifies your notification_url with OK or KO (see the notification_url webhook). Underneath, the same immutable intent as create is created: amount, beneficiary and reference are fixed before reaching the browser.

The Idempotency-Key header is also your merchant reference (customer_reference in the notification): you do not send it in the body. Repeating the same key with the same body returns the same URL; reusing it with other data (including another logo) responds 409 idempotency_conflict.

An instant payment has no specific limit in this API: the bank rejects the one it cannot accept, also because of the amount, and that rejection arrives as KO.

header Parameters
X-API-Key
required
string

API key of a licence with the PAYMENTS product. Keep it in your backend.

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

16 to 128 characters; it must start with a letter or digit and contain only letters, digits and . _ : -. A UUID v4 is valid. It is also the merchant reference sent back in the notification.

Request Body schema: application/json
required
amount
required
string

Amount in major units, as a JSON string. "15.50" is 15.50 EUR; an integer without decimals ("15") is also accepted. At most two decimals, so "15.5" and "15.50" are the same amount. Minimum 0.01. The maximum is the limit each customer has configured in their bank.

Example: 15.50

currency
required
string
Value: "EUR"

ISO 4217 currency. Only EUR in this version.

Example: EUR

required
object (payments-beneficiary)

Payee of the transfer. It cannot be changed after the payment is created.

reference
required
string [ 1 .. 140 ] characters

Statement reference, up to 140 characters.

Example: Pedido 78901

priority
required
string
Enum: "normal" "instant"

normal (SEPA credit transfer) or instant (SEPA instant credit transfer).

Example: normal

notification_url
required
string <= 2000 characters

Public https URL that receives the OK or KO notification. No credentials, port 443 if given, and no private, local or metadata addresses.

Example: https://tienda.example.com/pagos/aviso

logo
string <= 2048 characters

Optional. Public https URL of your merchant logo in SVG (the path must end in .svg; query parameters allowed), without credentials, fragment or private addresses, up to 2048 ASCII characters. The payment page shows it above the summary; Wealth Reader does not download it, the payer's browser does. Any other value responds 422 invalid_logo.

Example: https://tienda.example.com/marca/logo.svg

Responses

Request samples

Content type
application/json
{}

Response samples

Create a payment intent (widget)

Creates an immutable payment intent and returns a short-lived token to open the widget in the payer's browser. Amount, beneficiary and reference are fixed in the backend and cannot be modified from the browser. After the widget closes, confirm the result from your backend with status.

There are two body variants:

  • Standard: you set amount_minor, currency, beneficiary, reference, customer_reference and allowed_origin.
  • Managed profile (for example cruz_roja_demo): Wealth Reader fixes beneficiary, reference and limits; you send profile, institution_code, amount_minor, customer_reference and allowed_origin. Get the banks with profile-institutions.

Repeating the same Idempotency-Key with the same body returns the same intent (200, idempotent_replay: true); reusing it with other data responds 409 idempotency_conflict. The key is scoped to your company.

Guide: Intents and idempotency and Widget integration.

header Parameters
X-API-Key
required
string

API key of a licence with the PAYMENTS product. Keep it in your backend.

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

16 to 128 visible ASCII characters. Generate one per payment (a UUID v4 is valid) and reuse it if you retry the call.

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

Amount in minor units (cents) as a JSON integer. 1500 is 15.00 EUR. The maximum is the limit each customer has configured in their bank.

Example: 1500

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

Payee of the transfer. It cannot be changed after the payment is created.

reference
required
string [ 1 .. 140 ] characters

Statement reference, up to 140 characters.

Example: Pedido 78901

customer_reference
required
string <= 128 characters

Your internal reference for the payment. 1 to 128 characters; it starts with a letter or digit and contains only letters, digits and . _ : -.

Example: order-78901

allowed_origin
required
string

Origin (https://host[:port], no path, query or fragment) of the page that opens the widget. The widget only works from that origin.

Example: https://tienda.example.com

locale
string
Value: "es"

Optional. Widget language; only es in this version.

expected_mode
string
Enum: "mock" "live"

Optional. If it does not match the environment, the call responds 409 payment_mode_mismatch instead of creating the payment.

allowed_institution_codes
Array of strings <= 2500 items

Optional. Non-empty list of unique bank codes (see /payments/entities/) the payer may choose from.

Example: 

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

Optional. Public https URL of your logo in SVG (path ending in .svg), without credentials, fragment or private addresses, up to 2048 characters.

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": {
    }
}

Query the status of a payment

Server-to-server query of the status of a payment, until a bank conclusion is reached. A callback, an SCA return or closing the widget are not a financial confirmation: only payment_status: settled is.

Wealth Reader limits external queries per intent; apply backoff in your backend too and do not create another intent while the result is ambiguous.

Ambiguous result: a network failure, timeout or unrecognised response after the initiation was sent changes the intent to reconciliation_required with payment_status: unknown, and the response includes reconciliation. The initiation is never repeated automatically. Keep the identifier and the idempotency key, do not create another intent nor authorise again, and when automatic_recovery is false stop polling and escalate to support with reconciliation.reference.

For Fast Track payments, this query also sends the pending OK/KO notification to notification_url when the payment has reached a final state.

Guide: States, polling and reconciliation.

header Parameters
X-API-Key
required
string

API key of the licence that created the payment.

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

payment.id returned by create (in Fast Track, the payment_intent_id returned by fast-track).

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

refresh
boolean
Default: true

Optional. true asks the bank for the latest status when applicable; false returns the stored status.

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": {
    }
}

List the banks and conditions of a managed profile

Returns the conditions of a managed profile enabled for your company (beneficiary, reference, amount limits) and the banks the payer can choose from. Use the chosen code as institution_code in create.

header Parameters
X-API-Key
required
string

API key of a licence with the PAYMENTS product.

Request Body schema: application/json
required
profile
required
string

Managed profile code.

Example: cruz_roja_demo

Responses

Request samples

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

Response samples

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

List the banks available for payments

Catalogue of banks that can initiate payments, with their logo and supported payment methods. X-API-Key is optional; if you send it, it is validated and counts as a call. It also accepts POST with the same filters in a JSON body, and POST /payments/?action=entities with mandatory X-API-Key.

Unknown filters are ignored and never produce a validation error.

query Parameters
country
string
Example: country=ES

ISO 3166-1 alpha-2 country code. ALL or empty means no filter.

Example: ES

search
string

Case-insensitive text contained in the name or code (alias q).

code
string
Example: code=santander-es

Exact bank code, case-insensitive.

Example: santander-es

payment_method
string
Enum: "sepa_credit_transfer" "instant_sepa_credit_transfer"

Only banks that support this payment method.

limit
integer [ 1 .. 2000 ]

Page size (1 to 2000).

offset
integer >= 0

Number of results to skip.

header Parameters
X-API-Key
string

Optional. If sent, it is validated and counts as a call.

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.

Example: 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.

Example: 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.

Example: a1b2c3d4

enrollment_id
required
string
Example: enrollment_id=0f3a9c7b1d2e4f5a6b7c8d9e0f1a2b3c

Identifier returned by POST /cards/enrollments/.

Example: 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.

Example: a1b2c3d4

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

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

Example: 2026-07-01

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

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

Example: 2026-07-11

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

Filters by the email of the employee.

Example: empleado@cliente.com

since_id
integer
Example: since_id=216

Exclusive cursor on the transaction id, for pagination.

Example: 216

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

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

Example: 500

Responses

Response samples

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