Wealth Reader (8.1.12)

Download OpenAPI specification:

API-urile reglementate bazate pe PSD2 oferă acces la anumite informații financiare precum soldurile conturilor bancare și tranzacțiile. Cu toate acestea, există alte surse de informații privind averea care nu sunt accesibile prin aceste API-uri. API-ul Wealth Reader extinde informațiile oferite de API-urile reglementate prin furnizarea accesului în timp real la surse suplimentare de avere în orice entitate din lume. Există alte două documente conexe care vă vor ajuta să integrați API-ul Wealth Reader. Unul este ghidul de integrare a widget-ului Javascript: https://docs-en.wealthreader.com/ iar celălalt este o colecție Postman bazată pe această documentație. Foarte important: Această definiție API este adaptată pentru clienții care integrează prin Widget, astfel încât unii parametri care nu sunt necesari pentru acest tip de integrare au fost omiși, cum ar fi parametrii de autentificare bancară, deoarece va fi utilizat un token.

Core

API principală necesară pentru integrările standard

Preia activele financiare și detaliile compoziției acestora

Preia activele financiare și detaliile compoziției acestora inclusiv portofoliile de investiții compuse din acțiuni sau fonduri, carduri de credit, asigurări și împrumuturi. Include informații de proprietate pentru fiecare activ precum și identificatori unici care facilitează procesarea datelor. Este posibil să se obțină date Mock. Verificați cu echipa tehnică cum să procedați.

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

Identifică clientul în serviciu

code
string

Numele entității. Lista completă este disponibilă cu GET

Exemplu: caixabank

token
string

Identifică acreditările custodiate. Fluxul prin care a fost obținut token-ul este descris în documentul 'Ghid de integrare Widget'. Următorii utilizatori Mock sunt disponibili: MOCKDATA, răspuns OK; MOCKOTP, răspuns cu provocare OTP; MOCKLOGINKO, răspuns cu eroare de login

Exemplu: MOCKDATA

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

Lista tipurilor de produse din care se vor prelua informații. Acceptă valori multiple separate prin virgule.

Exemplu: accounts,portfolios

only_balances
boolean
Default: false

Indică dacă se obțin doar soldurile produselor în loc de toate informațiile disponibile. Valoare implicită: false.

Exemplu: false

fetch_transaction_details
boolean
Default: false

Indică dacă trebuie obținute detalii extinse ale tranzacțiilor atunci când conectorul entității le acceptă. IMPORTANT: Activarea acestuia implică efectuarea uneia sau mai multor navigări suplimentare per tranzacție pentru a îmbogăți informațiile returnate. Acest lucru va crește inevitabil și semnificativ timpul de execuție. Numărul de navigări suplimentare crește odată cu volumul tranzacțiilor. Se recomandă activarea acestuia doar atunci când există certitudinea că este necesar un nivel de detaliu suplimentar față de cel returnat în mod implicit. Detaliile obținute sunt inserate în cheia additional_info la nivelul fiecărei tranzacții. Utilizarea acestui parametru necesită un mediu dedicat.

Exemplu: false

date_from
string <date>

Data de la care sunt solicitate tranzacțiile, în format AAAA-LL-ZZ. Trebuie să fie o dată anterioară zilei de azi.

Exemplu: 2024-01-01

date_to
string <date>

Aceasta se aplică doar pentru restricționarea după date viitoare pentru produsele loan și confirming, în format AAAA-LL-ZZ. Data trebuie să fie ulterioară zilei de azi

Exemplu: 2025-12-31

required_products_schema
string

Schema produselor necesare. Indică conturile sau cardurile de la care se doresc date, cu configurații suplimentare.

Exemplu:

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

Acceptă uuid-uri de tranzacții separate prin virgule. Parametru luat în considerare doar dacă product_types este ALL sau include accounts. Adaugă documentul PDF asociat fiecărei tranzacții bancare solicitate.

Exemplu:

20966426721d0885ef9d4b95535e1d3198936f16,8772d6c978d37d7af83094abf380b8b703e94105,e59296b79e7f80cec26679d2c65883025fd59295
otp_method
string

