Wealth Reader (8.1.12)

Download OpenAPI specification:

Las APIs regulatorias basadas en PSD2 proporcionan acceso a cierta información financiera como saldos de cuentas bancarias y transacciones. Sin embargo, hay otras fuentes de información patrimonial que no son accesibles por estas APIs. La API de Wealth Reader amplía la información ofrecida por las APIs regulatorias proporcionando acceso en tiempo real a las fuentes patrimoniales adicionales en cualquier entidad del mundo. Existen otros dos documentos relacionados que te ayudarán a integrar la API de Wealth Reader. Uno es la guía de integración del widget Javascript: https://docs-es.wealthreader.com/ y el otro una colección Postman basada en esta documentación. Muy importante: Esta definición de la API está adaptada para los clientes que integran por Widget, por lo que se han omitido algunos parámetros que no son necesarios para este tipo de integración, como pueden ser los de autenticación con el banco, ya que se utilizará token.

Core

API principal requerida para integraciones estándar

Obtiene los activos financieros y el detalle de su composición

Obtiene los activos financieros y el detalle de su composición de carteras de inversión (acciones, fondos, bonos, planes de pensiones, inversiones alternativas, criptoactivos), tarjetas de crédito, seguros y préstamos. Incluye información de titularidad de cada uno de los activos así como identificadores únicos que facilitan el tratamiento del dato. Es posible obtener datos Mock. Consulte con el equipo técnico cómo hacerlo.

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

Identifica al cliente en el servicio

code
string

Nombre de la entidad. El listado completo está disponible con GET

Ejemplo: caixabank

token
string

Identifica la credencial custodiada. El flujo mediante el cual se ha obtenido el token se describe en el documento 'Guía de integración del Widget'. Los siguientes usuarios Mock están disponibles: MOCKDATA, respuesta OK; MOCKOTP, respuesta con desafío OTP; MOCKLOGINKO, respuesta con error de login

Ejemplo: MOCKDATA

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

Lista de tipos de producto de los que se desea obtener información. Acepta múltiples valores separados por comas.

Ejemplo: accounts,portfolios

only_balances
boolean
Default: false

Indica si se desean obtener solo los saldos de los productos en lugar de toda la información disponible. Valor por defecto: false.

Ejemplo: false

fetch_transaction_details
boolean
Default: false

Indica si se deben obtener detalles ampliados de las transacciones cuando el conector de la entidad lo soporte. IMPORTANTE: Activarlo implica realizar una o más navegaciones adicionales por cada transacción para enriquecer la información devuelta. Esto aumentará inevitablemente y de forma significativa el tiempo de ejecución. El número de navegaciones adicionales crece con el volumen de transacciones. Se recomienda activarlo únicamente cuando se tenga certeza de que se requiere un nivel de detalle adicional al devuelto por defecto. Los detalles obtenidos se insertan en la clave additional_info a nivel de cada transacción. El uso de este parámetro requiere un entorno dedicado.

Ejemplo: false

date_from
string <date>

Fecha a partir de la cual se solicitan las transacciones, en formato AAAA-MM-DD. Debe ser una fecha anterior a hoy.

Ejemplo: 2024-01-01

date_to
string <date>

Esto solo aplica para restringir por fechas futuras para productos loan y confirming, en formato AAAA-MM-DD. La fecha debe ser posterior a hoy

Ejemplo: 2025-12-31

required_products_schema
string

Esquema de productos requeridos. Indica las cuentas o tarjetas de las que se desea obtener datos, con configuraciones adicionales.

Ejemplo:

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

Acepta uuids de transacciones separados por comas. Parámetro que solo se tiene en cuenta si product_types es ALL o incluye accounts. Añade el documento PDF asociado a cada una de las transacciones bancarias solicitadas.

Ejemplo:

20966426721d0885ef9d4b95535e1d3198936f16,8772d6c978d37d7af83094abf380b8b703e94105,e59296b79e7f80cec26679d2c65883025fd59295
otp_method
string

