API docs by Redocly

Wealth Reader (8.1.12)

Download OpenAPI specification:

E-mail: info@wealthreader.com

Auf PSD2 basierende regulatorische APIs bieten Zugang zu bestimmten finanziellen Informationen wie Bankkontensalden und Transaktionen. Es gibt jedoch andere Quellen von Vermögensinformationen, die über diese APIs nicht zugänglich sind. Die Wealth Reader API erweitert die von regulatorischen APIs angebotenen Informationen, indem sie Echtzeitzugang zu zusätzlichen Vermögensquellen in jeder Einrichtung weltweit bietet. Es gibt zwei weitere verwandte Dokumente, die Ihnen bei der Integration der Wealth Reader API helfen werden. Eines ist der Javascript-Widget-Integrationsleitfaden: https://docs-en.wealthreader.com/ und das andere ist eine auf dieser Dokumentation basierende Postman-Sammlung. Sehr wichtig: Diese API-Definition ist für Kunden angepasst, die über Widget integrieren, daher wurden einige Parameter weggelassen, die für diesen Integrationstyp nicht notwendig sind, wie z.B. Bankauthentifizierungsparameter, da ein Token verwendet wird.

Core

Kern-API erforderlich für Standardintegrationen

Ruft Finanzanlagen und deren Zusammensetzungsdetails ab

Ruft Finanzanlagen und Details ihrer Zusammensetzung ab, einschließlich Investmentportfolios bestehend aus Aktien oder Fonds, Kreditkarten, Versicherungen und Darlehen. Enthält Eigentumsinformationen für jedes Asset sowie eindeutige Kennungen, die die Datenverarbeitung erleichtern. Es ist möglich, Mock-Daten zu erhalten. Erkundigen Sie sich beim technischen Team, wie das geht.

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

Identifiziert den Kunden im Dienst

code
string

Name der Einrichtung. Die vollständige Liste ist mit GET verfügbar

Beispiel: caixabank

token
string

Identifiziert die verwalteten Anmeldedaten. Der Ablauf, durch den das Token erhalten wurde, ist im Dokument 'Widget-Integrationsleitfaden' beschrieben. Die folgenden Mock-Benutzer sind verfügbar: MOCKDATA, OK-Antwort; MOCKOTP, Antwort mit OTP-Herausforderung; MOCKLOGINKO, Antwort mit Login-Fehler

Beispiel: MOCKDATA

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

Liste der Produkttypen, deren Informationen abgerufen werden sollen. Akzeptiert mehrere durch Kommas getrennte Werte.

Beispiel: accounts,portfolios

only_balances
boolean
Default: false

Gibt an, ob nur die Salden der Produkte anstelle aller verfügbaren Informationen abgerufen werden sollen. Standardwert: false.

Beispiel: false

fetch_transaction_details
boolean
Default: false

Gibt an, ob erweiterte Transaktionsdetails abgerufen werden sollen, wenn der Connector der Einrichtung dies unterstützt. WICHTIG: Die Aktivierung bedeutet, dass pro Transaktion eine oder mehrere zusätzliche Navigationen durchgeführt werden, um die zurückgegebenen Informationen anzureichern. Dies erhöht unweigerlich und erheblich die Ausführungszeit. Die Anzahl der zusätzlichen Navigationen wächst mit dem Transaktionsvolumen. Es wird empfohlen, dies nur zu aktivieren, wenn Sie sicher sind, dass ein höherer Detaillierungsgrad als der standardmäßig zurückgegebene erforderlich ist. Die abgerufenen Details werden in den Schlüssel additional_info auf Ebene jeder Transaktion eingefügt. Die Verwendung dieses Parameters erfordert eine dedizierte Umgebung.

Beispiel: false

date_from
string <date>

Datum, ab dem Transaktionen angefordert werden, im Format JJJJ-MM-TT. Muss ein Datum vor heute sein.

Beispiel: 2024-01-01

date_to
string <date>

Dies gilt nur für die Einschränkung nach zukünftigen Daten für Produkte Loan und Confirming, im Format JJJJ-MM-TT. Das Datum muss nach heute liegen

Beispiel: 2025-12-31

required_products_schema
string

Schema der erforderlichen Produkte. Gibt die Konten oder Karten an, von denen Daten gewünscht werden, mit zusätzlichen Konfigurationen.