Selectează canalul de livrare al celui de-al doilea factor când API-ul a returnat codul 2017 sau 20171 (mai multe metode OTP). Reluați apelul cu același identificator de sesiune din acel răspuns și setați otp_method la șirul exact din câmpul otp_method al unui obiect din statistics.otpMethods — nu indexul tabloului. Omiteți la prima cerere cu credențiale; trimiteți după alegerea utilizatorului. Exemplul de mai jos este ilustrativ; copiați mereu șirul din statistics.otpMethods.

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

Lista tipurilor de tranzacții

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Interogare tokens asociate cu un api_key

Utilizați această metodă pentru a interoga token-urile legate de un api_key specific. Rezultatele sunt paginate: limit stabilește numărul de token-uri pe pagină (maximum 500), iar page selectează pagina returnată. api_key, method și limit sunt obligatorii; dacă oricare dintre ele lipsește sau nu este valid, API-ul răspunde cu HTTP 400 și codul de eroare 2.

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

api_key pentru identificarea clientului în serviciu

method
required
string
Value: "get"

Operația de efectuat. Singura valoare acceptată este get.

Exemplu: get

limit
required
integer [ 1 .. 500 ]

Numărul de token-uri pe pagină. Minimum 1, maximum 500.

Exemplu: 100

page
integer >= 1
Default: 1

Specificați numărul paginii pe care doriți să o recuperați. Fiecare pagină conține până la limit token-uri. Dacă nu este furnizat, valoarea implicită este 1.

Exemplu: 1

code
string

Codul entității folosit pentru filtrarea token-urilor. Dacă este omis, se returnează token-urile tuturor entităților.

Exemplu: bbva

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

Câmpul după care se sortează rezultatele: created_at (data creării) sau accesed_at (data ultimului acces). Implicit created_at.

Exemplu: created_at

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

Direcția sortării: ASC (crescător) sau DESC (descrescător). Implicit DESC.

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

Revocarea unui token

Această metodă permite revocarea unui token existent pentru a dezautoriza viitoarele cereri de acces la API.

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

Identifică clientul în serviciu

token
string

Token de revocat.

Responses

Response samples

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

Reasignarea unui token la un api_key diferit

Această metodă permite reasignarea unui token de la un api_key la altul. Ambele api_key trebuie să fie active și să aparțină aceleiași companii, iar token-ul trebuie să aparțină api_key_source.

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

api_key de la care se reasignează token-ul.

api_key_target
string

api_key la care se reasignează token-ul.

token
string

Token de reasignat.

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

Adăugare domeniu nou

Adaugă asocierea între domeniul care va găzdui widget-ul și webhook-ul de destinație. Pentru a edita sau testa domeniile dvs., utilizați https://www.wealthreader.com/clients/

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

Method to execute.

Exemplu: add

api_key
required
string

User's API key.

domain
required
string

Domain to add.

Exemplu: http://desarrollo.cliente.es

url_callback
required
string

URL for callback.

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

tokenize
required
string
Enum: "1" "0"

Controlează dacă widget-ul inițiază un flux de tokenizare:

  • 1 - Utilizatorul se autentifică la instituția financiară (login, consimțământ, 2FA dacă este necesar) și se returnează un token reutilizabil pentru interogări viitoare
  • 0 - Nu se efectuează tokenizare. Valoarea tokenului obținut anterior trebuie inclusă în cerere

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

Lista codurilor de eroare

Lista codurilor de eroare. Acordați o atenție deosebită faptului că nu toate codurile de eroare ar trebui să primească același tratament din partea aplicației dvs. Pentru o eroare de parolă incorectă, nu ar trebui să reîncercați apelul cu aceiași parametri, dar pentru o eroare care indică faptul că entitatea este în întreținere, puteți reîncerca. Solicitați o sesiune tehnică cu echipa noastră pentru a rezolva orice întrebări despre gestionarea erorilor.

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Lista codurilor de avertizare

Lista codurilor de avertizare.

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Advanced