Indica qué canal de entrega del segundo factor debe usarse cuando la API devolvió el código 2017 o 20171 (varios métodos OTP). Repita la petición con el mismo identificador de sesión de esa respuesta y envíe en este campo el valor exacto del campo otp_method de uno de los objetos de statistics.otpMethods (no use la posición en el array ni un alias). Opcional en la primera petición con credenciales; debe enviarse tras la elección del usuario. El ejemplo que muestra la referencia (p. ej. OTP_SMS ****1234) es solo orientativo: copie siempre la cadena que devuelve statistics.otpMethods para su entidad (puede ser otro formato, p. ej. SMS *****1234, según el banco).

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

Listado de tipos de transacción

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Consulta los tokens asociados a una api_key

Usa este método para consultar los tokens vinculados a una api_key específica. Los resultados se paginan: limit fija el número de tokens por página (máximo 500) y page indica la página que se devuelve. api_key, method y limit son obligatorios; si falta alguno o no es válido, la API responde con HTTP 400 y el código de error 2.

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

api_key para identificar al cliente en el servicio

method
required
string
Value: "get"

Operación que se realiza. El único valor admitido es get.

Ejemplo: get

limit
required
integer [ 1 .. 500 ]

Número de tokens por página. Mínimo 1, máximo 500.

Ejemplo: 100

page
integer >= 1
Default: 1

Especifica el número de página que deseas recuperar. Cada página contiene hasta limit tokens. Si no se proporciona, el valor por defecto es 1.

Ejemplo: 1

code
string

Código de la entidad por el que se filtran los tokens. Si se omite, se devuelven los tokens de todas las entidades.

Ejemplo: bbva

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

Campo por el que se ordenan los resultados: created_at (fecha de creación) o accesed_at (fecha del último acceso). Por defecto, created_at.

Ejemplo: created_at

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

Sentido de la ordenación: ASC (ascendente) o DESC (descendente). Por defecto, DESC.

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

Revocar un token

Este método permite revocar un token existente para desautorizar futuras solicitudes de acceso a la API.

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

Identifica al cliente en el servicio

token
string

Token a revocar.

Responses

Response samples

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

Reasignar un token a una api_key diferente

Este método permite reasignar un token de una api_key a otra. Ambas api_keys deben estar activas y pertenecer a la misma empresa, y el token debe pertenecer a api_key_source.

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

api_key desde la cual reasignar el token.

api_key_target
string

api_key a la cual reasignar el token.

token
string

Token a reasignar.

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

Añadir un nuevo dominio

Añade la asociación entre dominio que hospedará el widget con el webhook de destino. Para editar o probar sus dominios, use https://www.wealthreader.com/clients/

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

Method to execute.

Ejemplo: add

api_key
required
string

User's API key.

domain
required
string

Domain to add.

Ejemplo: http://desarrollo.cliente.es

url_callback
required
string

URL for callback.

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

tokenize
required
string
Enum: "1" "0"

Controla si el widget inicia un flujo de tokenización:

  • 1 - El usuario se autentica con la entidad financiera (login, consentimiento, 2FA si aplica) y se devuelve un token reutilizable para futuras consultas
  • 0 - No se realiza tokenización. Se debe incluir en la petición el valor del token obtenido previamente

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

Listado de códigos de error

Listado de códigos de error. Presta especial atención a que no todos los códigos de error deben recibir el mismo tratamiento por parte de tu aplicación. Ante un error de password incorrecto no debes reintentar la llamada con los mismos parámetros, pero ante un error que te indique que la entidad está en mantenimiento sí puedes reintentarlo. Pide una sesión técnica con nuestro equipo para resolver cualquier duda sobre la gestión de errores.

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Listado de códigos de warning

Listado de códigos de warning.

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Advanced