Beispiel: 

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

Akzeptiert durch Kommas getrennte Transaktions-UUIDs. Parameter wird nur berücksichtigt, wenn product_types ALL ist oder accounts enthält. Fügt das mit jeder angeforderten Banktransaktion verknüpfte PDF-Dokument hinzu.

Beispiel: 

20966426721d0885ef9d4b95535e1d3198936f16,8772d6c978d37d7af83094abf380b8b703e94105,e59296b79e7f80cec26679d2c65883025fd59295
otp_method
string

Wählt den Zwei-Faktor-Zustellkanal, wenn die API Fehlercode 2017 oder 20171 zurückgab (mehrere OTP-Methoden). Erneut aufrufen mit derselben Sitzungs-ID wie in dieser Antwort und otp_method auf die exakte Zeichenkette im Feld otp_method eines Objekts in statistics.otpMethods setzen — nicht den Array-Index. Bei der ersten Credential-Anfrage weglassen; nach Benutzerwahl senden. Das untenstehende Beispiel ist nur illustrativ; kopieren Sie stets die Zeichenkette aus statistics.otpMethods.

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

Liste der Transaktionstypen

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Tokens abfragen, die mit einem api_key verknüpft sind

Verwenden Sie diese Methode, um die mit einem bestimmten api_key verknüpften Tokens abzufragen. Die Ergebnisse sind paginiert: limit legt die Anzahl der Tokens pro Seite fest (maximal 500) und page wählt die zurückzugebende Seite. api_key, method und limit sind Pflichtfelder; fehlt einer davon oder ist er ungültig, antwortet die API mit HTTP 400 und dem Fehlercode 2.

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

api_key zur Identifizierung des Kunden im Dienst

method
required
string
Value: "get"

Auszuführende Operation. Der einzige unterstützte Wert ist get.

Beispiel: get

limit
required
integer [ 1 .. 500 ]

Anzahl der Tokens pro Seite. Minimum 1, Maximum 500.

Beispiel: 100

page
integer >= 1
Default: 1

Geben Sie die Seitennummer an, die Sie abrufen möchten. Jede Seite enthält bis zu limit Tokens. Wenn nicht angegeben, ist der Standardwert 1.

Beispiel: 1

code
string

Entitätscode zum Filtern der Tokens. Wird er weggelassen, werden die Tokens aller Entitäten zurückgegeben.

Beispiel: bbva

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

Feld zum Sortieren der Ergebnisse: created_at (Erstellungsdatum) oder accesed_at (letztes Zugriffsdatum). Standardwert created_at.

Beispiel: created_at

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

Sortierrichtung: ASC (aufsteigend) oder DESC (absteigend). Standardwert DESC.

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

Einen Token widerrufen

Diese Methode ermöglicht das Widerrufen eines vorhandenen Tokens, um zukünftige API-Zugriffsanfragen zu deautorisieren.

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

Identifiziert den Kunden im Dienst

token
string

Token, das widerrufen werden soll.

Responses

Response samples

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

Einen Token einem anderen api_key zuweisen

Diese Methode ermöglicht die Neuzuweisung eines Tokens von einem api_key zu einem anderen. Beide api_keys müssen aktiv sein und zum selben Unternehmen gehören, und der Token muss zu api_key_source gehören.

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

api_key, von dem der Token neu zugewiesen werden soll.

api_key_target
string

api_key, zu dem der Token neu zugewiesen werden soll.

token
string

Token, das neu zugewiesen werden soll.

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

Neue Domain hinzufügen

Fügt die Verknüpfung zwischen der Domain, die das Widget hosten wird, und dem Ziel-Webhook hinzu. Zum Bearbeiten oder Testen Ihrer Domains verwenden Sie https://www.wealthreader.com/clients/

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

Method to execute.

Beispiel: add

api_key
required
string

User's API key.

domain
required
string

Domain to add.

Beispiel: http://desarrollo.cliente.es

url_callback
required
string

URL for callback.

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

tokenize
required
string
Enum: "1" "0"

