API docs by Redocly

Wealth Reader (8.1.12)

Download OpenAPI specification:

E-mail: info@wealthreader.com

Les APIs reguladores basades en PSD2 proporcionen accés a certa informació financera com saldos de comptes bancaris i transaccions. No obstant això, hi ha altres fonts d'informació patrimonial que no són accessibles per aquestes APIs. L'API de Wealth Reader amplia la informació oferta per les APIs reguladores proporcionant accés en temps real a les fonts patrimonials addicionals en qualsevol entitat del món. Hi ha dos altres documents relacionats que t'ajudaran a integrar l'API de Wealth Reader. Un és la guia d'integració del widget Javascript: https://docs-es.wealthreader.com/ i l'altre és una col·lecció Postman basada en aquesta documentació. Molt important: Aquesta definició de l'API està adaptada per als clients que integren per Widget, per la qual cosa s'han omès alguns paràmetres que no són necessaris per a aquest tipus d'integració, com poden ser els d'autenticació amb el banc, ja que s'utilitzarà un token.

Core

API principal requerida per a integracions estàndard

Obté els actius financers i el detall de la seva composició

Obté els actius financers i el detall de la seva composició de carteres d'inversió compostes per accions o fons, targetes de crèdit, assegurances i préstecs. Inclou informació de titularitat de cadascun dels actius així com identificadors únics que faciliten el tractament de la dada. És possible obtenir dades Mock. Consulteu amb l'equip tècnic com fer-ho.

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

Identifica el client en el servei

code
string

Nom de l'entitat. El llistat complet està disponible amb GET

Exemple: caixabank

token
string

Identifica la credencial custodiada. El flux mitjançant el qual s'ha obtingut el token es descriu al document 'Guia d'integració del Widget'. Els següents usuaris Mock estan disponibles: MOCKDATA, resposta OK; MOCKOTP, resposta amb desafiament OTP; MOCKLOGINKO, resposta amb error de login

Exemple: MOCKDATA

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

Llista de tipus de producte dels quals es vol obtenir informació. Accepta múltiples valors separats per comes.

Exemple: accounts,portfolios

only_balances
boolean
Default: false

Indica si es desitgen obtenir només els saldos dels productes en lloc de tota la informació disponible. Valor per defecte: false.

Exemple: false

fetch_transaction_details
boolean
Default: false

Indica si s'han d'obtenir detalls ampliats de les transaccions quan el connector de l'entitat ho admeti. IMPORTANT: Activar-ho implica fer una o més navegacions addicionals per cada transacció per enriquir la informació retornada. Això augmentarà inevitablement i de manera significativa el temps d'execució. El nombre de navegacions addicionals creix amb el volum de transaccions. Es recomana activar-ho únicament quan es tingui certesa que es requereix un nivell de detall addicional al retornat per defecte. Els detalls obtinguts s'insereixen a la clau additional_info a nivell de cada transacció. L'ús d'aquest paràmetre requereix un entorn dedicat.

Exemple: false

date_from
string <date>

Data a partir de la qual es sol·liciten les transaccions, en format AAAA-MM-DD. Ha de ser una data anterior a avui.

Exemple: 2024-01-01

date_to
string <date>

Això només s'aplica per restringir per dates futures per als productes loan i confirming, en format AAAA-MM-DD. La data ha de ser posterior a avui

Exemple: 2025-12-31

required_products_schema
string

Esquema de productes requerits. Indica els comptes o targetes dels quals es desitgen obtenir dades, amb configuracions addicionals.

Exemple: 

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

Accepta uuids de transaccions separats per comes. Paràmetre que només es té en compte si product_types és ALL o inclou accounts. Afegeix el document PDF associat a cadascuna de les transaccions bancàries sol·licitades.

Exemple: 

20966426721d0885ef9d4b95535e1d3198936f16,8772d6c978d37d7af83094abf380b8b703e94105,e59296b79e7f80cec26679d2c65883025fd59295
otp_method
string

Indica quin canal d'entrega del segon factor usar quan l'API ha retornat el codi 2017 o 20171 (diversos mètodes OTP). Torneu a cridar amb el mateix identificador de sessió d'aquesta resposta i definiu otp_method al text exacte del camp otp_method d'un objecte a statistics.otpMethods; no useu l'índex de l'array. Opcional en la primera petició amb credencials; envieu-lo després de l'elecció de l'usuari. L'exemple de la referència és orientatiu; copieu sempre la cadena que retorna statistics.otpMethods.

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

