Wealth Reader (8.1.12)

Download OpenAPI specification:

Op PSD2 gebaseerde regulatorische APIs bieden toegang tot bepaalde financiële informatie zoals banksaldos en transacties. Er zijn echter andere bronnen van vermogensinformatie die niet toegankelijk zijn via deze APIs. De Wealth Reader API breidt de door regulatorische APIs aangeboden informatie uit door realtime toegang te bieden tot extra vermogensbronnen in elke entiteit wereldwijd. Er zijn twee andere gerelateerde documenten die u zullen helpen bij het integreren van de Wealth Reader API. Eén is de Javascript widget integratiegids: https://docs-en.wealthreader.com/ en de ander is een Postman collectie gebaseerd op deze documentatie. Zeer belangrijk: Deze API-definitie is aangepast voor klanten die via Widget integreren, dus sommige parameters die niet nodig zijn voor dit type integratie zijn weggelaten, zoals bankauthenticatieparameters, aangezien een token zal worden gebruikt.

Core

Kern-API vereist voor standaard integraties

Haalt financiële activa en details van hun samenstelling op

Haalt financiële activa en details van hun samenstelling op, inclusief beleggingsportefeuilles samengesteld uit aandelen of fondsen, creditcards, verzekeringen en leningen. Bevat eigendomsinformatie voor elk actief en unieke identificatoren die gegevensverwerking vergemakkelijken. Het is mogelijk om Mock-gegevens te verkrijgen. Controleer bij het technische team hoe dit te doen.

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

Identificeert de klant in de dienst

code
string

Naam van de entiteit. De volledige lijst is beschikbaar met GET

Voorbeeld: caixabank

token
string

Identificeert de bewaarde inloggegevens. De flow waarmee het token is verkregen staat beschreven in het document 'Widget Integratiegids'. De volgende Mock-gebruikers zijn beschikbaar: MOCKDATA, OK-antwoord; MOCKOTP, antwoord met OTP-uitdaging; MOCKLOGINKO, antwoord met login-fout

Voorbeeld: MOCKDATA

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

Lijst van producttypen waarvan informatie moet worden opgehaald. Accepteert meerdere waarden gescheiden door komma's.

Voorbeeld: accounts,portfolios

only_balances
boolean
Default: false

Geeft aan of alleen de saldi van de producten moeten worden opgehaald in plaats van alle beschikbare informatie. Standaardwaarde: false.

Voorbeeld: false

fetch_transaction_details
boolean
Default: false

Geeft aan of uitgebreide transactiegegevens moeten worden opgehaald wanneer de connector van de entiteit dit ondersteunt. BELANGRIJK: Het inschakelen ervan houdt in dat er een of meer extra navigaties per transactie worden uitgevoerd om de geretourneerde informatie te verrijken. Dit zal de uitvoeringstijd onvermijdelijk en aanzienlijk verhogen. Het aantal extra navigaties groeit met het volume aan transacties. Het wordt aanbevolen dit alleen in te schakelen wanneer u zeker weet dat een hoger detailniveau dan standaard wordt geretourneerd vereist is. De opgehaalde gegevens worden ingevoegd in de sleutel additional_info op het niveau van elke transactie. Het gebruik van deze parameter vereist een toegewijde omgeving.

Voorbeeld: false

date_from
string <date>

Datum vanaf wanneer transacties worden opgevraagd, in JJJJ-MM-DD formaat. Moet een datum voor vandaag zijn.

Voorbeeld: 2024-01-01

date_to
string <date>

Dit geldt alleen voor beperking op toekomstige datums voor producten loan en confirming, in JJJJ-MM-DD formaat. De datum moet later zijn dan vandaag

Voorbeeld: 2025-12-31

required_products_schema
string

Schema van vereiste producten. Geeft de rekeningen of kaarten aan waarvan gegevens gewenst zijn, met aanvullende configuraties.

Voorbeeld:

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

Accepteert transactie-uuid's gescheiden door komma's. Parameter die alleen in aanmerking wordt genomen als product_types ALL is of accounts bevat. Voegt het PDF-document toe dat bij elk van de gevraagde banktransacties hoort.

Voorbeeld:

20966426721d0885ef9d4b95535e1d3198936f16,8772d6c978d37d7af83094abf380b8b703e94105,e59296b79e7f80cec26679d2c65883025fd59295
otp_method
string