Steuert, ob das Widget einen Tokenisierungsfluss startet:

  • 1 - Der Benutzer authentifiziert sich beim Finanzinstitut (Login, Zustimmung, 2FA falls erforderlich) und ein wiederverwendbarer Token wird zurückgegeben
  • 0 - Es wird keine Tokenisierung durchgeführt. Der zuvor erhaltene Token-Wert muss in der Anfrage enthalten sein

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

Liste der Fehlercodes

Liste der Fehlercodes. Achten Sie besonders darauf, dass nicht alle Fehlercodes von Ihrer Anwendung gleich behandelt werden sollten. Bei einem falschen Passwortfehler sollten Sie den Aufruf nicht mit denselben Parametern wiederholen, aber bei einem Fehler, der anzeigt, dass die Entität gewartet wird, können Sie es erneut versuchen. Fordern Sie eine technische Sitzung mit unserem Team an, um Fragen zur Fehlerverwaltung zu klären.

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Liste der Warnungscodes

Liste der Warnungscodes.

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

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Advanced

Optionale Endpunkte, die für Standardintegrationen nicht erforderlich sind. Nur verwenden, wenn explizit von Wealth Reader angewiesen.

Ruft die Liste der unterstützten Einrichtungen ab

Ruft die Liste der unterstützten Einrichtungen und die Informationen ab, die zum Zeichnen des Anmeldeformulars der Einrichtung benötigt werden.

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

Neuen Benutzer registrieren

Dieser Endpoint ist optional und für Standardintegrationen nicht erforderlich. Nur verwenden, wenn explizit von Wealth Reader angewiesen. Dieser Endpoint ermöglicht die Registrierung eines Benutzers entweder auf der Portfolio-Transfer-Plattform Easytransfer oder auf dem Reporting-Tool Acumulas, basierend auf einem eindeutigen Identifikator.

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.

Beispiel: 12345678A

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

Service associated with the user. Determines the data flow.

Beispiel: easy-transfer

email
required
string <email>

User email, used according to service type.

Beispiel: sai_banker@singularbank.com

Responses

Response samples

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

Benutzerregistrierungsstatus prüfen

Dieser Endpoint ist optional und für Standardintegrationen nicht erforderlich. Nur verwenden, wenn explizit von Wealth Reader angewiesen. Überprüft, ob ein Benutzer im Easytransfer- oder Acumulas-System registriert ist und gibt den eindeutigen Zugangslink für den Benutzer zurück.

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

Authentication key

user_id
required
string

User identification document.

Beispiel: 12345678A

Responses

Response samples

Content type
application/json
{}

Einen zuvor registrierten Benutzer widerrufen

Dieser Endpoint ist optional und für Standardintegrationen nicht erforderlich. Nur verwenden, wenn explizit von Wealth Reader angewiesen. Dieser Endpoint ermöglicht das Abmelden eines Benutzers vom Easytransfer- oder Acumulas-Plattformdienst.

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.

Beispiel: 12345678A

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

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

Beispiel: easy-transfer

Responses

Response samples

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

Batch-Verbindungsladung

Dieser Endpoint ist optional und für Standardintegrationen nicht erforderlich. Nur verwenden, wenn explizit von Wealth Reader angewiesen. Wichtig: Um die Batch-Prozessverwaltung auf Wealthreader-Seite zu nutzen, ist eine dedizierte Umgebung erforderlich. Dieser Endpoint ist nicht auf api.wealthreader.com verfügbar. Die unter dem Tag "batch" gruppierten Endpoints ermöglichen die asynchrone Verarbeitung mehrerer Bankverbindungen, im Gegensatz zur synchronen /entities/-Methode. Ideal für die Verarbeitung großer Verbindungsmengen und zur Vermeidung von 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.

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

Allgemeine Statistiken über Batch-Verbindungen abrufen

Dieser Endpoint ist optional. Ruft allgemeine Statistiken über das Verarbeitungsergebnis aller Verbindungen in einem Batch ab.

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

Individuelles Ergebnis einer spezifischen Verbindung innerhalb eines Batch abrufen

Dieser Endpoint ist optional. Ruft das Ergebnis einer spezifischen Verbindung aus dem Batch ab.

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

Prüfung der Kontoinhaberschaft: Prüfen Sie, ob eine IBAN einem Kontoinhaber gehört, mithilfe der SEPA-Empfängerüberprüfung (VoP) der mit Ihrer Lizenz verknüpften Bank. Schritt-für-Schritt-Anleitung: MyBankMatch.