Endpoints opcionales no requeridos para integraciones estándar. Usar solo si Wealth Reader lo indica explícitamente.

Obtiene el listado de entidades soportadas

Obtiene el listado de entidades soportadas y la información necesaria para dibujar el formulario de login de la entidad.

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

Registrar un nuevo usuario

Este endpoint permite registrar un usuario ya sea en la plataforma de traspaso de carteras, Easytransfer, como en la herramienta de reporting, Acumulas, en a partir de un identificador único.

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.

Ejemplo: 12345678A

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

Service associated with the user. Determines the data flow.

Ejemplo: easy-transfer

email
required
string <email>

User email, used according to service type.

Ejemplo: sai_banker@singularbank.com

Responses

Response samples

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

Consultar el estado de registro de un usuario

Consulta si un usuario está registrado en el sistema Easytransfer o Acumulas y responde el enlace de acceso único para el usuario.

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

Authentication key

user_id
required
string

User identification document.

Ejemplo: 12345678A

Responses

Response samples

Content type
application/json
{}

Método para dar de baja un usuario previamente registrado

Este endpoint permite dar de baja un usuario del servicio de Easytransfer o plataforma 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.

Ejemplo: 12345678A

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

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

Ejemplo: easy-transfer

Responses

Response samples

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

Carga de conexiones en batch

Los endpoints agrupados en la etiqueta "batch" permiten procesar múltiples conexiones bancarias de forma asíncrona, a diferencia del método /entities/ que es síncrono. Ideal para:

  • Procesar grandes volúmenes de conexiones, delegando el proceso en Wealthreader
  • Evitar timeouts en conexiones lentas
  • Recibir una notificación webhook por cada credencial completada

Importante: Para utilizar la gestión de procesos batch del lado de Wealthreader es necesario contar con un entorno dedicado. Este endpoint no está disponible en api.wealthreader.com.

Este método inicia el procesamiento asíncrono de una o múltiples conexiones bancarias. Retorna inmediatamente un batch_id para seguimiento. Se envía una notificación webhook a notification_url por cada credencial completada individualmente, con los campos: 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.

Ejemplo: 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",
  • "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"
}

Obtiene estadísticas generales sobre las conexiones de un batch

Recupera estadísticas generales sobre el resultado del procesamiento de todas las conexiones de un 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": {
    }
}

Obtiene el resultado individual de una conexión específica dentro de un batch

Recupera el resultado de una conexión específica del 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

Verificación de titularidad: compruebe si un IBAN pertenece a un titular mediante la Verificación del Beneficiario (VoP) SEPA del banco vinculado a su licencia. Guía paso a paso: MyBankMatch.

Verifica que un IBAN pertenece a un titular (MyBankMatch)

Comprueba si un IBAN pertenece al titular indicado mediante la Verificación del Beneficiario (VoP) SEPA de su propio banco, vinculado a su licencia de WealthReader. Devuelve el veredicto del banco: no lo sustituye por un cálculo local de similitud de nombres ni crea, autoriza o ejecuta ninguna orden de pago.

Antes de la primera llamada

  1. Disponga de una licencia activa con el producto MY_BANK_MATCH y cuota disponible.
  2. Abra Clientes · MyBankMatch, pulse Conectar banco y complete la autenticación en la ventana alojada de WealthReader. La conexión tokenizada queda asociada a su api_key; el token bancario no se entrega al navegador ni es un parámetro de la consulta.

Petición: cuerpo codificado como formulario (application/x-www-form-urlencoded) con api_key, iban y name, igual que en /entities/. No se envía JSON ni se usa la cabecera X-API-Key. Mantenga la api_key en su backend.

Respuesta: HTTP 200 indica que se ha obtenido un resultado del producto, no que el nombre coincida. Compruebe success y después payload.result:

payload.result Significado Campos adicionales Facturable
MATCH El banco considera que el nombre coincide con el titular. Ninguno. Sí, 0,10 EUR.
PARTIAL_MATCH El banco devuelve una coincidencia parcial (CLOSE_MATCH). suggested_name. Sí, 0,10 EUR.
NO_MATCH El banco indica que el nombre no coincide. Ninguno. Sí, 0,10 EUR.
NOT_CONFIGURED La licencia todavía no tiene un banco vinculado. setup_url. No.
REAUTH_REQUIRED La conexión con el banco necesita una nueva autenticación. setup_url, reason_code. No.
NOT_POSSIBLE No ha sido posible obtener un veredicto utilizable. No equivale a NO_MATCH. reason. No.

Sólo MATCH, PARTIAL_MATCH y NO_MATCH consumen cuota. Los errores de entrada y los resultados no concluyentes no se facturan.

No hay clave de idempotencia ni reintento gratuito. Si pierde la respuesta (timeout, red o un cuerpo no interpretable), el resultado y su consumo de cuota pueden ser desconocidos para su aplicación. No vuelva a enviar automáticamente la misma consulta: revise el historial en Clientes y consulte con soporte indicando statistics.SESSION.

Guía completa: MyBankMatch.

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

Clave de 8 caracteres hexadecimales de una licencia activa con el producto MY_BANK_MATCH y cuota disponible. Manténgala en su backend.

iban
required
string

IBAN de un país SEPA. Se eliminan los espacios, se pasa a mayúsculas y se validan la longitud de su país y los dígitos de control mod-97.

Ejemplo: ES9321005707250200257112

name
required
string <= 140 characters

Nombre del titular. No vacío, UTF-8 válido, sin caracteres de control y hasta 140 caracteres. Se recorta y se colapsan los espacios internos.

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

Pagos SEPA de cuenta a cuenta iniciados desde el banco del pagador. Hay dos formas de integrarlos:

  • Fast Track: un único POST /payments/?action=fast-track devuelve la URL de pago y Wealth Reader avisa a su notification_url con OK o KO. Consulte Pagos Fast Track.
  • Widget: su backend crea una intención de pago inmutable con POST /payments/?action=create, abre el widget con el token devuelto y confirma el resultado con POST /payments/?action=status. Consulte Introducción a pagos y Estados, sondeo y conciliación.

Reglas comunes a todas las llamadas /payments/?action=...

  • Método POST con la cabecera Content-Type: application/json y un objeto JSON como cuerpo (máximo 32768 bytes).
  • Autenticación sólo con la cabecera X-API-Key (wr_live_ seguido de 72 letras o dígitos) de una licencia activa con el producto PAYMENTS. Nunca se envía en el cuerpo. Cada llamada autenticada cuenta para el límite de llamadas de la licencia.
  • El cuerpo es una lista blanca: un campo obligatorio que falte o uno no previsto responde 422 invalid_request.
  • La única confirmación financiera positiva es payment_status: settled. Un evento del widget, un retorno SCA o interaction_status: completed nunca significan que el pago esté liquidado.

Formato de error: application/json (no problem+json) con un error.code estable; error.message es informativo y puede cambiar.

{"success": false, "error": {"code": "invalid_request", "message": "The request body has an invalid schema."}}
HTTP error.code Motivo
400 invalid_json Cuerpo vacío, no válido o que no es un objeto JSON.
401 invalid_api_key X-API-Key ausente, mal formada, desconocida o inactiva.
403 payments_not_allowed La licencia no tiene el producto PAYMENTS.
404 action_not_found action desconocida.
405 method_not_allowed Método distinto de POST.
413 request_too_large Cuerpo de más de 32768 bytes.
415 json_required Content-Type distinto de application/json.
422 invalid_request Campos que faltan o no previstos.
429 api_limit_reached Se ha alcanzado el límite de llamadas de la licencia.
500 internal_error Error inesperado.
503 payments_disabled, payments_accept_new_disabled, payment_storage_unavailable, payment_state_unavailable Servicio no disponible temporalmente o nuevos pagos en pausa.