Selecteert welk tweefactorleveringskanaal te gebruiken wanneer de API foutcode 2017 of 20171 retourneerde (meerdere OTP-methoden). Roep opnieuw aan met dezelfde sessie-ID als die reactie en zet otp_method op de exacte string in het otp_method-veld van een object in statistics.otpMethods — niet de array-index. Weglaten bij eerste credential-verzoek; meesturen na keuze van de gebruiker. Het voorbeeld hieronder is ter illustratie; kopieer altijd de string uit statistics.otpMethods voor uw entiteit.

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

Lijst van transactietypes

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Tokens opvragen die gekoppeld zijn aan een api_key

Gebruik deze methode om de tokens op te vragen die gekoppeld zijn aan een specifieke api_key. De resultaten zijn gepagineerd: limit bepaalt het aantal tokens per pagina (maximaal 500) en page kiest de pagina die wordt geretourneerd. api_key, method en limit zijn verplicht; als een ervan ontbreekt of ongeldig is, antwoordt de API met HTTP 400 en foutcode 2.

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

api_key om de klant in de dienst te identificeren

method
required
string
Value: "get"

Uit te voeren bewerking. De enige ondersteunde waarde is get.

Voorbeeld: get

limit
required
integer [ 1 .. 500 ]

Aantal tokens per pagina. Minimaal 1, maximaal 500.

Voorbeeld: 100

page
integer >= 1
Default: 1

Specificeer het paginanummer dat u wilt ophalen. Elke pagina bevat maximaal limit tokens. Indien niet opgegeven, is de standaardwaarde 1.

Voorbeeld: 1

code
string

Entiteitscode om de tokens op te filteren. Indien weggelaten, worden de tokens van alle entiteiten geretourneerd.

Voorbeeld: bbva

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

Veld waarop de resultaten worden gesorteerd: created_at (aanmaakdatum) of accesed_at (laatste toegangsdatum). Standaard created_at.

Voorbeeld: created_at

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

Sorteervolgorde: ASC (oplopend) of DESC (aflopend). Standaard DESC.

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

Een token intrekken

Met deze methode kunt u een bestaand token intrekken om toekomstige API-toegangsverzoeken te deautoriseren.

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

Identificeert de klant in de dienst

token
string

Token dat moet worden ingetrokken.

Responses

Response samples

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

Een token toewijzen aan een andere api_key

Met deze methode kunt u een token van de ene api_key naar een andere toewijzen. Beide api_keys moeten actief zijn en bij hetzelfde bedrijf horen, en het token moet bij api_key_source horen.

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

api_key waarvan het token opnieuw moet worden toegewezen.

api_key_target
string

api_key waaraan het token opnieuw moet worden toegewezen.

token
string

Token dat opnieuw moet worden toegewezen.

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

Een nieuw domein toevoegen

Voegt de associatie toe tussen het domein dat de widget zal hosten en de bestemmings-webhook. Om uw domeinen te bewerken of te testen, gebruikt u https://www.wealthreader.com/clients/

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

Method to execute.

Voorbeeld: add

api_key
required
string

User's API key.

domain
required
string

Domain to add.

Voorbeeld: http://desarrollo.cliente.es

url_callback
required
string

URL for callback.

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

tokenize
required
string
Enum: "1" "0"

Bepaalt of de widget een tokenisatiestroom start:

  • 1 - De gebruiker authenticeert zich bij de financiële instelling (login, toestemming, 2FA indien vereist) en een herbruikbaar token wordt teruggegeven
  • 0 - Er wordt geen tokenisatie uitgevoerd. De eerder verkregen tokenwaarde moet in het verzoek worden opgenomen

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

Lijst van foutcodes

Lijst van foutcodes. Let er speciaal op dat niet alle foutcodes dezelfde behandeling van uw applicatie moeten krijgen. Bij een onjuist wachtwoordfout moet u de oproep niet opnieuw proberen met dezelfde parameters, maar bij een fout die aangeeft dat de entiteit in onderhoud is, kunt u het opnieuw proberen. Vraag een technische sessie aan met ons team om vragen over foutbeheer op te lossen.

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Lijst van waarschuwingscodes

Lijst van waarschuwingscodes.

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Advanced

Optionele eindpunten niet vereist voor standaard integraties. Gebruik alleen als expliciet geïnstrueerd door Wealth Reader.