Prüft, ob eine IBAN einem Kontoinhaber gehört (MyBankMatch)

Prüft, ob eine IBAN dem angegebenen Kontoinhaber gehört, mithilfe der SEPA-Empfängerüberprüfung (VoP) Ihrer eigenen Bank, die mit Ihrer WealthReader-Lizenz verknüpft ist. Liefert das Urteil der Bank: Es wird weder durch eine lokale Berechnung der Namensähnlichkeit ersetzt, noch wird ein Zahlungsauftrag erstellt, autorisiert oder ausgeführt.

Vor dem ersten Aufruf

  1. Sie benötigen eine aktive Lizenz mit dem Produkt MY_BANK_MATCH und verfügbarem Kontingent.
  2. Öffnen Sie Kunden · MyBankMatch, klicken Sie auf Bank verbinden und schließen Sie die Authentifizierung im von WealthReader gehosteten Fenster ab. Die tokenisierte Verbindung wird Ihrem api_key zugeordnet; das Bank-Token wird nicht an den Browser übergeben und ist kein Parameter der Anfrage.

Anfrage: formularcodierter Body (application/x-www-form-urlencoded) mit api_key, iban und name, wie bei /entities/. Es wird kein JSON gesendet und der Header X-API-Key wird nicht verwendet. Bewahren Sie den api_key in Ihrem Backend auf.

Antwort: HTTP 200 bedeutet, dass ein Ergebnis des Produkts ermittelt wurde, nicht, dass der Name übereinstimmt. Prüfen Sie success und anschließend payload.result:

payload.result Bedeutung Zusätzliche Felder Kostenpflichtig
MATCH Die Bank stuft den Namen als übereinstimmend mit dem Kontoinhaber ein. Keine. Ja, 0,10 EUR.
PARTIAL_MATCH Die Bank meldet eine teilweise Übereinstimmung (CLOSE_MATCH). suggested_name. Ja, 0,10 EUR.
NO_MATCH Die Bank gibt an, dass der Name nicht übereinstimmt. Keine. Ja, 0,10 EUR.
NOT_CONFIGURED Mit der Lizenz ist noch keine Bank verknüpft. setup_url. Nein.
REAUTH_REQUIRED Die Verbindung zur Bank erfordert eine erneute Authentifizierung. setup_url, reason_code. Nein.
NOT_POSSIBLE Es konnte kein verwertbares Urteil ermittelt werden. Dies ist nicht gleichbedeutend mit NO_MATCH. reason. Nein.

Nur MATCH, PARTIAL_MATCH und NO_MATCH verbrauchen Kontingent. Eingabefehler und nicht eindeutige Ergebnisse werden nicht berechnet.

Es gibt weder einen Idempotenzschlüssel noch eine kostenlose Wiederholung. Wenn Ihnen die Antwort verloren geht (Timeout, Netzwerk oder nicht auswertbarer Body), können das Ergebnis und der zugehörige Kontingentverbrauch für Ihre Anwendung unbekannt sein. Senden Sie dieselbe Abfrage nicht automatisch erneut: Prüfen Sie den Verlauf unter Kunden und wenden Sie sich unter Angabe von statistics.SESSION an den Support.

Vollständige Anleitung: MyBankMatch.

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

Schlüssel aus 8 Hexadezimalzeichen einer aktiven Lizenz mit dem Produkt MY_BANK_MATCH und verfügbarem Kontingent. Bewahren Sie ihn in Ihrem Backend auf.

iban
required
string

IBAN eines SEPA-Landes. Leerzeichen werden entfernt, der Wert wird in Großbuchstaben umgewandelt und die länderspezifische Länge sowie die Prüfziffern nach mod-97 werden validiert.

Beispiel: ES9321005707250200257112

name
required
string <= 140 characters

Name des Kontoinhabers. Nicht leer, gültiges UTF-8, ohne Steuerzeichen und bis zu 140 Zeichen. Er wird getrimmt und interne Leerzeichen werden zusammengefasst.