Puncte finale opționale care nu sunt necesare pentru integrările standard. Utilizați doar dacă Wealth Reader indică în mod explicit.

Preia lista entităților acceptate

Preia lista entităților acceptate și informațiile necesare pentru a desena formularul de conectare al entității.

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

Înregistrare utilizator nou

Acest endpoint este opțional și nu este necesar pentru integrările standard. Utilizați doar dacă Wealth Reader indică în mod explicit. Acest endpoint permite înregistrarea unui utilizator fie pe platforma de transfer de portofoliu Easytransfer, fie pe instrumentul de raportare Acumulas, pe baza unui identificator unic.

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.

Exemplu: 12345678A

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

Service associated with the user. Determines the data flow.

Exemplu: easy-transfer

email
required
string <email>

User email, used according to service type.

Exemplu: sai_banker@singularbank.com

Responses

Response samples

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

Verificare stare înregistrare utilizator

Acest endpoint este opțional și nu este necesar pentru integrările standard. Utilizați doar dacă Wealth Reader indică în mod explicit. Verifică dacă un utilizator este înregistrat în sistemul Easytransfer sau Acumulas și returnează linkul de acces unic pentru utilizator.

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

Authentication key

user_id
required
string

User identification document.

Exemplu: 12345678A

Responses

Response samples

Content type
application/json
{}

Revocarea unui utilizator înregistrat anterior

Acest endpoint este opțional și nu este necesar pentru integrările standard. Utilizați doar dacă Wealth Reader indică în mod explicit. Acest endpoint permite anularea înregistrării unui utilizator din serviciul platformei Easytransfer sau 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.

Exemplu: 12345678A

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

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

Exemplu: easy-transfer

Responses

Response samples

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

Încărcare conexiuni în lot

Acest endpoint este opțional și nu este necesar pentru integrările standard. Utilizați doar dacă Wealth Reader indică în mod explicit. Important: Pentru a utiliza gestionarea proceselor batch din partea Wealthreader, este necesar un mediu dedicat. Acest endpoint nu este disponibil pe api.wealthreader.com. Endpoint-urile grupate sub eticheta "batch" permit procesarea mai multor conexiuni bancare în mod asincron, spre deosebire de metoda /entities/ care este sincronă. Ideal pentru procesarea volumelor mari de conexiuni și evitarea timeout-urilor.

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.

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

Obține statistici generale despre conexiunile batch

Acest endpoint este opțional. Recuperează statistici generale despre rezultatul procesării tuturor conexiunilor dintr-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": {
    }
}

Obține rezultatul individual al unei conexiuni specifice dintr-un batch

Acest endpoint este opțional. Recuperează rezultatul unei conexiuni specifice din 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

Verificarea titularului: verificați dacă un IBAN aparține unui titular prin Verificarea Beneficiarului (VoP) SEPA a băncii asociate licenței dumneavoastră. Ghid pas cu pas: MyBankMatch.

Verifică dacă un IBAN aparține unui titular (MyBankMatch)

Verifică dacă un IBAN aparține titularului indicat prin Verificarea Beneficiarului (VoP) SEPA a propriei dumneavoastră bănci, asociată licenței WealthReader. Returnează verdictul băncii: nu îl înlocuiește cu un calcul local de similaritate a numelor și nu creează, nu autorizează și nu execută niciun ordin de plată.

Înainte de primul apel

  1. Asigurați-vă că dispuneți de o licență activă cu produsul MY_BANK_MATCH și cotă disponibilă.
  2. Deschideți Clienți · MyBankMatch, apăsați Conectare bancă și finalizați autentificarea în fereastra găzduită de WealthReader. Conexiunea tokenizată rămâne asociată cheii dumneavoastră api_key; tokenul bancar nu este transmis browserului și nu este un parametru al interogării.

Cerere: corp codificat ca formular (application/x-www-form-urlencoded) cu api_key, iban și name, la fel ca în /entities/. Nu se trimite JSON și nu se utilizează antetul X-API-Key. Păstrați api_key în backend-ul dumneavoastră.