Haalt de lijst van ondersteunde entiteiten op

Haalt de lijst van ondersteunde entiteiten op en de informatie die nodig is om het inlogformulier van de entiteit te tekenen.

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

Nieuwe gebruiker registreren

Dit endpoint is optioneel en niet vereist voor standaard integraties. Gebruik alleen als expliciet geïnstrueerd door Wealth Reader. Dit endpoint maakt het mogelijk een gebruiker te registreren op het portfolio-overdrachtsplatform Easytransfer of op de rapportagetool Acumulas, gebaseerd op een unieke identificatie.

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.

Voorbeeld: 12345678A

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

Service associated with the user. Determines the data flow.

Voorbeeld: easy-transfer

email
required
string <email>

User email, used according to service type.

Voorbeeld: sai_banker@singularbank.com

Responses

Response samples

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

Gebruikersregistratiestatus controleren

Dit endpoint is optioneel en niet vereist voor standaard integraties. Gebruik alleen als expliciet geïnstrueerd door Wealth Reader. Controleert of een gebruiker is geregistreerd in het Easytransfer- of Acumulas-systeem en retourneert de unieke toegangslink voor de gebruiker.

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

Authentication key

user_id
required
string

User identification document.

Voorbeeld: 12345678A

Responses

Response samples

Content type
application/json
{}

Een eerder geregistreerde gebruiker intrekken

Dit endpoint is optioneel en niet vereist voor standaard integraties. Gebruik alleen als expliciet geïnstrueerd door Wealth Reader. Dit endpoint maakt het mogelijk een gebruiker uit te schrijven van de Easytransfer- of Acumulas-platformservice.

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.

Voorbeeld: 12345678A

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

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

Voorbeeld: easy-transfer

Responses

Response samples

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

Batch-verbindingen laden

Dit endpoint is optioneel en niet vereist voor standaard integraties. Gebruik alleen als expliciet geïnstrueerd door Wealth Reader. Belangrijk: Om batchprocesbeheer aan de Wealthreader-kant te gebruiken, is een dedicated omgeving vereist. Dit endpoint is niet beschikbaar op api.wealthreader.com. De endpoints gegroepeerd onder de "batch" tag maken het mogelijk meerdere bankverbindingen asynchroon te verwerken, in tegenstelling tot de synchrone /entities/ methode. Ideaal voor grote volumes verbindingen en het vermijden van 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.

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

Algemene statistieken over batch-verbindingen ophalen

Dit endpoint is optioneel. Haalt algemene statistieken op over het verwerkingsresultaat van alle verbindingen in een 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": {
    }
}

Individueel resultaat van een specifieke verbinding binnen een batch ophalen

Dit endpoint is optioneel. Haalt het resultaat van een specifieke verbinding uit de batch op.

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

Verificatie van rekeninghouderschap: controleer of een IBAN toebehoort aan een rekeninghouder via de SEPA-Verificatie van de Begunstigde (VoP) van de bank die aan uw licentie is gekoppeld. Stapsgewijze handleiding: MyBankMatch.

Controleert of een IBAN toebehoort aan een rekeninghouder (MyBankMatch)

Controleert of een IBAN toebehoort aan de opgegeven rekeninghouder via de SEPA-Verificatie van de Begunstigde (VoP) van uw eigen bank, gekoppeld aan uw WealthReader-licentie. Retourneert het oordeel van de bank: dit wordt niet vervangen door een lokale berekening van naamsovereenkomst, en er wordt geen betaalopdracht aangemaakt, geautoriseerd of uitgevoerd.

Vóór de eerste aanroep

  1. Beschik over een actieve licentie met het product MY_BANK_MATCH en beschikbaar quotum.
  2. Open Klanten · MyBankMatch, klik op Bank koppelen en voltooi de authenticatie in het gehoste venster van WealthReader. De getokeniseerde koppeling wordt aan uw api_key gekoppeld; het banktoken wordt niet aan de browser doorgegeven en is geen parameter van de aanvraag.

Aanvraag: body gecodeerd als formulier (application/x-www-form-urlencoded) met api_key, iban en name, net als bij /entities/. Er wordt geen JSON verzonden en de header X-API-Key wordt niet gebruikt. Bewaar de api_key in uw backend.

Antwoord: HTTP 200 geeft aan dat er een resultaat van het product is verkregen, niet dat de naam overeenkomt. Controleer success en vervolgens payload.result:

payload.result Betekenis Aanvullende velden Factureerbaar
MATCH De bank beschouwt de naam als overeenkomend met de rekeninghouder. Geen. Ja, 0,10 EUR.
PARTIAL_MATCH De bank retourneert een gedeeltelijke overeenkomst (CLOSE_MATCH). suggested_name. Ja, 0,10 EUR.
NO_MATCH De bank geeft aan dat de naam niet overeenkomt. Geen. Ja, 0,10 EUR.
NOT_CONFIGURED Aan de licentie is nog geen bank gekoppeld. setup_url. Nee.
REAUTH_REQUIRED De koppeling met de bank vereist een nieuwe authenticatie. setup_url, reason_code. Nee.
NOT_POSSIBLE Er kon geen bruikbaar oordeel worden verkregen. Dit staat niet gelijk aan NO_MATCH. reason. Nee.

Alleen MATCH, PARTIAL_MATCH en NO_MATCH verbruiken quotum. Invoerfouten en niet-conclusieve resultaten worden niet gefactureerd.

Er is geen idempotentiesleutel en geen gratis nieuwe poging. Als u het antwoord verliest (time-out, netwerk of een niet-interpreteerbare body), kunnen het resultaat en het bijbehorende quotumverbruik onbekend zijn voor uw applicatie. Verzend dezelfde aanvraag niet automatisch opnieuw: bekijk de geschiedenis in Klanten en neem contact op met support onder vermelding van statistics.SESSION.

Volledige handleiding: MyBankMatch.

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

Sleutel van 8 hexadecimale tekens van een actieve licentie met het product MY_BANK_MATCH en beschikbaar quotum. Bewaar deze in uw backend.

iban
required
string

IBAN van een SEPA-land. Spaties worden verwijderd, de waarde wordt omgezet naar hoofdletters en de lengte voor het land en de controlecijfers mod-97 worden gevalideerd.

Voorbeeld: ES9321005707250200257112

name
required
string <= 140 characters

Naam van de rekeninghouder. Niet leeg, geldige UTF-8, zonder controletekens en maximaal 140 tekens. Wordt bijgesneden en interne spaties worden samengevoegd.

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

SEPA-betalingen van rekening naar rekening, geïnitieerd vanuit de bank van de betaler. Er zijn twee manieren om ze te integreren:

  • Fast Track: één enkele POST /payments/?action=fast-track retourneert de betalings-URL en Wealth Reader informeert uw notification_url met OK of KO. Zie Fast Track-betalingen.
  • Widget: uw backend maakt met POST /payments/?action=create een onveranderlijke betalingsintentie aan, opent de widget met het geretourneerde token en bevestigt het resultaat met POST /payments/?action=status. Zie Inleiding tot betalingen en Statussen, polling en reconciliatie.

Gemeenschappelijke regels voor alle aanroepen van /payments/?action=...

  • Methode POST met de header Content-Type: application/json en een JSON-object als body (maximaal 32768 bytes).
  • Authenticatie uitsluitend met de header X-API-Key (wr_live_ gevolgd door 72 letters of cijfers) van een actieve licentie met het product PAYMENTS. Deze wordt nooit in de body verzonden. Elke geauthenticeerde aanroep telt mee voor de aanroeplimiet van de licentie.
  • De body is een whitelist: een ontbrekend verplicht veld of een onverwacht veld geeft 422 invalid_request.
  • De enige positieve financiële bevestiging is payment_status: settled. Een widgetgebeurtenis, een SCA-terugkeer of interaction_status: completed betekent nooit dat de betaling is afgewikkeld.

Foutformaat: application/json (geen problem+json) met een stabiele error.code; error.message is informatief en kan wijzigen.

{"success": false, "error": {"code": "invalid_request", "message": "The request body has an invalid schema."}}
HTTP error.code Reden
400 invalid_json Lege of ongeldige body, of geen JSON-object.
401 invalid_api_key X-API-Key ontbreekt, is onjuist opgemaakt, onbekend of inactief.
403 payments_not_allowed De licentie heeft het product PAYMENTS niet.
404 action_not_found Onbekende action.
405 method_not_allowed Andere methode dan POST.
413 request_too_large Body groter dan 32768 bytes.
415 json_required Andere Content-Type dan application/json.
422 invalid_request Ontbrekende of onverwachte velden.
429 api_limit_reached De aanroeplimiet van de licentie is bereikt.
500 internal_error Onverwachte fout.
503 payments_disabled, payments_accept_new_disabled, payment_storage_unavailable, payment_state_unavailable Dienst tijdelijk niet beschikbaar of nieuwe betalingen gepauzeerd.