Beispiel: 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-Kontozahlungen (Account-to-Account), die von der Bank des Zahlers ausgelöst werden. Es gibt zwei Integrationsmöglichkeiten:

  • Fast Track: Ein einziger POST /payments/?action=fast-track liefert die Zahlungs-URL, und Wealth Reader benachrichtigt Ihre notification_url mit OK oder KO. Siehe Fast-Track-Zahlungen.
  • Widget: Ihr Backend erstellt mit POST /payments/?action=create eine unveränderliche Zahlungsabsicht, öffnet das Widget mit dem zurückgegebenen Token und bestätigt das Ergebnis mit POST /payments/?action=status. Siehe Einführung in Zahlungen und Status, Abfrage und Abgleich.

Gemeinsame Regeln für alle Aufrufe /payments/?action=...

  • Methode POST mit dem Header Content-Type: application/json und einem JSON-Objekt als Body (maximal 32768 Byte).
  • Authentifizierung ausschließlich über den Header X-API-Key (wr_live_ gefolgt von 72 Buchstaben oder Ziffern) einer aktiven Lizenz mit dem Produkt PAYMENTS. Er wird niemals im Body gesendet. Jeder authentifizierte Aufruf wird auf das Aufruflimit der Lizenz angerechnet.
  • Der Body ist eine Whitelist: Ein fehlendes Pflichtfeld oder ein nicht vorgesehenes Feld führt zur Antwort 422 invalid_request.
  • Die einzige positive finanzielle Bestätigung ist payment_status: settled. Ein Widget-Ereignis, eine SCA-Rückkehr oder interaction_status: completed bedeuten niemals, dass die Zahlung abgewickelt ist.

Fehlerformat: application/json (nicht problem+json) mit einem stabilen error.code; error.message dient nur der Information und kann sich ändern.

{"success": false, "error": {"code": "invalid_request", "message": "The request body has an invalid schema."}}
HTTP error.code Grund
400 invalid_json Body leer, ungültig oder kein JSON-Objekt.
401 invalid_api_key X-API-Key fehlt, ist fehlerhaft, unbekannt oder inaktiv.
403 payments_not_allowed Die Lizenz verfügt nicht über das Produkt PAYMENTS.
404 action_not_found Unbekannte action.
405 method_not_allowed Andere Methode als POST.
413 request_too_large Body größer als 32768 Byte.
415 json_required Anderer Content-Type als application/json.
422 invalid_request Fehlende oder nicht vorgesehene Felder.
429 api_limit_reached Das Aufruflimit der Lizenz wurde erreicht.
500 internal_error Unerwarteter Fehler.
503 payments_disabled, payments_accept_new_disabled, payment_storage_unavailable, payment_state_unavailable Dienst vorübergehend nicht verfügbar oder neue Zahlungen pausiert.

OK- oder KO-Benachrichtigung einer Fast-Track-Zahlung Webhook

Wealth Reader sendet diesen POST an die notification_url einer Fast-Track-Zahlung, wenn es den Status der Zahlung prüft und einen Endstatus vorfindet. reconciliation_required ist kein Endstatus und wird nicht gemeldet: Bestätigen Sie ihn mit status.

  • outcome ist nur dann ok, wenn die Bank die Zahlung abgewickelt hat (settled); rejected, cancelled, expired und failed werden als ko gemeldet.
  • Der Status wird geprüft, solange sich der Zahler auf der Zahlungsseite befindet (die ihn bis zum Endergebnis oder bis zum Ablauf der Zahlungssitzung abfragt), und jedes Mal, wenn Sie status aufrufen. Es gibt keinen separaten geplanten Versand: Wenn der Zahler die Seite verlässt, bevor die Bank zu einem Ergebnis kommt, oder Ihr Server nicht mit 2xx antwortet, wird die Benachrichtigung bei der nächsten Prüfung gesendet. Wenn sie einige Minuten nach der Weiterleitung des Zahlers nicht eingetroffen ist, rufen Sie status mit der payment_intent_id auf; dieser Aufruf löst auch die ausstehende Benachrichtigung aus.
  • Antworten Sie mit einem beliebigen 2xx, damit sie als zugestellt gilt. Wealth Reader folgt keinen Weiterleitungen und wartet höchstens 3 Sekunden.
  • Dieselbe Benachrichtigung kann mehrfach eintreffen: Behandeln Sie customer_reference zusammen mit outcome als idempotent.
  • Die Anfrage ist nicht signiert. Bevor Sie ein wertvolles Gut ausliefern, bestätigen Sie das Ergebnis mit status unter Verwendung Ihres X-API-Key und der payment_intent_id aus der Benachrichtigung.