Răspuns: HTTP 200 indică faptul că s-a obținut un rezultat al produsului, nu că numele coincide. Verificați success și apoi payload.result:

payload.result Semnificație Câmpuri suplimentare Facturabil
MATCH Banca consideră că numele coincide cu titularul. Niciunul. Da, 0,10 EUR.
PARTIAL_MATCH Banca returnează o potrivire parțială (CLOSE_MATCH). suggested_name. Da, 0,10 EUR.
NO_MATCH Banca indică faptul că numele nu coincide. Niciunul. Da, 0,10 EUR.
NOT_CONFIGURED Licența nu are încă o bancă asociată. setup_url. Nu.
REAUTH_REQUIRED Conexiunea cu banca necesită o nouă autentificare. setup_url, reason_code. Nu.
NOT_POSSIBLE Nu a fost posibilă obținerea unui verdict utilizabil. Nu echivalează cu NO_MATCH. reason. Nu.

Numai MATCH, PARTIAL_MATCH și NO_MATCH consumă cotă. Erorile de intrare și rezultatele neconcludente nu se facturează.

Nu există cheie de idempotență și nici reîncercare gratuită. Dacă pierdeți răspunsul (timeout, rețea sau un corp care nu poate fi interpretat), rezultatul și consumul de cotă aferent pot fi necunoscute pentru aplicația dumneavoastră. Nu retrimiteți automat aceeași interogare: verificați istoricul în Clienți și contactați asistența indicând statistics.SESSION.

Ghid complet: MyBankMatch.

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

Cheie de 8 caractere hexazecimale a unei licențe active cu produsul MY_BANK_MATCH și cotă disponibilă. Păstrați-o în backend-ul dumneavoastră.

iban
required
string

IBAN dintr-o țară SEPA. Se elimină spațiile, se convertește la majuscule și se validează lungimea specifică țării și cifrele de control mod-97.

Exemplu: ES9321005707250200257112

name
required
string <= 140 characters

Numele titularului. Nevid, UTF-8 valid, fără caractere de control și de cel mult 140 de caractere. Se elimină spațiile de la capete și se comprimă spațiile interne.

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

Plăți SEPA de la cont la cont inițiate din banca plătitorului. Există două moduri de integrare:

  • Fast Track: un singur POST /payments/?action=fast-track returnează URL-ul de plată, iar Wealth Reader notifică notification_url cu OK sau KO. Consultați Plăți Fast Track.
  • Widget: backend-ul dumneavoastră creează o intenție de plată imuabilă cu POST /payments/?action=create, deschide widgetul cu tokenul returnat și confirmă rezultatul cu POST /payments/?action=status. Consultați Introducere în plăți și Stări, interogare periodică și reconciliere.

Reguli comune pentru toate apelurile /payments/?action=...

  • Metoda POST cu antetul Content-Type: application/json și un obiect JSON drept corp (maximum 32768 de octeți).
  • Autentificare numai cu antetul X-API-Key (wr_live_ urmat de 72 de litere sau cifre) al unei licențe active cu produsul PAYMENTS. Nu se trimite niciodată în corp. Fiecare apel autentificat se contabilizează în limita de apeluri a licenței.
  • Corpul este o listă albă: un câmp obligatoriu lipsă sau un câmp neprevăzut primește răspunsul 422 invalid_request.
  • Singura confirmare financiară pozitivă este payment_status: settled. Un eveniment al widgetului, o revenire SCA sau interaction_status: completed nu înseamnă niciodată că plata este decontată.

Formatul erorilor: application/json (nu problem+json) cu un error.code stabil; error.message este informativ și se poate schimba.

{"success": false, "error": {"code": "invalid_request", "message": "The request body has an invalid schema."}}
HTTP error.code Motiv
400 invalid_json Corp gol, invalid sau care nu este un obiect JSON.
401 invalid_api_key X-API-Key lipsă, formată greșit, necunoscută sau inactivă.
403 payments_not_allowed Licența nu are produsul PAYMENTS.
404 action_not_found action necunoscută.
405 method_not_allowed Altă metodă decât POST.
413 request_too_large Corp mai mare de 32768 de octeți.
415 json_required Alt Content-Type decât application/json.
422 invalid_request Câmpuri lipsă sau neprevăzute.
429 api_limit_reached S-a atins limita de apeluri a licenței.
500 internal_error Eroare neașteptată.
503 payments_disabled, payments_accept_new_disabled, payment_storage_unavailable, payment_state_unavailable Serviciu temporar indisponibil sau plăți noi suspendate.