OK- of KO-melding van een Fast Track-betaling Webhook

Wealth Reader verzendt deze POST naar de notification_url van een Fast Track-betaling wanneer het de status van de betaling controleert en vaststelt dat deze een eindstatus heeft. reconciliation_required is geen eindstatus en wordt niet gemeld: bevestig deze met status.

  • outcome is alleen ok als de bank de betaling heeft afgewikkeld (settled); rejected, cancelled, expired en failed worden gemeld als ko.
  • De status wordt gecontroleerd zolang de betaler op de betaalpagina blijft (die de status opvraagt tot het eindresultaat of totdat de betaalsessie verloopt) en telkens wanneer u status aanroept. Er is geen afzonderlijke geplande verzending: als de betaler vertrekt voordat de bank tot een conclusie komt, of uw server niet met 2xx antwoordt, wordt de melding bij de volgende controle verzonden. Als deze enkele minuten na het doorsturen van de betaler nog niet is binnengekomen, roep dan status aan met de payment_intent_id; die aanroep activeert ook de openstaande melding.
  • Antwoord met een willekeurige 2xx om de melding als afgeleverd te beschouwen. Wealth Reader volgt geen omleidingen en wacht maximaal 3 seconden.
  • Dezelfde melding kan meer dan eens binnenkomen: behandel customer_reference plus outcome als idempotent.
  • De aanvraag is niet ondertekend. Bevestig het resultaat met status met uw X-API-Key en de payment_intent_id uit de melding voordat u een waardevol goed levert.
header Parameters
User-Agent
required
string
Value: "WealthReader-Payments"
Request Body schema: application/json
required
outcome
required
string
Enum: "ok" "ko"

ok alleen voor settled.

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

Definitief financieel resultaat.

customer_reference
required
string

De Idempotency-Key die u bij het aanmaken van de betaling hebt verzonden.

payment_intent_id
required
string <uuid>

Identificatie die fast-track heeft geretourneerd. Gebruik deze om het resultaat te bevestigen met 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"
}

Maakt een betaling aan en verkrijgt de URL ervan (Fast Track)

Eén enkele aanroep die de betalings-URL retourneert. De betaler opent deze en autoriseert de betaling bij zijn bank; wanneer de betaling een eindstatus bereikt, informeert Wealth Reader uw notification_url met OK of KO (zie de webhook notification_url). Op de achtergrond wordt dezelfde onveranderlijke intentie aangemaakt als met create: bedrag, begunstigde en omschrijving liggen vast voordat ze de browser bereiken.

De header Idempotency-Key is tevens uw handelaarsreferentie (customer_reference in de melding): deze wordt niet in de body verzonden. Als u dezelfde sleutel herhaalt met dezelfde body, ontvangt u dezelfde URL; als u deze hergebruikt met andere gegevens (ook met een ander logo), is het antwoord 409 idempotency_conflict.

Voor een instantoverboeking geldt in deze API geen eigen limiet: de bank weigert een overboeking die zij niet kan accepteren, ook op basis van het bedrag, en die weigering komt binnen als KO.

header Parameters
X-API-Key
required
string

API-sleutel van een licentie met het product PAYMENTS. Bewaar deze in uw backend.

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

Van 16 tot 128 tekens; moet beginnen met een letter of cijfer en mag alleen letters, cijfers en . _ : - bevatten. Een UUID v4 is geldig. Dit is tevens de handelaarsreferentie die in de melding wordt geretourneerd.

Request Body schema: application/json
required
amount
required
string

Bedrag in hoofdeenheden, als JSON-string. "15.50" is 15,50 EUR; een geheel getal zonder decimalen ("15") wordt ook geaccepteerd. Maximaal twee decimalen, dus "15.5" en "15.50" zijn hetzelfde bedrag. Minimum 0.01. Het maximum wordt begrensd door de limiet die elke klant bij zijn bank heeft ingesteld.

Voorbeeld: 15.50

currency
required
string
Value: "EUR"

ISO 4217-valuta. In deze versie alleen EUR.