header Parameters
User-Agent
required
string
Value: "WealthReader-Payments"
Request Body schema: application/json
required
outcome
required
string
Enum: "ok" "ko"

ok nur bei settled.

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

Endgültiges finanzielles Ergebnis.

customer_reference
required
string

Der Idempotency-Key, den Sie beim Erstellen der Zahlung gesendet haben.

payment_intent_id
required
string <uuid>

Von fast-track zurückgegebene Kennung. Verwenden Sie sie, um das Ergebnis mit status zu bestätigen.

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

Erstellt eine Zahlung und liefert ihre URL (Fast Track)

Ein einziger Aufruf, der die Zahlungs-URL zurückgibt. Der Zahler öffnet sie und autorisiert die Zahlung bei seiner Bank; sobald die Zahlung einen Endstatus erreicht, benachrichtigt Wealth Reader Ihre notification_url mit OK oder KO (siehe Webhook notification_url). Im Hintergrund wird dieselbe unveränderliche Zahlungsabsicht wie bei create erstellt: Betrag, Begünstigter und Verwendungszweck werden festgelegt, bevor sie den Browser erreichen.

Der Header Idempotency-Key ist zugleich Ihre Händlerreferenz (customer_reference in der Benachrichtigung): Er wird nicht im Body gesendet. Wenn Sie denselben Schlüssel mit demselben Body wiederholen, erhalten Sie dieselbe URL; wenn Sie ihn mit anderen Daten wiederverwenden (auch mit einem anderen logo), lautet die Antwort 409 idempotency_conflict.

Für eine Echtzeitüberweisung gibt es in dieser API keine eigene Obergrenze: Die Bank lehnt ab, was sie nicht akzeptieren kann, auch aufgrund des Betrags, und diese Ablehnung wird als KO gemeldet.

header Parameters
X-API-Key
required
string

API-Schlüssel einer Lizenz mit dem Produkt PAYMENTS. Bewahren Sie ihn in Ihrem Backend auf.

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

16 bis 128 Zeichen; muss mit einem Buchstaben oder einer Ziffer beginnen und darf nur Buchstaben, Ziffern und . _ : - enthalten. Eine UUID v4 ist gültig. Sie ist zugleich die Händlerreferenz, die in der Benachrichtigung zurückgegeben wird.

Request Body schema: application/json
required
amount
required
string

Betrag in Haupteinheiten als JSON-Zeichenkette. "15.50" entspricht 15,50 EUR; eine Ganzzahl ohne Dezimalstellen ("15") wird ebenfalls akzeptiert. Höchstens zwei Dezimalstellen, daher sind "15.5" und "15.50" derselbe Betrag. Mindestens 0.01. Der Höchstbetrag ist auf das Limit begrenzt, das jeder Kunde bei seiner Bank eingerichtet hat.

Beispiel: 15.50

currency
required
string
Value: "EUR"

Währung nach ISO 4217. In dieser Version nur EUR.

Beispiel: EUR

required
object (payments-beneficiary)

Empfänger der Überweisung. Er kann nach dem Erstellen der Zahlung nicht mehr geändert werden.

reference
required
string [ 1 .. 140 ] characters

Verwendungszweck auf dem Kontoauszug, bis zu 140 Zeichen.

Beispiel: Pedido 78901

priority
required
string
Enum: "normal" "instant"

normal (SEPA-Überweisung) oder instant (SEPA-Echtzeitüberweisung).

Beispiel: normal

notification_url
required
string <= 2000 characters

Öffentliche https-URL, die die OK- oder KO-Benachrichtigung empfängt. Ohne Zugangsdaten, Port 443, falls angegeben, und ohne private, lokale oder Metadaten-Adressen.

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

logo
string <= 2048 characters

Optional. Öffentliche https-URL des Logos Ihres Unternehmens im SVG-Format (der Pfad muss auf .svg enden; Abfrageparameter sind zulässig), ohne Zugangsdaten, Fragment oder private Adressen, bis zu 2048 ASCII-Zeichen. Die Zahlungsseite zeigt es oberhalb der Zusammenfassung an; Wealth Reader lädt es nicht herunter, sondern der Browser des Zahlers lädt es. Jeder andere Wert führt zur Antwort 422 invalid_logo.

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

