API docs by Redocly

Wealth Reader (8.1.12)

Download OpenAPI specification:

E-mail: info@wealthreader.com

Le API regolamentari basate su PSD2 forniscono accesso a determinate informazioni finanziarie come saldi dei conti bancari e transazioni. Tuttavia, esistono altre fonti di informazioni patrimoniali che non sono accessibili attraverso queste API. L'API Wealth Reader estende le informazioni offerte dalle API regolamentari fornendo accesso in tempo reale a fonti patrimoniali aggiuntive in qualsiasi entità mondiale. Esistono altri due documenti correlati che ti aiuteranno a integrare l'API Wealth Reader. Uno è la guida all'integrazione del widget Javascript: https://docs-en.wealthreader.com/ e l'altro è una collezione Postman basata su questa documentazione. Molto importante: Questa definizione API è adattata per i clienti che integrano tramite Widget, quindi alcuni parametri che non sono necessari per questo tipo di integrazione sono stati omessi, come i parametri di autenticazione bancaria, poiché verrà utilizzato un token.

Core

API principale richiesta per integrazioni standard

Recupera gli attivi finanziari e i dettagli della loro composizione

Recupera gli attivi finanziari e i dettagli della loro composizione inclusi portafogli di investimento composti da azioni o fondi, carte di credito, assicurazioni e prestiti. Include informazioni di proprietà per ciascun attivo nonché identificatori unici che facilitano l'elaborazione dei dati. È possibile ottenere dati Mock. Verifica con il team tecnico come farlo.

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

Identifica il cliente nel servizio

code
string

Nome dell'entità. L'elenco completo è disponibile con GET

Esempio: caixabank

token
string

Identifica le credenziali custodite. Il flusso attraverso il quale è stato ottenuto il token è descritto nel documento 'Guida all'integrazione del Widget'. Sono disponibili i seguenti utenti Mock: MOCKDATA, risposta OK; MOCKOTP, risposta con sfida OTP; MOCKLOGINKO, risposta con errore di login

Esempio: MOCKDATA

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

Elenco dei tipi di prodotto da cui recuperare le informazioni. Accetta più valori separati da virgole.

Esempio: accounts,portfolios

only_balances
boolean
Default: false

Indica se ottenere solo i saldi dei prodotti invece di tutte le informazioni disponibili. Valore predefinito: false.

Esempio: false

fetch_transaction_details
boolean
Default: false

Indica se devono essere ottenuti dettagli estesi delle transazioni quando il connettore dell'entità lo supporta. IMPORTANTE: Attivarlo implica eseguire una o più navigazioni aggiuntive per ogni transazione per arricchire le informazioni restituite. Ciò aumenterà inevitabilmente e in modo significativo il tempo di esecuzione. Il numero di navigazioni aggiuntive cresce con il volume delle transazioni. Si consiglia di attivarlo solo quando si è certi che è richiesto un livello di dettaglio superiore a quello restituito per impostazione predefinita. I dettagli ottenuti vengono inseriti nella chiave additional_info a livello di ogni transazione. L'uso di questo parametro richiede un ambiente dedicato.

Esempio: false

date_from
string <date>

Data da cui vengono richieste le transazioni, in formato AAAA-MM-GG. Deve essere una data precedente a oggi.

Esempio: 2024-01-01

date_to
string <date>

Questo si applica solo per restringere per date future per i prodotti loan e confirming, in formato AAAA-MM-GG. La data deve essere successiva a oggi

Esempio: 2025-12-31

required_products_schema
string

Schema dei prodotti richiesti. Indica i conti o le carte da cui si desiderano i dati, con configurazioni aggiuntive.

Esempio: 

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

Accetta uuid di transazioni separati da virgole. Parametro considerato solo se product_types è ALL o include accounts. Aggiunge il documento PDF associato a ciascuna delle transazioni bancarie richieste.

Esempio: 