Voorbeeld: EUR

required
object (payments-beneficiary)

Ontvanger van de overboeking. Kan niet worden gewijzigd nadat de betaling is aangemaakt.

reference
required
string [ 1 .. 140 ] characters

Omschrijving op het rekeningafschrift, maximaal 140 tekens.

Voorbeeld: Pedido 78901

priority
required
string
Enum: "normal" "instant"

normal (SEPA-overboeking) of instant (SEPA-instantoverboeking).

Voorbeeld: normal

notification_url
required
string <= 2000 characters

Openbare https-URL die de OK- of KO-melding ontvangt. Zonder inloggegevens, poort 443 indien opgegeven en zonder privé-, lokale of metadata-adressen.

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

logo
string <= 2048 characters

Optioneel. Openbare https-URL van het logo van uw onderneming in SVG (het pad moet eindigen op .svg; queryparameters zijn toegestaan), zonder inloggegevens, fragment of privéadressen, maximaal 2048 ASCII-tekens. De betaalpagina toont het boven het overzicht; Wealth Reader downloadt het niet, de browser van de betaler laadt het. Elke andere waarde geeft 422 invalid_logo.

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

Responses

Request samples

Content type
application/json
{}

Response samples

Maakt een betalingsintentie aan (widget)

Maakt een onveranderlijke betalingsintentie aan en retourneert een kortlevend token om de widget in de browser van de betaler te openen. Bedrag, begunstigde en omschrijving worden in de backend vastgelegd en kunnen niet vanuit de browser worden gewijzigd. Bevestig na het sluiten van de widget het resultaat vanuit uw backend met status.

Er zijn twee varianten van de body:

  • Standaard: u legt amount_minor, currency, beneficiary, reference, customer_reference en allowed_origin vast.
  • Beheerd profiel (bijvoorbeeld cruz_roja_demo): Wealth Reader legt begunstigde, omschrijving en limieten vast; u verzendt profile, institution_code, amount_minor, customer_reference en allowed_origin. Haal de banken op met profile-institutions.

Als u dezelfde Idempotency-Key herhaalt met dezelfde body, ontvangt u dezelfde intentie (200, idempotent_replay: true); als u deze hergebruikt met andere gegevens, is het antwoord 409 idempotency_conflict. De sleutel is specifiek voor uw onderneming.

Handleiding: Intenties en idempotentie en Integratie met de widget.

header Parameters
X-API-Key
required
string

API-sleutel van een licentie met het product PAYMENTS. Bewaar deze in uw backend.

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

Van 16 tot 128 zichtbare ASCII-tekens. Genereer er één per betaling (een UUID v4 is geldig) en hergebruik deze als u de aanroep opnieuw probeert.

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

Bedrag in kleinere eenheden (centen) als JSON-geheel getal. 1500 is 15,00 EUR. Het maximum wordt begrensd door de limiet die elke klant bij zijn bank heeft ingesteld.

Voorbeeld: 1500

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

Ontvanger van de overboeking. Kan niet worden gewijzigd nadat de betaling is aangemaakt.

reference
required
string [ 1 .. 140 ] characters

Omschrijving op het rekeningafschrift, maximaal 140 tekens.

Voorbeeld: Pedido 78901

customer_reference
required
string <= 128 characters

Uw interne referentie voor de betaling. Van 1 tot 128 tekens; begint met een letter of cijfer en bevat alleen letters, cijfers en . _ : -.

Voorbeeld: order-78901

allowed_origin
required
string