Responses

Request samples

Content type
application/json
{}

Response samples

Erstellt eine Zahlungsabsicht (Widget)

Erstellt eine unveränderliche Zahlungsabsicht und gibt ein kurzlebiges Token zurück, um das Widget im Browser des Zahlers zu öffnen. Betrag, Begünstigter und Verwendungszweck werden im Backend festgelegt und können im Browser nicht geändert werden. Bestätigen Sie nach dem Schließen des Widgets das Ergebnis aus Ihrem Backend mit status.

Es gibt zwei Body-Varianten:

  • Standard: Sie legen amount_minor, currency, beneficiary, reference, customer_reference und allowed_origin fest.
  • Verwaltetes Profil (zum Beispiel cruz_roja_demo): Wealth Reader legt Begünstigten, Verwendungszweck und Limits fest; Sie senden profile, institution_code, amount_minor, customer_reference und allowed_origin. Die Banken erhalten Sie mit profile-institutions.

Wenn Sie denselben Idempotency-Key mit demselben Body wiederholen, erhalten Sie dieselbe Zahlungsabsicht (200, idempotent_replay: true); wenn Sie ihn mit anderen Daten wiederverwenden, lautet die Antwort 409 idempotency_conflict. Der Schlüssel gilt nur für Ihr Unternehmen.

Anleitung: Zahlungsabsichten und Idempotenz und Integration mit dem Widget.

header Parameters
X-API-Key
required
string

API-Schlüssel einer Lizenz mit dem Produkt PAYMENTS. Bewahren Sie ihn in Ihrem Backend auf.

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

16 bis 128 sichtbare ASCII-Zeichen. Erzeugen Sie einen pro Zahlung (eine UUID v4 ist gültig) und verwenden Sie ihn erneut, wenn Sie den Aufruf wiederholen.

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

Betrag in Untereinheiten (Cent) als JSON-Ganzzahl. 1500 entspricht 15,00 EUR. Der Höchstbetrag ist auf das Limit begrenzt, das jeder Kunde bei seiner Bank eingerichtet hat.

Beispiel: 1500

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

Empfänger der Überweisung. Er kann nach dem Erstellen der Zahlung nicht mehr geändert werden.

reference
required
string [ 1 .. 140 ] characters

Verwendungszweck auf dem Kontoauszug, bis zu 140 Zeichen.

Beispiel: Pedido 78901

customer_reference
required
string <= 128 characters

Ihre interne Referenz der Zahlung. 1 bis 128 Zeichen; beginnt mit einem Buchstaben oder einer Ziffer und enthält nur Buchstaben, Ziffern und . _ : -.

Beispiel: order-78901

allowed_origin
required
string