Aviso de OK o KO de un pago Fast Track Webhook

Wealth Reader envía este POST a la notification_url de un pago Fast Track cuando comprueba el estado del pago y lo encuentra en un estado final. reconciliation_required no es final y no se avisa: confírmelo con status.

  • outcome es ok sólo si el banco ha liquidado el pago (settled); rejected, cancelled, expired y failed avisan ko.
  • El estado se comprueba mientras el pagador sigue en la página de pago (la consulta hasta el resultado final o hasta que caduca la sesión de pago) y cada vez que usted llama a status. No hay un envío programado aparte: si el pagador se va antes de que el banco concluya, o su servidor no responde 2xx, el aviso se envía en la siguiente comprobación. Si no ha llegado unos minutos después de redirigir al pagador, llame a status con el payment_intent_id; esa llamada también dispara el aviso pendiente.
  • Responda con cualquier 2xx para darlo por entregado. Wealth Reader no sigue redirecciones y espera como máximo 3 segundos.
  • El mismo aviso puede llegar más de una vez: trate customer_reference más outcome como idempotentes.
  • La petición no va firmada. Antes de entregar un bien valioso, confirme el resultado con status usando su X-API-Key y el payment_intent_id del aviso.
header Parameters
User-Agent
required
string
Value: "WealthReader-Payments"
Request Body schema: application/json
required
outcome
required
string
Enum: "ok" "ko"

ok sólo para settled.

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

Resultado financiero final.

customer_reference
required
string

La Idempotency-Key que envió al crear el pago.

payment_intent_id
required
string <uuid>

Identificador que devolvió fast-track. Úselo para confirmar el resultado con 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"
}

Crea un pago y obtiene su URL (Fast Track)

Una sola llamada que devuelve la URL de pago. El pagador la abre y autoriza en su banco; cuando el pago llega a un estado final, Wealth Reader avisa a su notification_url con OK o KO (vea el webhook notification_url). Por debajo se crea la misma intención inmutable que con create: importe, beneficiario y concepto quedan fijados antes de llegar al navegador.

La cabecera Idempotency-Key es también su referencia de comercio (customer_reference en el aviso): no se envía en el cuerpo. Si repite la misma clave con el mismo cuerpo, recibe la misma URL; si la reutiliza con otros datos (también con otro logo), la respuesta es 409 idempotency_conflict.

Una transferencia inmediata no tiene un tope propio en esta API: el banco rechaza la que no puede aceptar, también por importe, y ese rechazo llega como KO.

header Parameters
X-API-Key
required
string

Clave de API de una licencia con el producto PAYMENTS. Manténgala en su backend.

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

De 16 a 128 caracteres; debe empezar por letra o dígito y contener sólo letras, dígitos y . _ : -. Un UUID v4 es válido. Es también la referencia de comercio que se devuelve en el aviso.

Request Body schema: application/json
required
amount
required
string

Importe en unidades mayores, como cadena JSON. "15.50" son 15,50 EUR; también se admite un entero sin decimales ("15"). Como máximo dos decimales, así que "15.5" y "15.50" son el mismo importe. Mínimo 0.01. El máximo está limitado al límite que cada cliente tenga configurado en su banco.

Ejemplo: 15.50

currency
required
string
Value: "EUR"

Divisa ISO 4217. En esta versión, sólo EUR.

Ejemplo: EUR

required
object (payments-beneficiary)

Destinatario de la transferencia. No puede cambiarse una vez creado el pago.

reference
required
string [ 1 .. 140 ] characters

Concepto del extracto, hasta 140 caracteres.

Ejemplo: Pedido 78901

priority
required
string
Enum: "normal" "instant"

normal (transferencia SEPA) o instant (transferencia SEPA inmediata).

Ejemplo: normal

notification_url
required
string <= 2000 characters