Origin (https://host[:puerto], zonder pad, query of fragment) van de pagina die de widget opent. De widget werkt alleen vanaf die origin.

Voorbeeld: https://tienda.example.com

locale
string
Value: "es"

Optioneel. Taal van de widget; in deze versie alleen es.

expected_mode
string
Enum: "mock" "live"

Optioneel. Als deze niet overeenkomt met de omgeving, geeft de aanroep 409 payment_mode_mismatch in plaats van de betaling aan te maken.

allowed_institution_codes
Array of strings <= 2500 items

Optioneel. Niet-lege lijst van unieke bankcodes (zie /payments/entities/) waaruit de betaler kan kiezen.

Voorbeeld:

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

Optioneel. Openbare https-URL van uw logo in SVG (pad eindigend op .svg), zonder inloggegevens, fragment of privéadressen, maximaal 2048 tekens.

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

Vraagt de status van een betaling op

Server-naar-server-opvraging van de status van een betaling, totdat er een bancaire conclusie is. Een callback, een SCA-terugkeer of het sluiten van de widget is geen financiële bevestiging: alleen payment_status: settled is dat.

Wealth Reader beperkt de externe opvragingen per intentie; pas ook in uw backend backoff toe en maak geen nieuwe intentie aan zolang het resultaat dubbelzinnig is.

Dubbelzinnig resultaat: een netwerkstoring, time-out of onherkenbaar antwoord na het verzenden van de initiatie zet de intentie op reconciliation_required met payment_status: unknown, en het antwoord bevat reconciliation. De initiatie wordt nooit automatisch herhaald. Bewaar de identificatie en de idempotentiesleutel, maak geen nieuwe intentie aan en autoriseer niet opnieuw, en stop met pollen wanneer automatic_recovery false is en escaleer naar support met reconciliation.reference.

Bij Fast Track-betalingen verzendt deze opvraging ook de openstaande OK/KO-melding naar notification_url wanneer de betaling een eindstatus heeft bereikt.

Handleiding: Statussen, polling en reconciliatie.

header Parameters
X-API-Key
required
string

API-sleutel van de licentie die de betaling heeft aangemaakt.

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

payment.id geretourneerd door create (bij Fast Track de payment_intent_id die fast-track retourneert).

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

refresh
boolean
Default: true

Optioneel. true vraagt indien van toepassing de laatste status op bij de bank; false retourneert de opgeslagen status.

Responses

Request samples

Content type
application/json
{
  • "payment_intent_id": "3f2b8c1e-5d4a-4b6f-9e21-7c0d4a1b2e3f",
  • "refresh": true
}

Response samples

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

Toont de banken en voorwaarden van een beheerd profiel

Retourneert de voorwaarden van een voor uw onderneming ingeschakeld beheerd profiel (begunstigde, omschrijving, bedraglimieten) en de banken waaruit de betaler kan kiezen. Gebruik de gekozen code als institution_code in create.

header Parameters
X-API-Key
required
string

API-sleutel van een licentie met het product PAYMENTS.

Request Body schema: application/json
required
profile
required
string

Code van het beheerde profiel.

Voorbeeld: cruz_roja_demo

Responses

Request samples

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

Response samples

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

Toont de banken die beschikbaar zijn voor betalingen

Catalogus van banken die betalingen kunnen initiëren, met hun logo en de betaalmethoden die ze ondersteunen. X-API-Key is optioneel; als u deze meestuurt, wordt deze gevalideerd en telt deze als aanroep. Ondersteunt ook POST met dezelfde filters in een JSON-body, en POST /payments/?action=entities met verplichte X-API-Key.

Onbekende filters worden genegeerd en leiden nooit tot een validatiefout.

query Parameters
country
string
Example: country=ES

ISO 3166-1 alpha-2-landcode. ALL of leeg betekent geen filter.

Voorbeeld: ES

search
string

Tekst die voorkomt in de naam of de code, niet hoofdlettergevoelig (alias q).

code
string
Example: code=santander-es

Exacte code van de bank, niet hoofdlettergevoelig.

Voorbeeld: santander-es

payment_method
string
Enum: "sepa_credit_transfer" "instant_sepa_credit_transfer"

Alleen de banken die deze betaalmethode ondersteunen.

limit
integer [ 1 .. 2000 ]

Paginagrootte (van 1 tot 2000).

offset
integer >= 0

Aantal resultaten dat wordt overgeslagen.

header Parameters
X-API-Key
string

Optioneel. Indien meegestuurd, wordt deze gevalideerd en telt deze als aanroep.

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.

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

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

Voorbeeld: a1b2c3d4

enrollment_id
required
string
Example: enrollment_id=0f3a9c7b1d2e4f5a6b7c8d9e0f1a2b3c

Identifier returned by POST /cards/enrollments/.

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

Voorbeeld: a1b2c3d4

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

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

Voorbeeld: 2026-07-01

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

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

Voorbeeld: 2026-07-11

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

Filters by the email of the employee.

Voorbeeld: empleado@cliente.com

since_id
integer
Example: since_id=216

Exclusive cursor on the transaction id, for pagination.

Voorbeeld: 216

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

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

Voorbeeld: 500

Responses

Response samples

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