Origin (https://host[:puerto], ohne Pfad, Abfrage oder Fragment) der Seite, die das Widget öffnet. Das Widget funktioniert nur von diesem Origin aus.

Beispiel: https://tienda.example.com

locale
string
Value: "es"

Optional. Sprache des Widgets; in dieser Version nur es.

expected_mode
string
Enum: "mock" "live"

Optional. Wenn der Wert nicht mit der Umgebung übereinstimmt, antwortet der Aufruf mit 409 payment_mode_mismatch, anstatt die Zahlung zu erstellen.

allowed_institution_codes
Array of strings <= 2500 items

Optional. Nicht leere Liste eindeutiger Bankcodes (siehe /payments/entities/), aus denen der Zahler wählen kann.

Beispiel: 

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

Optional. Öffentliche https-URL Ihres Logos im SVG-Format (Pfad endet auf .svg), ohne Zugangsdaten, Fragment oder private Adressen, bis zu 2048 Zeichen.

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

Fragt den Status einer Zahlung ab

Server-zu-Server-Abfrage des Status einer Zahlung, bis ein Ergebnis der Bank vorliegt. Ein Callback, eine SCA-Rückkehr oder das Schließen des Widgets sind keine finanzielle Bestätigung: Nur payment_status: settled ist eine.

Wealth Reader begrenzt die externen Abfragen pro Zahlungsabsicht; wenden Sie auch in Ihrem Backend ein Backoff an und erstellen Sie keine weitere Zahlungsabsicht, solange das Ergebnis mehrdeutig ist.

Mehrdeutiges Ergebnis: Ein Netzwerkausfall, ein Timeout oder eine nicht erkannte Antwort nach dem Absenden der Auslösung versetzt die Zahlungsabsicht in den Status reconciliation_required mit payment_status: unknown, und die Antwort enthält reconciliation. Die Auslösung wird niemals automatisch wiederholt. Bewahren Sie die Kennung und den Idempotenzschlüssel auf, erstellen Sie keine weitere Zahlungsabsicht und autorisieren Sie nicht erneut; wenn automatic_recovery den Wert false hat, beenden Sie die Abfragen und eskalieren Sie mit reconciliation.reference an den Support.

Bei Fast-Track-Zahlungen sendet diese Abfrage außerdem die ausstehende OK/KO-Benachrichtigung an notification_url, wenn die Zahlung einen Endstatus erreicht hat.

Anleitung: Status, Abfrage und Abgleich.

header Parameters
X-API-Key
required
string

API-Schlüssel der Lizenz, die die Zahlung erstellt hat.

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

Von create zurückgegebene payment.id (bei Fast Track die von fast-track zurückgegebene payment_intent_id).

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

refresh
boolean
Default: true

Optional. true fragt bei der Bank den aktuellen Status ab, sofern sinnvoll; false gibt den gespeicherten Status zurück.

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

Listet die Banken und Bedingungen eines verwalteten Profils auf

Gibt die Bedingungen eines für Ihr Unternehmen freigeschalteten verwalteten Profils (Begünstigter, Verwendungszweck, Betragslimits) sowie die Banken zurück, die der Zahler wählen kann. Verwenden Sie den gewählten code als institution_code in create.

header Parameters
X-API-Key
required
string

API-Schlüssel einer Lizenz mit dem Produkt PAYMENTS.

Request Body schema: application/json
required
profile
required
string

Code des verwalteten Profils.

Beispiel: cruz_roja_demo

Responses

Request samples

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

Response samples

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

Listet die für Zahlungen verfügbaren Banken auf

Katalog der Banken, die Zahlungen auslösen können, mit ihrem Logo und den unterstützten Zahlungsmethoden. X-API-Key ist optional; wenn Sie ihn senden, wird er validiert und als Aufruf gezählt. Außerdem wird POST mit denselben Filtern in einem JSON-Body akzeptiert sowie POST /payments/?action=entities mit verpflichtendem X-API-Key.

Unbekannte Filter werden ignoriert und führen nie zu einem Validierungsfehler.

query Parameters
country
string
Example: country=ES

Ländercode nach ISO 3166-1 Alpha-2. ALL oder leer bedeutet kein Filter.

Beispiel: ES

search
string

Im Namen oder Code enthaltener Text, ohne Beachtung der Groß-/Kleinschreibung (Alias q).

code
string
Example: code=santander-es

Exakter Code der Bank, ohne Beachtung der Groß-/Kleinschreibung.

Beispiel: santander-es

payment_method
string
Enum: "sepa_credit_transfer" "instant_sepa_credit_transfer"

Nur die Banken, die diese Zahlungsmethode unterstützen.

limit
integer [ 1 .. 2000 ]

Seitengröße (1 bis 2000).

offset
integer >= 0

Anzahl der übersprungenen Ergebnisse.

header Parameters
X-API-Key
string

Optional. Wenn er gesendet wird, wird er validiert und als Aufruf gezählt.

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.

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

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

Beispiel: a1b2c3d4

enrollment_id
required
string
Example: enrollment_id=0f3a9c7b1d2e4f5a6b7c8d9e0f1a2b3c

Identifier returned by POST /cards/enrollments/.

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

Beispiel: a1b2c3d4

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

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

Beispiel: 2026-07-01

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

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

Beispiel: 2026-07-11

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

Filters by the email of the employee.

Beispiel: empleado@cliente.com

since_id
integer
Example: since_id=216

Exclusive cursor on the transaction id, for pagination.

Beispiel: 216

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

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

Beispiel: 500

Responses

Response samples

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