URL https pública que recibe el aviso de OK o KO. Sin credenciales, puerto 443 si se indica y sin direcciones privadas, locales ni de metadatos.

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

logo
string <= 2048 characters

Opcional. URL https pública del logotipo de su comercio en SVG (la ruta debe terminar en .svg; admite parámetros de consulta), sin credenciales, fragmento ni direcciones privadas, hasta 2048 caracteres ASCII. La página de pago lo muestra encima del resumen; Wealth Reader no la descarga, la carga el navegador del pagador. Cualquier otro valor responde 422 invalid_logo.

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

Responses

Request samples

Content type
application/json
{}

Response samples

Crea una intención de pago (widget)

Crea una intención de pago inmutable y devuelve un token de corta duración para abrir el widget en el navegador del pagador. Importe, beneficiario y concepto quedan fijados en el backend y no se pueden modificar desde el navegador. Tras cerrarse el widget, confirme el resultado desde su backend con status.

Hay dos variantes de cuerpo:

  • Estándar: usted fija amount_minor, currency, beneficiary, reference, customer_reference y allowed_origin.
  • Perfil administrado (por ejemplo cruz_roja_demo): Wealth Reader fija beneficiario, concepto y límites; usted envía profile, institution_code, amount_minor, customer_reference y allowed_origin. Obtenga los bancos con profile-institutions.

Si repite la misma Idempotency-Key con el mismo cuerpo, recibe la misma intención (200, idempotent_replay: true); si la reutiliza con otros datos, la respuesta es 409 idempotency_conflict. La clave es propia de su empresa.

Guía: Intenciones e idempotencia e Integración con el widget.

header Parameters
X-API-Key
required
string

Clave de API de una licencia con el producto PAYMENTS. Manténgala en su backend.

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

De 16 a 128 caracteres ASCII visibles. Genere una por pago (un UUID v4 es válido) y reutilícela si reintenta la llamada.

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

Importe en unidades menores (céntimos) como entero JSON. 1500 son 15,00 EUR. El máximo está limitado al límite que cada cliente tenga configurado en su banco.

Ejemplo: 1500

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

Destinatario de la transferencia. No puede cambiarse una vez creado el pago.

reference
required
string [ 1 .. 140 ] characters

Concepto del extracto, hasta 140 caracteres.

Ejemplo: Pedido 78901

customer_reference
required
string <= 128 characters

Su referencia interna del pago. De 1 a 128 caracteres; empieza por letra o dígito y contiene sólo letras, dígitos y . _ : -.

Ejemplo: order-78901

allowed_origin
required
string