Notificare de OK sau KO pentru o plată Fast Track Webhook

Wealth Reader trimite acest POST către notification_url al unei plăți Fast Track atunci când verifică starea plății și constată că aceasta se află într-o stare finală. reconciliation_required nu este o stare finală și nu se notifică: confirmați-o cu status.

  • outcome este ok numai dacă banca a decontat plata (settled); rejected, cancelled, expired și failed notifică ko.
  • Starea este verificată cât timp plătitorul rămâne pe pagina de plată (care o interoghează până la rezultatul final sau până la expirarea sesiunii de plată) și de fiecare dată când apelați status. Nu există o trimitere programată separată: dacă plătitorul pleacă înainte ca banca să finalizeze sau dacă serverul dumneavoastră nu răspunde cu 2xx, notificarea este trimisă la următoarea verificare. Dacă nu a sosit la câteva minute după redirecționarea plătitorului, apelați status cu payment_intent_id; acest apel declanșează și notificarea în așteptare.
  • Răspundeți cu orice 2xx pentru a o considera livrată. Wealth Reader nu urmează redirecționările și așteaptă cel mult 3 secunde.
  • Aceeași notificare poate sosi de mai multe ori: tratați customer_reference împreună cu outcome ca idempotente.
  • Cererea nu este semnată. Înainte de a livra un bun valoros, confirmați rezultatul cu status folosind X-API-Key și payment_intent_id din notificare.
header Parameters
User-Agent
required
string
Value: "WealthReader-Payments"
Request Body schema: application/json
required
outcome
required
string
Enum: "ok" "ko"

ok numai pentru settled.

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

Rezultatul financiar final.

customer_reference
required
string

Idempotency-Key pe care ați trimis-o la crearea plății.

payment_intent_id
required
string <uuid>

Identificatorul returnat de fast-track. Utilizați-l pentru a confirma rezultatul cu 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"
}

Creează o plată și obține URL-ul acesteia (Fast Track)

Un singur apel care returnează URL-ul de plată. Plătitorul îl deschide și autorizează plata în banca sa; când plata ajunge într-o stare finală, Wealth Reader notifică notification_url cu OK sau KO (consultați webhookul notification_url). În fundal se creează aceeași intenție imuabilă ca în cazul create: suma, beneficiarul și descrierea plății sunt fixate înainte de a ajunge în browser.

Antetul Idempotency-Key este și referința dumneavoastră de comerciant (customer_reference în notificare): nu se trimite în corp. Dacă repetați aceeași cheie cu același corp, primiți același URL; dacă o reutilizați cu alte date (inclusiv cu alt logo), răspunsul este 409 idempotency_conflict.

Un transfer instant nu are o limită proprie în acest API: banca respinge transferul pe care nu îl poate accepta, inclusiv din cauza sumei, iar această respingere este transmisă ca KO.

header Parameters
X-API-Key
required
string

Cheie API a unei licențe cu produsul PAYMENTS. Păstrați-o în backend-ul dumneavoastră.

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

Între 16 și 128 de caractere; trebuie să înceapă cu o literă sau o cifră și să conțină numai litere, cifre și . _ : -. Un UUID v4 este valid. Este și referința de comerciant returnată în notificare.

Request Body schema: application/json
required
amount
required
string

Suma în unități principale, ca șir JSON. "15.50" înseamnă 15,50 EUR; se acceptă și un număr întreg fără zecimale ("15"). Cel mult două zecimale, astfel încât "15.5" și "15.50" reprezintă aceeași sumă. Minimum 0.01. Maximul este limitat la limita pe care fiecare client o are configurată în banca sa.

Exemplu: 15.50