Llista de tipus de transacció

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Consulta els tokens associats a una api_key

Utilitza aquest mètode per consultar els tokens vinculats a una api_key específica. Els resultats es paginen: limit fixa el nombre de tokens per pàgina (màxim 500) i page indica la pàgina que es retorna. api_key, method i limit són obligatoris; si en falta algun o no és vàlid, l'API respon amb HTTP 400 i el codi d'error 2.

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

api_key per identificar el client en el servei

method
required
string
Value: "get"

Operació que es realitza. L'únic valor admès és get.

Exemple: get

limit
required
integer [ 1 .. 500 ]

Nombre de tokens per pàgina. Mínim 1, màxim 500.

Exemple: 100

page
integer >= 1
Default: 1

Especifica el número de pàgina que vols recuperar. Cada pàgina conté fins a limit tokens. Si no es proporciona, el valor per defecte és 1.

Exemple: 1

code
string

Codi de l'entitat pel qual es filtren els tokens. Si s'omet, es retornen els tokens de totes les entitats.

Exemple: bbva

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

Camp pel qual s'ordenen els resultats: created_at (data de creació) o accesed_at (data de l'últim accés). Per defecte, created_at.

Exemple: created_at

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

Sentit de l'ordenació: ASC (ascendent) o DESC (descendent). Per defecte, DESC.

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

Aquest mètode permet revocar un token existent per desautoritzar futures sol·licituds d'accés a l'API.

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

Identifica el client en el servei

token
string

Token a revocar.

Responses

Response samples

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

Reassignar un token a una api_key diferent

Aquest mètode permet reassignar un token d'una api_key a una altra. Les dues api_keys han d'estar actives i pertànyer a la mateixa empresa, i el token ha de pertànyer a api_key_source.

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

api_key des de la qual reassignar el token.

api_key_target
string

api_key a la qual reassignar el token.

token
string

Token a reassignar.

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

Afegir un nou domini

Afegeix l'associació entre el domini que hostatjarà el widget i el webhook de destinació. Per editar o provar els seus dominis, utilitzi https://www.wealthreader.com/clients/

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

Method to execute.

Exemple: add

api_key
required
string

User's API key.

domain
required
string

Domain to add.

Exemple: http://desarrollo.cliente.es

url_callback
required
string

URL for callback.

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

tokenize
required
string
Enum: "1" "0"

Controla si el widget inicia un flux de tokenització:

  • 1 - L'usuari s'autentica amb l'entitat financera (login, consentiment, 2FA si cal) i es retorna un token reutilitzable per a futures consultes
  • 0 - No es realitza tokenització. S'ha d'incloure a la petició el valor del token obtingut prèviament

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

Llista de codis d'error

Llista de codis d'error. Presta especial atenció al fet que no tots els codis d'error han de rebre el mateix tractament per part de la teva aplicació. Davant d'un error de contrasenya incorrecta no has de reintentar la crida amb els mateixos paràmetres, però davant d'un error que t'indiqui que l'entitat està en manteniment sí que pots reintentar-ho. Demana una sessió tècnica amb el nostre equip per resoldre qualsevol dubte sobre la gestió d'errors.

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Llista de codis d'advertència

Llista de codis d'advertència.

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Advanced

Punts finals opcionals no requerits per a integracions estàndard. Utilitzar només si Wealth Reader ho indica explícitament.

Obté el llistat d'entitats suportades

Obté el llistat d'entitats suportades i la informació necessària per dibuixar el formulari de login de l'entitat.

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 nou usuari

Aquest endpoint és opcional i no és necessari per a integracions estàndard. Utilitzar només si Wealth Reader ho indica explícitament. Aquest endpoint permet registrar un usuari ja sigui a la plataforma de traspàs de carteres Easytransfer o a l'eina de reporting Acumulas, a partir d'un identificador únic.

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.

Exemple: 12345678A

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

Service associated with the user. Determines the data flow.

Exemple: easy-transfer

email
required
string <email>

User email, used according to service type.

Exemple: sai_banker@singularbank.com

Responses

Response samples

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

Consultar l'estat de registre d'un usuari

Aquest endpoint és opcional i no és necessari per a integracions estàndard. Utilitzar només si Wealth Reader ho indica explícitament. Consulta si un usuari està registrat al sistema Easytransfer o Acumulas i retorna l'enllaç d'accés únic per a l'usuari.

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

Authentication key

user_id
required
string

User identification document.

Exemple: 12345678A

Responses

Response samples

Content type
application/json
{}