20966426721d0885ef9d4b95535e1d3198936f16,8772d6c978d37d7af83094abf380b8b703e94105,e59296b79e7f80cec26679d2c65883025fd59295
otp_method
string

Seleziona il canale di consegna del secondo fattore quando l'API ha restituito il codice 2017 o 20171 (più metodi OTP). Richiamare con lo stesso identificatore di sessione di quella risposta e impostare otp_method sulla stringa esatta del campo otp_method di un oggetto in statistics.otpMethods — non l'indice dell'array. Omettere nella prima richiesta con credenziali; inviare dopo la scelta dell'utente. L'esempio sotto è indicativo; copiare sempre la stringa restituita in statistics.otpMethods.

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

Elenco dei tipi di transazione

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Interroga i token associati a una api_key

Usa questo metodo per interrogare i token collegati a una specifica api_key. I risultati sono paginati: limit stabilisce il numero di token per pagina (massimo 500) e page indica la pagina da restituire. api_key, method e limit sono obbligatori; se uno di essi manca o non è valido, l'API risponde con HTTP 400 e il codice di errore 2.

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

api_key per identificare il cliente nel servizio

method
required
string
Value: "get"

Operazione da eseguire. L'unico valore supportato è get.

Esempio: get

limit
required
integer [ 1 .. 500 ]

Numero di token per pagina. Minimo 1, massimo 500.

Esempio: 100

page
integer >= 1
Default: 1

Specifica il numero di pagina che vuoi recuperare. Ogni pagina contiene fino a limit token. Se non fornito, il valore predefinito è 1.

Esempio: 1

code
string

Codice dell'entità usato per filtrare i token. Se omesso, vengono restituiti i token di tutte le entità.

Esempio: bbva

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