Origen (https://host[:puerto], sin ruta, consulta ni fragmento) de la página que abre el widget. El widget sólo funciona desde ese origen.

Ejemplo: https://tienda.example.com

locale
string
Value: "es"

Opcional. Idioma del widget; en esta versión sólo es.

expected_mode
string
Enum: "mock" "live"

Opcional. Si no coincide con el entorno, la llamada responde 409 payment_mode_mismatch en lugar de crear el pago.

allowed_institution_codes
Array of strings <= 2500 items

Opcional. Lista no vacía de códigos de banco únicos (vea /payments/entities/) entre los que puede elegir el pagador.

Ejemplo:

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

Opcional. URL https pública de su logotipo en SVG (ruta terminada en .svg), sin credenciales, fragmento ni direcciones privadas, hasta 2048 caracteres.

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

Consulta el estado de un pago

Consulta servidor a servidor del estado de un pago, hasta obtener una conclusión bancaria. Un callback, un retorno SCA o el cierre del widget no son una confirmación financiera: sólo lo es payment_status: settled.

Wealth Reader limita las consultas externas por intención; aplique backoff también en su backend y no cree otra intención mientras el resultado sea ambiguo.

Resultado ambiguo: una caída de red, timeout o respuesta no reconocida después de emitir el inicio cambia la intención a reconciliation_required con payment_status: unknown, y la respuesta incluye reconciliation. La iniciación nunca se repite automáticamente. Conserve el identificador y la clave de idempotencia, no cree otra intención ni vuelva a autorizar y, cuando automatic_recovery sea false, deje de sondear y escale a soporte con reconciliation.reference.

En los pagos Fast Track, esta consulta también envía a notification_url el aviso de OK/KO pendiente cuando el pago ha llegado a un estado final.

Guía: Estados, sondeo y conciliación.

header Parameters
X-API-Key
required
string

Clave de API de la licencia que creó el pago.

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

payment.id devuelto por create (en Fast Track, el payment_intent_id que devuelve fast-track).

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

refresh
boolean
Default: true

Opcional. true consulta al banco el último estado cuando procede; false devuelve el estado almacenado.

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

Lista los bancos y condiciones de un perfil administrado

Devuelve las condiciones de un perfil administrado habilitado para su empresa (beneficiario, concepto, límites de importe) y los bancos que puede elegir el pagador. Use el code elegido como institution_code en create.

header Parameters
X-API-Key
required
string

Clave de API de una licencia con el producto PAYMENTS.

Request Body schema: application/json
required
profile
required
string

Código del perfil administrado.

Ejemplo: cruz_roja_demo

Responses

Request samples

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

Response samples

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

Lista los bancos disponibles para pagos

Catálogo de bancos que pueden iniciar pagos, con su logotipo y los métodos de pago que admiten. X-API-Key es opcional; si la envía, se valida y cuenta como llamada. También admite POST con los mismos filtros en un cuerpo JSON, y POST /payments/?action=entities con X-API-Key obligatoria.

Los filtros desconocidos se ignoran y nunca producen un error de validación.

query Parameters
country
string
Example: country=ES

Código de país ISO 3166-1 alfa-2. ALL o vacío significa sin filtro.

Ejemplo: ES

search
string

Texto contenido en el nombre o el código, sin distinguir mayúsculas (alias q).

code
string
Example: code=santander-es

Código exacto del banco, sin distinguir mayúsculas.

Ejemplo: santander-es

payment_method
string
Enum: "sepa_credit_transfer" "instant_sepa_credit_transfer"

Sólo los bancos que admiten este método de pago.

limit
integer [ 1 .. 2000 ]

Tamaño de página (de 1 a 2000).

offset
integer >= 0

Número de resultados que se omiten.

header Parameters
X-API-Key
string

Opcional. Si se envía, se valida y cuenta como llamada.

Responses

Response samples

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

Cards (real time)

Sincronización de gastos de tarjeta en tiempo real desde la app móvil Open Sync: pre-registro de empleados por cliente, webhooks firmados (card_transaction.created / card_enrollment.confirmed), y consulta / backfill por API REST.

Registrar o rotar el webhook de tarjetas en tiempo real

Da de alta o actualiza la URL de webhook del cliente para los eventos card_transaction.created y card_enrollment.confirmed (ver el esquema cards-webhook-delivery para el formato de entrega y la firma). En el primer alta, o cuando rotate_secret es true, se genera un webhook_secret nuevo (64 caracteres hex) que se devuelve una única vez; en cualquier otro caso webhook_secret viene null en la respuesta y no se puede volver a leer. webhook_url debe ser siempre https:// y resolver a un host público: se rechazan localhost y las direcciones privadas, de loopback, link-local (incluida la de metadatos de cloud), CGNAT, multicast y reservadas, escritas en cualquier notación (hexadecimal, decimal, octal, punteada corta o IPv6 con IPv4 embebida), y también los nombres que no resuelven. La misma comprobación se repite justo antes de cada envío, no sólo al registrar: si el host se repunta después a una dirección interna (DNS rebinding), la entrega se cierra como failed con response_excerpt "blocked_host". Enviar null en webhook_url desactiva los webhooks para ese cliente; omitir el campo deja la URL guardada como estaba, que es la forma de rotar el secreto sin tocar la URL.

Request Body schema: application/json
required
api_key
required
string

API key del cliente.

webhook_url
string or null

URL https:// que recibirá los eventos, en un host público que resuelva en DNS. null desactiva los webhooks; omitir el campo deja la URL guardada sin cambios.

Ejemplo: https://cliente.example.com/webhooks/wealthreader-cards

rotate_secret
boolean
Default: false

Si es true, genera y devuelve un webhook_secret nuevo.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Pre-registrar el email de un empleado

Da de alta una solicitud de alta ("enrollment") en estado pending con una caducidad corta (ttl_minutes, 20 por defecto, entre 1 y 60) para que el empleado la confirme abriendo la app móvil e introduciendo ese email (POST /user-sync-validation/, sin cambios de contrato para la app). Es idempotente: repetir la llamada para el mismo (api_key, email) mientras siga pending y sin caducar devuelve la misma solicitud. Si el email ya está vinculado al mismo cliente que llama, devuelve status "active" directamente. Si ya está vinculado a otro cliente distinto, devuelve 409. Límite de frecuencia: máximo 60 llamadas a este endpoint por api_key cada 60 segundos, contando todos los intentos y no sólo los que crean una fila, y comprobado antes que nada para que las respuestas que no crean nada (200 ya activo, 409 vinculado a otro cliente, 400) no sirvan como oráculo de enumeración. Superarlo devuelve 429 con code rate_limited.

Request Body schema: application/json
required
api_key
required
string

API key del cliente.

email
required
string <email>

Email del empleado a pre-registrar.

Ejemplo: empleado@cliente.com

ttl_minutes
integer [ 1 .. 60 ]
Default: 20

Minutos de validez de la solicitud antes de expirar.

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

Consultar el estado de un enrollment

Lectura del estado de una solicitud de alta. No tiene efectos secundarios sobre los usuarios de tarjetas, a diferencia de POST /user-sync-validation/, que sí confirma. La única escritura permitida es marcar como expired, de forma perezosa, un enrollment pending cuya fecha de caducidad ya pasó.

query Parameters
api_key
required
string
Example: api_key=a1b2c3d4

API key del cliente. Ojo: viaja en la query string, así que queda registrada en los logs de acceso y en los proxies intermedios.

Ejemplo: a1b2c3d4

enrollment_id
required
string
Example: enrollment_id=0f3a9c7b1d2e4f5a6b7c8d9e0f1a2b3c

Identificador devuelto por POST /cards/enrollments/.

Ejemplo: 0f3a9c7b1d2e4f5a6b7c8d9e0f1a2b3c

Responses

Response samples

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

Consultar / backfill de movimientos de tarjeta en tiempo real

Devuelve los movimientos de tarjeta recibidos en tiempo real para los empleados vinculados a esta api_key, ordenados por id ascendente. Pensado tanto para backfill periódico (sondear con date_from/date_to y paginar con since_id) como para consulta puntual. Es el mismo objeto de transacción que viaja en el webhook card_transaction.created.

query Parameters
api_key
required
string
Example: api_key=a1b2c3d4

API key del cliente. Ojo: viaja en la query string, así que queda registrada en los logs de acceso y en los proxies intermedios.

Ejemplo: a1b2c3d4

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

YYYY-MM-DD, sobre fecha_operacion. Por defecto: hoy menos 3 días.

Ejemplo: 2026-07-01

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

YYYY-MM-DD, sobre fecha_operacion. Por defecto: hoy.

Ejemplo: 2026-07-11

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

Filtra por el email del empleado.

Ejemplo: empleado@cliente.com

since_id
integer
Example: since_id=216

Cursor exclusivo sobre el id de la transacción, para paginar.

Ejemplo: 216

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

Máximo de movimientos a devolver (por defecto 500, máximo 1000).

Ejemplo: 500

Responses

Response samples

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