Donar de baixa un usuari prèviament registrat

Aquest endpoint és opcional i no és necessari per a integracions estàndard. Utilitzar només si Wealth Reader ho indica explícitament. Aquest endpoint permet donar de baixa un usuari del servei de la plataforma Easytransfer o 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.

Exemple: 12345678A

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

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

Exemple: easy-transfer

Responses

Response samples

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

Càrrega de connexions en batch

Aquest endpoint és opcional i no és necessari per a integracions estàndard. Utilitzar només si Wealth Reader ho indica explícitament. Important: Per utilitzar la gestió de processos batch del costat de Wealthreader és necessari comptar amb un entorn dedicat. Aquest endpoint no està disponible a api.wealthreader.com. Els endpoints agrupats sota l'etiqueta "batch" permeten processar múltiples connexions bancàries de forma asíncrona, a diferència del mètode /entities/ que és síncron. Ideal per processar grans volums de connexions i evitar timeouts.

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.

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

Obtenir estadístiques generals sobre les connexions del batch

Aquest endpoint és opcional. Recupera estadístiques generals sobre el resultat del processament de totes les connexions d'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": {
    }
}

Obtenir el resultat individual d'una connexió específica dins d'un batch

Aquest endpoint és opcional. Recupera el resultat d'una connexió 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ó de titularitat: comproveu si un IBAN pertany a un titular mitjançant la Verificació del Beneficiari (VoP) SEPA del banc vinculat a la vostra llicència. Guia pas a pas: MyBankMatch.

Verifica que un IBAN pertany a un titular (MyBankMatch)

Comprova si un IBAN pertany al titular indicat mitjançant la Verificació del Beneficiari (VoP) SEPA del vostre propi banc, vinculat a la vostra llicència de WealthReader. Retorna el veredicte del banc: no el substitueix per un càlcul local de similitud de noms ni crea, autoritza o executa cap ordre de pagament.

Abans de la primera crida

  1. Disposeu d'una llicència activa amb el producte MY_BANK_MATCH i quota disponible.
  2. Obriu Clients · MyBankMatch, premeu Connectar banc i completeu l'autenticació a la finestra allotjada de WealthReader. La connexió tokenitzada queda associada a la vostra api_key; el token bancari no es lliura al navegador ni és un paràmetre de la consulta.

Petició: cos codificat com a formulari (application/x-www-form-urlencoded) amb api_key, iban i name, igual que a /entities/. No s'envia JSON ni s'utilitza la capçalera X-API-Key. Mantingueu la api_key al vostre backend.

Resposta: HTTP 200 indica que s'ha obtingut un resultat del producte, no que el nom coincideixi. Comproveu success i després payload.result:

payload.result Significat Camps addicionals Facturable
MATCH El banc considera que el nom coincideix amb el titular. Cap. Sí, 0,10 EUR.
PARTIAL_MATCH El banc retorna una coincidència parcial (CLOSE_MATCH). suggested_name. Sí, 0,10 EUR.
NO_MATCH El banc indica que el nom no coincideix. Cap. Sí, 0,10 EUR.
NOT_CONFIGURED La llicència encara no té cap banc vinculat. setup_url. No.
REAUTH_REQUIRED La connexió amb el banc necessita una nova autenticació. setup_url, reason_code. No.
NOT_POSSIBLE No ha estat possible obtenir un veredicte utilitzable. No equival a NO_MATCH. reason. No.

Només MATCH, PARTIAL_MATCH i NO_MATCH consumeixen quota. Els errors d'entrada i els resultats no concloents no es facturen.

No hi ha clau d'idempotència ni reintent gratuït. Si perdeu la resposta (timeout, xarxa o un cos no interpretable), el resultat i el consum de quota corresponent poden ser desconeguts per a la vostra aplicació. No torneu a enviar automàticament la mateixa consulta: reviseu l'historial a Clients i consulteu el suport indicant statistics.SESSION.

Guia completa: MyBankMatch.

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

Clau de 8 caràcters hexadecimals d'una llicència activa amb el producte MY_BANK_MATCH i quota disponible. Mantingueu-la al vostre backend.

iban
required
string

IBAN d'un país SEPA. S'eliminen els espais, es passa a majúscules i es validen la longitud del país corresponent i els dígits de control mod-97.

Exemple: ES9321005707250200257112

name
required
string <= 140 characters

Nom del titular. No buit, UTF-8 vàlid, sense caràcters de control i fins a 140 caràcters. Es retallen els extrems i es col·lapsen els espais interns.

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