currency
required
string
Value: "EUR"

Monedă ISO 4217. În această versiune, numai EUR.

Exemplu: EUR

required
object (payments-beneficiary)

Destinatarul transferului. Nu poate fi modificat după crearea plății.

reference
required
string [ 1 .. 140 ] characters

Descrierea din extras, de cel mult 140 de caractere.

Exemplu: Pedido 78901

priority
required
string
Enum: "normal" "instant"

normal (transfer SEPA) sau instant (transfer SEPA instant).

Exemplu: normal

notification_url
required
string <= 2000 characters

URL https public care primește notificarea de OK sau KO. Fără credențiale, portul 443 dacă este indicat și fără adrese private, locale sau de metadate.

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

logo
string <= 2048 characters

Opțional. URL https public al logoului comerciantului dumneavoastră în format SVG (calea trebuie să se termine cu .svg; acceptă parametri de interogare), fără credențiale, fragment sau adrese private, de cel mult 2048 de caractere ASCII. Pagina de plată îl afișează deasupra rezumatului; Wealth Reader nu îl descarcă, ci îl încarcă browserul plătitorului. Orice altă valoare primește răspunsul 422 invalid_logo.

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

Responses

Request samples

Content type
application/json
{}

Response samples

Creează o intenție de plată (widget)

Creează o intenție de plată imuabilă și returnează un token de scurtă durată pentru a deschide widgetul în browserul plătitorului. Suma, beneficiarul și descrierea plății sunt fixate în backend și nu pot fi modificate din browser. După închiderea widgetului, confirmați rezultatul din backend-ul dumneavoastră cu status.

Există două variante de corp:

  • Standard: dumneavoastră stabiliți amount_minor, currency, beneficiary, reference, customer_reference și allowed_origin.
  • Profil administrat (de exemplu cruz_roja_demo): Wealth Reader stabilește beneficiarul, descrierea și limitele; dumneavoastră trimiteți profile, institution_code, amount_minor, customer_reference și allowed_origin. Obțineți băncile cu profile-institutions.

Dacă repetați aceeași Idempotency-Key cu același corp, primiți aceeași intenție (200, idempotent_replay: true); dacă o reutilizați cu alte date, răspunsul este 409 idempotency_conflict. Cheia este proprie firmei dumneavoastră.

Ghid: Intenții și idempotență și Integrarea cu widgetul.

header Parameters
X-API-Key
required
string

Cheie API a unei licențe cu produsul PAYMENTS. Păstrați-o în backend-ul dumneavoastră.

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

Între 16 și 128 de caractere ASCII vizibile. Generați câte una pentru fiecare plată (un UUID v4 este valid) și reutilizați-o dacă reîncercați apelul.

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

Suma în subunități (cenți) ca număr întreg JSON. 1500 înseamnă 15,00 EUR. Maximul este limitat la limita pe care fiecare client o are configurată în banca sa.

Exemplu: 1500

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

Destinatarul transferului. Nu poate fi modificat după crearea plății.

reference
required
string [ 1 .. 140 ] characters

Descrierea din extras, de cel mult 140 de caractere.

Exemplu: Pedido 78901

customer_reference
required
string <= 128 characters

Referința dumneavoastră internă a plății. Între 1 și 128 de caractere; începe cu o literă sau o cifră și conține numai litere, cifre și . _ : -.

Exemplu: order-78901

allowed_origin
required
string