Campo usato per ordinare i risultati: created_at (data di creazione) o accesed_at (data dell'ultimo accesso). Predefinito created_at.

Esempio: created_at

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

Direzione dell'ordinamento: ASC (crescente) o DESC (decrescente). Predefinito DESC.

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

Revocare un token

Questo metodo consente di revocare un token esistente per deautorizzare le future richieste di accesso all'API.

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

Identifica il cliente nel servizio

token
string

Token da revocare.

Responses

Response samples

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

Riassegnare un token a un api_key diverso

Questo metodo consente di riassegnare un token da un api_key a un altro. Entrambi gli api_key devono essere attivi e appartenere alla stessa azienda, e il token deve appartenere ad api_key_source.

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

api_key da cui riassegnare il token.

api_key_target
string

api_key a cui riassegnare il token.

token
string

Token da riassegnare.

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

Aggiungere un nuovo dominio

Aggiunge l'associazione tra il dominio che ospiterà il widget e il webhook di destinazione. Per modificare o testare i propri domini, usare https://www.wealthreader.com/clients/

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

Method to execute.

Esempio: add

api_key
required
string

User's API key.

domain
required
string

Domain to add.

Esempio: http://desarrollo.cliente.es

url_callback
required
string

URL for callback.

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

tokenize
required
string
Enum: "1" "0"

Controlla se il widget avvia un flusso di tokenizzazione:

  • 1 - L'utente si autentica presso l'istituto finanziario (login, consenso, 2FA se richiesto) e viene restituito un token riutilizzabile per le query future
  • 0 - Non viene eseguita alcuna tokenizzazione. Il valore del token ottenuto in precedenza deve essere incluso nella richiesta

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

Elenco dei codici di errore

Elenco dei codici di errore. Presta particolare attenzione al fatto che non tutti i codici di errore devono ricevere lo stesso trattamento dalla tua applicazione. Per un errore di password errata, non dovresti ritentare la chiamata con gli stessi parametri, ma per un errore che indica che l'entità è in manutenzione, puoi riprovare. Richiedi una sessione tecnica con il nostro team per risolvere qualsiasi domanda sulla gestione degli errori.

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Elenco dei codici di avviso

Elenco dei codici di avviso.

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Advanced

Endpoint opzionali non richiesti per integrazioni standard. Utilizzare solo se esplicitamente indicato da Wealth Reader.

Recupera l'elenco delle entità supportate

Recupera l'elenco delle entità supportate e le informazioni necessarie per disegnare il modulo di accesso dell'entità.

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

Registrare un nuovo utente

Questo endpoint è opzionale e non richiesto per le integrazioni standard. Utilizzare solo se esplicitamente indicato da Wealth Reader. Questo endpoint consente di registrare un utente sulla piattaforma di trasferimento portafoglio Easytransfer o sullo strumento di reporting Acumulas, basato su un identificatore unico.

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.

Esempio: 12345678A

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

Service associated with the user. Determines the data flow.

Esempio: easy-transfer

email
required
string <email>

User email, used according to service type.

Esempio: sai_banker@singularbank.com

Responses

Response samples

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

Verificare lo stato di registrazione dell'utente

Questo endpoint è opzionale e non richiesto per le integrazioni standard. Utilizzare solo se esplicitamente indicato da Wealth Reader. Verifica se un utente è registrato nel sistema Easytransfer o Acumulas e restituisce il link di accesso unico per l'utente.

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

Authentication key

user_id
required
string

User identification document.

Esempio: 12345678A

Responses

Response samples

Content type
application/json
{}

Revocare un utente precedentemente registrato

Questo endpoint è opzionale e non richiesto per le integrazioni standard. Utilizzare solo se esplicitamente indicato da Wealth Reader. Questo endpoint consente di annullare la registrazione di un utente dal servizio della piattaforma 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.

Esempio: 12345678A

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

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

Esempio: easy-transfer

Responses

Response samples

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

Caricamento connessioni batch

Questo endpoint è opzionale e non richiesto per le integrazioni standard. Utilizzare solo se esplicitamente indicato da Wealth Reader. Importante: Per utilizzare la gestione dei processi batch dal lato di Wealthreader, è necessario disporre di un ambiente dedicato. Questo endpoint non è disponibile su api.wealthreader.com. Gli endpoint raggruppati sotto il tag "batch" consentono di elaborare più connessioni bancarie in modo asincrono, a differenza del metodo /entities/ che è sincrono. Ideale per elaborare grandi volumi di connessioni ed evitare timeout.

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.

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

Ottenere statistiche generali sulle connessioni batch

Questo endpoint è opzionale. Recupera statistiche generali sul risultato dell'elaborazione di tutte le connessioni in 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": {
    }
}

Ottenere il risultato individuale di una connessione specifica all'interno di un batch

Questo endpoint è opzionale. Recupera il risultato di una connessione specifica dal 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

Verifica della titolarità: verifichi se un IBAN appartiene a un titolare tramite la Verifica del beneficiario (VoP) SEPA della banca collegata alla Sua licenza. Guida passo passo: MyBankMatch.

Verifica che un IBAN appartenga a un titolare (MyBankMatch)

Verifica se un IBAN appartiene al titolare indicato tramite la Verifica del beneficiario (VoP) SEPA della Sua banca, collegata alla Sua licenza WealthReader. Restituisce il verdetto della banca: non lo sostituisce con un calcolo locale di somiglianza dei nomi né crea, autorizza o esegue alcun ordine di pagamento.

Prima della prima chiamata

  1. Disponga di una licenza attiva con il prodotto MY_BANK_MATCH e quota disponibile.
  2. Apra Clienti · MyBankMatch, prema Collega banca e completi l'autenticazione nella finestra ospitata da WealthReader. La connessione tokenizzata resta associata alla Sua api_key; il token bancario non viene consegnato al browser né è un parametro della richiesta.

Richiesta: corpo codificato come modulo (application/x-www-form-urlencoded) con api_key, iban e name, come in /entities/. Non si invia JSON né si usa l'header X-API-Key. Conservi la api_key nel Suo backend.

Risposta: HTTP 200 indica che è stato ottenuto un risultato del prodotto, non che il nome corrisponda. Verifichi success e poi payload.result:

payload.result Significato Campi aggiuntivi Fatturabile
MATCH La banca ritiene che il nome corrisponda al titolare. Nessuno. Sì, 0,10 EUR.
PARTIAL_MATCH La banca restituisce una corrispondenza parziale (CLOSE_MATCH). suggested_name. Sì, 0,10 EUR.
NO_MATCH La banca indica che il nome non corrisponde. Nessuno. Sì, 0,10 EUR.
NOT_CONFIGURED La licenza non ha ancora una banca collegata. setup_url. No.
REAUTH_REQUIRED La connessione con la banca richiede una nuova autenticazione. setup_url, reason_code. No.
NOT_POSSIBLE Non è stato possibile ottenere un verdetto utilizzabile. Non equivale a NO_MATCH. reason. No.

Solo MATCH, PARTIAL_MATCH e NO_MATCH consumano quota. Gli errori di input e i risultati non conclusivi non vengono fatturati.

Non esistono chiave di idempotenza né nuovi tentativi gratuiti. Se perde la risposta (timeout, rete o un corpo non interpretabile), il risultato e il relativo consumo di quota possono essere sconosciuti alla Sua applicazione. Non reinvii automaticamente la stessa richiesta: controlli lo storico in Clienti e si rivolga all'assistenza indicando statistics.SESSION.

Guida completa: MyBankMatch.

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

Chiave di 8 caratteri esadecimali di una licenza attiva con il prodotto MY_BANK_MATCH e quota disponibile. La conservi nel Suo backend.

iban
required
string

IBAN di un paese SEPA. Gli spazi vengono rimossi, il valore viene convertito in maiuscolo e vengono convalidati la lunghezza prevista per il paese e le cifre di controllo mod-97.

Esempio: ES9321005707250200257112

name
required
string <= 140 characters

Nome del titolare. Non vuoto, UTF-8 valido, senza caratteri di controllo e fino a 140 caratteri. Viene rifilato e gli spazi interni vengono compressi.

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

Pagamenti SEPA da conto a conto avviati dalla banca del pagatore. Esistono due modalità di integrazione:

  • Fast Track: un'unica POST /payments/?action=fast-track restituisce l'URL di pagamento e Wealth Reader notifica la Sua notification_url con OK o KO. Consulti Pagamenti Fast Track.
  • Widget: il Suo backend crea un intento di pagamento immutabile con POST /payments/?action=create, apre il widget con il token restituito e conferma l'esito con POST /payments/?action=status. Consulti Introduzione ai pagamenti e Stati, polling e riconciliazione.

Regole comuni a tutte le chiamate /payments/?action=...

  • Metodo POST con l'header Content-Type: application/json e un oggetto JSON come corpo (massimo 32768 byte).
  • Autenticazione esclusivamente tramite l'header X-API-Key (wr_live_ seguito da 72 lettere o cifre) di una licenza attiva con il prodotto PAYMENTS. Non viene mai inviata nel corpo. Ogni chiamata autenticata viene conteggiata nel limite di chiamate della licenza.
  • Il corpo è una whitelist: un campo obbligatorio mancante o un campo non previsto restituisce 422 invalid_request.
  • L'unica conferma finanziaria positiva è payment_status: settled. Un evento del widget, un ritorno SCA o interaction_status: completed non significano mai che il pagamento sia stato regolato.

Formato degli errori: application/json (non problem+json) con un error.code stabile; error.message è informativo e può cambiare.

{"success": false, "error": {"code": "invalid_request", "message": "The request body has an invalid schema."}}
HTTP error.code Motivo
400 invalid_json Corpo vuoto, non valido o che non è un oggetto JSON.
401 invalid_api_key X-API-Key assente, malformata, sconosciuta o inattiva.
403 payments_not_allowed La licenza non dispone del prodotto PAYMENTS.
404 action_not_found action sconosciuta.
405 method_not_allowed Metodo diverso da POST.
413 request_too_large Corpo superiore a 32768 byte.
415 json_required Content-Type diverso da application/json.
422 invalid_request Campi mancanti o non previsti.
429 api_limit_reached È stato raggiunto il limite di chiamate della licenza.
500 internal_error Errore imprevisto.
503 payments_disabled, payments_accept_new_disabled, payment_storage_unavailable, payment_state_unavailable Servizio temporaneamente non disponibile o nuovi pagamenti sospesi.