Pagaments SEPA de compte a compte iniciats des del banc del pagador. Hi ha dues maneres d'integrar-los:

  • Fast Track: un únic POST /payments/?action=fast-track retorna l'URL de pagament i Wealth Reader avisa la vostra notification_url amb OK o KO. Consulteu Pagaments Fast Track.
  • Widget: el vostre backend crea una intenció de pagament immutable amb POST /payments/?action=create, obre el widget amb el token retornat i confirma el resultat amb POST /payments/?action=status. Consulteu Introducció als pagaments i Estats, sondeig i conciliació.

Regles comunes a totes les crides /payments/?action=...

  • Mètode POST amb la capçalera Content-Type: application/json i un objecte JSON com a cos (màxim de 32768 bytes).
  • Autenticació només amb la capçalera X-API-Key (wr_live_ seguit de 72 lletres o dígits) d'una llicència activa amb el producte PAYMENTS. Mai no s'envia en el cos. Cada crida autenticada compta per al límit de crides de la llicència.
  • El cos és una llista blanca: si falta un camp obligatori o n'hi ha un de no previst, la resposta és 422 invalid_request.
  • L'única confirmació financera positiva és payment_status: settled. Un esdeveniment del widget, un retorn SCA o interaction_status: completed mai no signifiquen que el pagament estigui liquidat.

Format d'error: application/json (no problem+json) amb un error.code estable; error.message és informatiu i pot canviar.

{"success": false, "error": {"code": "invalid_request", "message": "The request body has an invalid schema."}}
HTTP error.code Motiu
400 invalid_json Cos buit, no vàlid o que no és un objecte JSON.
401 invalid_api_key X-API-Key absent, mal formada, desconeguda o inactiva.
403 payments_not_allowed La llicència no té el producte PAYMENTS.
404 action_not_found action desconeguda.
405 method_not_allowed Mètode diferent de POST.
413 request_too_large Cos de més de 32768 bytes.
415 json_required Content-Type diferent de application/json.
422 invalid_request Camps que falten o no previstos.
429 api_limit_reached S'ha assolit el límit de crides de la llicència.
500 internal_error Error inesperat.
503 payments_disabled, payments_accept_new_disabled, payment_storage_unavailable, payment_state_unavailable Servei no disponible temporalment o pagaments nous en pausa.

Avís d'OK o KO d'un pagament Fast Track Webhook

Wealth Reader envia aquest POST a la notification_url d'un pagament Fast Track quan comprova l'estat del pagament i el troba en un estat final. reconciliation_required no és final i no s'avisa: confirmeu-lo amb status.

  • outcome és ok només si el banc ha liquidat el pagament (settled); rejected, cancelled, expired i failed avisen ko.
  • L'estat es comprova mentre el pagador continua a la pàgina de pagament (que el consulta fins al resultat final o fins que caduca la sessió de pagament) i cada vegada que crideu status. No hi ha cap enviament programat a part: si el pagador marxa abans que el banc conclogui, o el vostre servidor no respon 2xx, l'avís s'envia en la comprovació següent. Si no ha arribat uns minuts després de redirigir el pagador, crideu status amb el payment_intent_id; aquesta crida també desencadena l'avís pendent.
  • Responeu amb qualsevol 2xx per donar-lo per lliurat. Wealth Reader no segueix redireccions i espera com a màxim 3 segons.
  • El mateix avís pot arribar més d'una vegada: tracteu customer_reference més outcome com a idempotents.
  • La petició no va signada. Abans de lliurar un bé valuós, confirmeu el resultat amb status utilitzant la vostra X-API-Key i el payment_intent_id de l'avís.
header Parameters
User-Agent
required
string
Value: "WealthReader-Payments"
Request Body schema: application/json
required
outcome
required
string
Enum: "ok" "ko"

ok només per a settled.

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

Resultat financer final.

customer_reference
required
string

La Idempotency-Key que vau enviar en crear el pagament.

payment_intent_id
required
string <uuid>

Identificador que va retornar fast-track. Utilitzeu-lo per confirmar el resultat amb 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 pagament i n'obté l'URL (Fast Track)

Una sola crida que retorna l'URL de pagament. El pagador l'obre i autoritza el pagament al seu banc; quan el pagament arriba a un estat final, Wealth Reader avisa la vostra notification_url amb OK o KO (vegeu el webhook notification_url). Internament es crea la mateixa intenció immutable que amb create: l'import, el beneficiari i el concepte queden fixats abans d'arribar al navegador.