Originea (https://host[:puerto], fără cale, interogare sau fragment) paginii care deschide widgetul. Widgetul funcționează numai de pe această origine.

Exemplu: https://tienda.example.com

locale
string
Value: "es"

Opțional. Limba widgetului; în această versiune, numai es.

expected_mode
string
Enum: "mock" "live"

Opțional. Dacă nu coincide cu mediul, apelul răspunde cu 409 payment_mode_mismatch în loc să creeze plata.

allowed_institution_codes
Array of strings <= 2500 items

Opțional. Listă nevidă de coduri unice de bancă (consultați /payments/entities/) dintre care poate alege plătitorul.

Exemplu:

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

Opțional. URL https public al logoului dumneavoastră în format SVG (cale terminată cu .svg), fără credențiale, fragment sau adrese private, de cel mult 2048 de caractere.

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

Interoghează starea unei plăți

Interogare de la server la server a stării unei plăți, până la obținerea unei concluzii bancare. Un callback, o revenire SCA sau închiderea widgetului nu reprezintă o confirmare financiară: numai payment_status: settled reprezintă una.

Wealth Reader limitează interogările externe pentru fiecare intenție; aplicați backoff și în backend-ul dumneavoastră și nu creați o altă intenție cât timp rezultatul este ambiguu.

Rezultat ambiguu: o întrerupere a rețelei, un timeout sau un răspuns nerecunoscut după emiterea inițierii trece intenția în reconciliation_required cu payment_status: unknown, iar răspunsul include reconciliation. Inițierea nu se repetă niciodată automat. Păstrați identificatorul și cheia de idempotență, nu creați o altă intenție și nu autorizați din nou, iar când automatic_recovery este false, opriți interogarea periodică și escaladați către asistență cu reconciliation.reference.

Pentru plățile Fast Track, această interogare trimite și către notification_url notificarea de OK/KO în așteptare atunci când plata a ajuns într-o stare finală.

Ghid: Stări, interogare periodică și reconciliere.

header Parameters
X-API-Key
required
string

Cheia API a licenței care a creat plata.

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

payment.id returnat de create (în Fast Track, payment_intent_id returnat de fast-track).

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

refresh
boolean
Default: true

Opțional. true interoghează banca pentru cea mai recentă stare, atunci când este cazul; false returnează starea stocată.

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

Listează băncile și condițiile unui profil administrat

Returnează condițiile unui profil administrat activat pentru firma dumneavoastră (beneficiar, descriere, limite de sumă) și băncile pe care le poate alege plătitorul. Utilizați code ales drept institution_code în create.

header Parameters
X-API-Key
required
string

Cheie API a unei licențe cu produsul PAYMENTS.

Request Body schema: application/json
required
profile
required
string

Codul profilului administrat.

Exemplu: cruz_roja_demo

Responses

Request samples

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

Response samples

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

Listează băncile disponibile pentru plăți

Catalogul băncilor care pot iniția plăți, cu logoul lor și metodele de plată pe care le acceptă. X-API-Key este opțional; dacă îl trimiteți, este validat și se contabilizează ca apel. Acceptă și POST cu aceleași filtre într-un corp JSON, precum și POST /payments/?action=entities cu X-API-Key obligatoriu.

Filtrele necunoscute sunt ignorate și nu produc niciodată o eroare de validare.

query Parameters
country
string
Example: country=ES

Cod de țară ISO 3166-1 alpha-2. ALL sau gol înseamnă fără filtru.

Exemplu: ES

search
string

Text conținut în nume sau în cod, fără a ține cont de majuscule (alias q).

code
string
Example: code=santander-es

Codul exact al băncii, fără a ține cont de majuscule.

Exemplu: santander-es

payment_method
string
Enum: "sepa_credit_transfer" "instant_sepa_credit_transfer"

Numai băncile care acceptă această metodă de plată.

limit
integer [ 1 .. 2000 ]

Dimensiunea paginii (între 1 și 2000).

offset
integer >= 0

Numărul de rezultate omise.

header Parameters
X-API-Key
string

Opțional. Dacă este trimis, este validat și se contabilizează ca apel.

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.

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

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

Exemplu: a1b2c3d4

enrollment_id
required
string
Example: enrollment_id=0f3a9c7b1d2e4f5a6b7c8d9e0f1a2b3c

Identifier returned by POST /cards/enrollments/.

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

Exemplu: a1b2c3d4

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

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

Exemplu: 2026-07-01

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

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

Exemplu: 2026-07-11

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

Filters by the email of the employee.

Exemplu: empleado@cliente.com

since_id
integer
Example: since_id=216

Exclusive cursor on the transaction id, for pagination.

Exemplu: 216

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

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

Exemplu: 500

Responses

Response samples

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