Notifica di OK o KO di un pagamento Fast Track Webhook

Wealth Reader invia questa POST alla notification_url di un pagamento Fast Track quando verifica lo stato del pagamento e lo trova in uno stato finale. reconciliation_required non è finale e non viene notificato: lo confermi con status.

  • outcome è ok solo se la banca ha regolato il pagamento (settled); rejected, cancelled, expired e failed vengono notificati come ko.
  • Lo stato viene verificato mentre il pagatore rimane sulla pagina di pagamento (che lo interroga fino all'esito finale o fino alla scadenza della sessione di pagamento) e ogni volta che Lei chiama status. Non esiste un invio programmato separato: se il pagatore lascia la pagina prima che la banca concluda, o se il Suo server non risponde 2xx, la notifica viene inviata alla verifica successiva. Se non è arrivata qualche minuto dopo il reindirizzamento del pagatore, chiami status con il payment_intent_id; tale chiamata attiva anche la notifica in sospeso.
  • Risponda con qualsiasi 2xx perché venga considerata consegnata. Wealth Reader non segue i reindirizzamenti e attende al massimo 3 secondi.
  • La stessa notifica può arrivare più di una volta: tratti customer_reference più outcome come idempotenti.
  • La richiesta non è firmata. Prima di consegnare un bene di valore, confermi l'esito con status usando la Sua X-API-Key e il payment_intent_id della notifica.
header Parameters
User-Agent
required
string
Value: "WealthReader-Payments"
Request Body schema: application/json
required
outcome
required
string
Enum: "ok" "ko"

ok solo per settled.

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

Esito finanziario finale.

customer_reference
required
string

La Idempotency-Key che ha inviato al momento della creazione del pagamento.

payment_intent_id
required
string <uuid>

Identificatore restituito da fast-track. Lo usi per confermare l'esito 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 pagamento e ne ottiene l'URL (Fast Track)

Un'unica chiamata che restituisce l'URL di pagamento. Il pagatore la apre e autorizza il pagamento presso la propria banca; quando il pagamento raggiunge uno stato finale, Wealth Reader notifica la Sua notification_url con OK o KO (veda il webhook notification_url). Dietro le quinte viene creato lo stesso intento immutabile di create: importo, beneficiario e causale vengono fissati prima di arrivare al browser.

L'header Idempotency-Key è anche il Suo riferimento esercente (customer_reference nella notifica): non viene inviato nel corpo. Se ripete la stessa chiave con lo stesso corpo, riceve lo stesso URL; se la riutilizza con dati diversi (anche con un altro logo), la risposta è 409 idempotency_conflict.

Un bonifico istantaneo non ha un tetto proprio in questa API: la banca rifiuta quello che non può accettare, anche per importo, e tale rifiuto viene notificato come KO.

header Parameters
X-API-Key
required
string

Chiave API di una licenza con il prodotto PAYMENTS. La conservi nel Suo backend.

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

Da 16 a 128 caratteri; deve iniziare con una lettera o una cifra e contenere solo lettere, cifre e . _ : -. Un UUID v4 è valido. È anche il riferimento esercente restituito nella notifica.

Request Body schema: application/json
required
amount
required
string

Importo in unità principali, come stringa JSON. "15.50" corrisponde a 15,50 EUR; è ammesso anche un intero senza decimali ("15"). Al massimo due decimali, quindi "15.5" e "15.50" sono lo stesso importo. Minimo 0.01. Il massimo è limitato al limite che ciascun cliente ha configurato presso la propria banca.

Esempio: 15.50

currency
required
string
Value: "EUR"

Valuta ISO 4217. In questa versione, solo EUR.

Esempio: EUR

required
object (payments-beneficiary)

Destinatario del bonifico. Non può essere modificato una volta creato il pagamento.

reference
required
string [ 1 .. 140 ] characters

Causale dell'estratto conto, fino a 140 caratteri.

Esempio: Pedido 78901

priority
required
string
Enum: "normal" "instant"

normal (bonifico SEPA) o instant (bonifico SEPA istantaneo).

Esempio: normal

notification_url
required
string <= 2000 characters

URL https pubblico che riceve la notifica di OK o KO. Senza credenziali, porta 443 se indicata e senza indirizzi privati, locali o di metadati.

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

logo
string <= 2048 characters

Facoltativo. URL https pubblico del logo del Suo esercizio in formato SVG (il percorso deve terminare con .svg; sono ammessi parametri di query), senza credenziali, frammento né indirizzi privati, fino a 2048 caratteri ASCII. La pagina di pagamento lo mostra sopra il riepilogo; Wealth Reader non lo scarica, lo carica il browser del pagatore. Qualsiasi altro valore restituisce 422 invalid_logo.

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

Responses

Request samples

Content type
application/json
{}

Response samples

Crea un intento di pagamento (widget)

Crea un intento di pagamento immutabile e restituisce un token di breve durata per aprire il widget nel browser del pagatore. Importo, beneficiario e causale vengono fissati nel backend e non possono essere modificati dal browser. Dopo la chiusura del widget, confermi l'esito dal Suo backend con status.

Esistono due varianti del corpo:

  • Standard: Lei fissa amount_minor, currency, beneficiary, reference, customer_reference e allowed_origin.
  • Profilo gestito (ad esempio cruz_roja_demo): Wealth Reader fissa beneficiario, causale e limiti; Lei invia profile, institution_code, amount_minor, customer_reference e allowed_origin. Ottenga le banche con profile-institutions.

Se ripete la stessa Idempotency-Key con lo stesso corpo, riceve lo stesso intento (200, idempotent_replay: true); se la riutilizza con dati diversi, la risposta è 409 idempotency_conflict. La chiave è propria della Sua azienda.

Guida: Intenti e idempotenza e Integrazione con il widget.

header Parameters
X-API-Key
required
string

Chiave API di una licenza con il prodotto PAYMENTS. La conservi nel Suo backend.

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

Da 16 a 128 caratteri ASCII visibili. Ne generi una per pagamento (un UUID v4 è valido) e la riutilizzi se ripete la chiamata.

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

Importo in unità minori (centesimi) come intero JSON. 1500 corrisponde a 15,00 EUR. Il massimo è limitato al limite che ciascun cliente ha configurato presso la propria banca.

Esempio: 1500

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

Destinatario del bonifico. Non può essere modificato una volta creato il pagamento.

reference
required
string [ 1 .. 140 ] characters

Causale dell'estratto conto, fino a 140 caratteri.

Esempio: Pedido 78901

customer_reference
required
string <= 128 characters

Il Suo riferimento interno del pagamento. Da 1 a 128 caratteri; inizia con una lettera o una cifra e contiene solo lettere, cifre e . _ : -.

Esempio: order-78901

allowed_origin
required
string

Origine (https://host[:puerto], senza percorso, query né frammento) della pagina che apre il widget. Il widget funziona solo da tale origine.

Esempio: https://tienda.example.com

locale
string
Value: "es"

Facoltativo. Lingua del widget; in questa versione solo es.

expected_mode
string
Enum: "mock" "live"

Facoltativo. Se non corrisponde all'ambiente, la chiamata restituisce 409 payment_mode_mismatch invece di creare il pagamento.

allowed_institution_codes
Array of strings <= 2500 items

Facoltativo. Elenco non vuoto di codici bancari univoci (veda /payments/entities/) tra cui il pagatore può scegliere.

Esempio: 

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

Facoltativo. URL https pubblico del Suo logo in formato SVG (percorso che termina con .svg), senza credenziali, frammento né indirizzi privati, fino a 2048 caratteri.

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 lo stato di un pagamento

Consultazione da server a server dello stato di un pagamento, fino a ottenere un esito bancario. Un callback, un ritorno SCA o la chiusura del widget non sono una conferma finanziaria: lo è solo payment_status: settled.

Wealth Reader limita le consultazioni esterne per intento; applichi un backoff anche nel Suo backend e non crei un altro intento finché l'esito è ambiguo.

Esito ambiguo: un'interruzione di rete, un timeout o una risposta non riconosciuta dopo l'invio dell'avvio portano l'intento a reconciliation_required con payment_status: unknown, e la risposta include reconciliation. L'avvio non viene mai ripetuto automaticamente. Conservi l'identificatore e la chiave di idempotenza, non crei un altro intento né autorizzi di nuovo e, quando automatic_recovery è false, interrompa il polling e si rivolga all'assistenza con reconciliation.reference.

Nei pagamenti Fast Track, questa consultazione invia anche a notification_url la notifica di OK/KO in sospeso quando il pagamento ha raggiunto uno stato finale.

Guida: Stati, polling e riconciliazione.

header Parameters
X-API-Key
required
string

Chiave API della licenza che ha creato il pagamento.

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

payment.id restituito da create (in Fast Track, il payment_intent_id restituito da fast-track).

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

refresh
boolean
Default: true

Facoltativo. true richiede alla banca lo stato più recente quando opportuno; false restituisce lo stato memorizzato.

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

Elenca le banche e le condizioni di un profilo gestito

Restituisce le condizioni di un profilo gestito abilitato per la Sua azienda (beneficiario, causale, limiti di importo) e le banche che il pagatore può scegliere. Usi il code scelto come institution_code in create.

header Parameters
X-API-Key
required
string

Chiave API di una licenza con il prodotto PAYMENTS.

Request Body schema: application/json
required
profile
required
string

Codice del profilo gestito.

Esempio: cruz_roja_demo

Responses

Request samples

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

Response samples

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

Elenca le banche disponibili per i pagamenti

Catalogo delle banche che possono avviare pagamenti, con il relativo logo e i metodi di pagamento supportati. X-API-Key è facoltativa; se la invia, viene convalidata e conteggiata come chiamata. È ammesso anche POST con gli stessi filtri in un corpo JSON, e POST /payments/?action=entities con X-API-Key obbligatoria.

I filtri sconosciuti vengono ignorati e non producono mai un errore di convalida.

query Parameters
country
string
Example: country=ES

Codice paese ISO 3166-1 alpha-2. ALL o vuoto significa nessun filtro.

Esempio: ES

search
string

Testo contenuto nel nome o nel codice, senza distinzione tra maiuscole e minuscole (alias q).

code
string
Example: code=santander-es

Codice esatto della banca, senza distinzione tra maiuscole e minuscole.

Esempio: santander-es

payment_method
string
Enum: "sepa_credit_transfer" "instant_sepa_credit_transfer"

Solo le banche che supportano questo metodo di pagamento.

limit
integer [ 1 .. 2000 ]

Dimensione della pagina (da 1 a 2000).

offset
integer >= 0

Numero di risultati da saltare.

header Parameters
X-API-Key
string

Facoltativo. Se viene inviata, viene convalidata e conteggiata come chiamata.

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.

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

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

Esempio: a1b2c3d4

enrollment_id
required
string
Example: enrollment_id=0f3a9c7b1d2e4f5a6b7c8d9e0f1a2b3c

Identifier returned by POST /cards/enrollments/.

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

Esempio: a1b2c3d4

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

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

Esempio: 2026-07-01

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

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

Esempio: 2026-07-11

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

Filters by the email of the employee.

Esempio: empleado@cliente.com

since_id
integer
Example: since_id=216

Exclusive cursor on the transaction id, for pagination.

Esempio: 216

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

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

Esempio: 500

Responses

Response samples

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