La capçalera Idempotency-Key és també la vostra referència de comerç (customer_reference a l'avís): no s'envia en el cos. Si repetiu la mateixa clau amb el mateix cos, rebeu la mateixa URL; si la reutilitzeu amb altres dades (també amb un altre logo), la resposta és 409 idempotency_conflict.

Una transferència immediata no té un límit propi en aquesta API: el banc rebutja la que no pot acceptar, també per import, i aquest rebuig arriba com a KO.

header Parameters
X-API-Key
required
string

Clau d'API d'una llicència amb el producte PAYMENTS. Mantingueu-la al vostre backend.

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

De 16 a 128 caràcters; ha de començar per una lletra o un dígit i contenir només lletres, dígits i . _ : -. Un UUID v4 és vàlid. És també la referència de comerç que es retorna a l'avís.

Request Body schema: application/json
required
amount
required
string

Import en unitats principals, com a cadena JSON. "15.50" són 15,50 EUR; també s'admet un enter sense decimals ("15"). Com a màxim dos decimals, de manera que "15.5" i "15.50" són el mateix import. Mínim 0.01. El màxim està limitat al límit que cada client tingui configurat al seu banc.

Exemple: 15.50

currency
required
string
Value: "EUR"

Divisa ISO 4217. En aquesta versió, només EUR.

Exemple: EUR

required
object (payments-beneficiary)

Destinatari de la transferència. No es pot canviar un cop creat el pagament.

reference
required
string [ 1 .. 140 ] characters

Concepte de l'extracte, fins a 140 caràcters.

Exemple: Pedido 78901

priority
required
string
Enum: "normal" "instant"

normal (transferència SEPA) o instant (transferència SEPA immediata).

Exemple: normal

notification_url
required
string <= 2000 characters

URL https pública que rep l'avís d'OK o KO. Sense credencials, port 443 si s'indica i sense adreces privades, locals ni de metadades.

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

logo
string <= 2048 characters

Opcional. URL https pública del logotip del vostre comerç en SVG (el camí ha d'acabar en .svg; admet paràmetres de consulta), sense credencials, fragment ni adreces privades, fins a 2048 caràcters ASCII. La pàgina de pagament el mostra damunt del resum; Wealth Reader no el descarrega, el carrega el navegador del pagador. Qualsevol altre valor retorna 422 invalid_logo.

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

Responses

Request samples

Content type
application/json
{}

Response samples

Crea una intenció de pagament (widget)

Crea una intenció de pagament immutable i retorna un token de curta durada per obrir el widget al navegador del pagador. L'import, el beneficiari i el concepte queden fixats al backend i no es poden modificar des del navegador. Un cop tancat el widget, confirmeu el resultat des del vostre backend amb status.

Hi ha dues variants de cos:

  • Estàndard: vós fixeu amount_minor, currency, beneficiary, reference, customer_reference i allowed_origin.
  • Perfil administrat (per exemple cruz_roja_demo): Wealth Reader fixa el beneficiari, el concepte i els límits; vós envieu profile, institution_code, amount_minor, customer_reference i allowed_origin. Obteniu els bancs amb profile-institutions.

Si repetiu la mateixa Idempotency-Key amb el mateix cos, rebeu la mateixa intenció (200, idempotent_replay: true); si la reutilitzeu amb altres dades, la resposta és 409 idempotency_conflict. La clau és pròpia de la vostra empresa.

Guia: Intencions i idempotència i Integració amb el widget.

header Parameters
X-API-Key
required
string

Clau d'API d'una llicència amb el producte PAYMENTS. Mantingueu-la al vostre backend.

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

De 16 a 128 caràcters ASCII visibles. Genereu-ne una per pagament (un UUID v4 és vàlid) i reutilitzeu-la si reintenteu la crida.

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

Import en unitats menors (cèntims) com a enter JSON. 1500 són 15,00 EUR. El màxim està limitat al límit que cada client tingui configurat al seu banc.

Exemple: 1500

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

Destinatari de la transferència. No es pot canviar un cop creat el pagament.

reference
required
string [ 1 .. 140 ] characters

Concepte de l'extracte, fins a 140 caràcters.

Exemple: Pedido 78901

customer_reference
required
string <= 128 characters

La vostra referència interna del pagament. De 1 a 128 caràcters; comença per una lletra o un dígit i conté només lletres, dígits i . _ : -.

Exemple: order-78901

allowed_origin
required
string

Origen (https://host[:puerto], sense camí, consulta ni fragment) de la pàgina que obre el widget. El widget només funciona des d'aquest origen.

Exemple: https://tienda.example.com

locale
string
Value: "es"

Opcional. Idioma del widget; en aquesta versió, només es.

expected_mode
string
Enum: "mock" "live"

Opcional. Si no coincideix amb l'entorn, la crida retorna 409 payment_mode_mismatch en lloc de crear el pagament.

allowed_institution_codes
Array of strings <= 2500 items

Opcional. Llista no buida de codis de banc únics (vegeu /payments/entities/) entre els quals pot triar el pagador.

Exemple: 

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

Opcional. URL https pública del vostre logotip en SVG (camí acabat en .svg), sense credencials, fragment ni adreces privades, fins a 2048 caràcters.

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 l'estat d'un pagament

Consulta de servidor a servidor de l'estat d'un pagament, fins a obtenir una conclusió bancària. Un callback, un retorn SCA o el tancament del widget no són una confirmació financera: només ho és payment_status: settled.

Wealth Reader limita les consultes externes per intenció; apliqueu backoff també al vostre backend i no creeu una altra intenció mentre el resultat sigui ambigu.

Resultat ambigu: una caiguda de xarxa, un timeout o una resposta no reconeguda després d'emetre l'inici canvia la intenció a reconciliation_required amb payment_status: unknown, i la resposta inclou reconciliation. La iniciació mai no es repeteix automàticament. Conserveu l'identificador i la clau d'idempotència, no creeu una altra intenció ni torneu a autoritzar i, quan automatic_recovery sigui false, deixeu de sondejar i escaleu al suport amb reconciliation.reference.

En els pagaments Fast Track, aquesta consulta també envia a notification_url l'avís d'OK/KO pendent quan el pagament ha arribat a un estat final.

Guia: Estats, sondeig i conciliació.

header Parameters
X-API-Key
required
string

Clau d'API de la llicència que va crear el pagament.

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

payment.id retornat per create (en Fast Track, el payment_intent_id que retorna fast-track).

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

refresh
boolean
Default: true

Opcional. true consulta al banc l'últim estat quan escau; false retorna l'estat emmagatzemat.

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

Llista els bancs i les condicions d'un perfil administrat

Retorna les condicions d'un perfil administrat habilitat per a la vostra empresa (beneficiari, concepte, límits d'import) i els bancs que pot triar el pagador. Utilitzeu el code triat com a institution_code a create.

header Parameters
X-API-Key
required
string

Clau d'API d'una llicència amb el producte PAYMENTS.

Request Body schema: application/json
required
profile
required
string

Codi del perfil administrat.

Exemple: cruz_roja_demo

Responses

Request samples

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

Response samples

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

Llista els bancs disponibles per a pagaments

Catàleg de bancs que poden iniciar pagaments, amb el seu logotip i els mètodes de pagament que admeten. X-API-Key és opcional; si l'envieu, es valida i compta com a crida. També admet POST amb els mateixos filtres en un cos JSON, i POST /payments/?action=entities amb X-API-Key obligatòria.

Els filtres desconeguts s'ignoren i mai no produeixen un error de validació.

query Parameters
country
string
Example: country=ES

Codi de país ISO 3166-1 alfa-2. ALL o buit significa sense filtre.

Exemple: ES

search
string

Text contingut en el nom o el codi, sense distingir majúscules (àlies q).

code
string
Example: code=santander-es

Codi exacte del banc, sense distingir majúscules.

Exemple: santander-es

payment_method
string
Enum: "sepa_credit_transfer" "instant_sepa_credit_transfer"

Només els bancs que admeten aquest mètode de pagament.

limit
integer [ 1 .. 2000 ]

Mida de pàgina (d'1 a 2000).

offset
integer >= 0

Nombre de resultats que s'ometen.

header Parameters
X-API-Key
string

Opcional. Si s'envia, es valida i compta com a crida.

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.

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

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

Exemple: a1b2c3d4

enrollment_id
required
string
Example: enrollment_id=0f3a9c7b1d2e4f5a6b7c8d9e0f1a2b3c

Identifier returned by POST /cards/enrollments/.

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

Exemple: a1b2c3d4

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

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

Exemple: 2026-07-01

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

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

Exemple: 2026-07-11

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

Filters by the email of the employee.

Exemple: empleado@cliente.com

since_id
integer
Example: since_id=216

Exclusive cursor on the transaction id, for pagination.

Exemple: 216

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

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

Exemple: 500

Responses

Response samples

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