Zahlungen mit Wealth Reader

Architektur in zwei Schritten

Die Zahlungsintegration trennt die Verantwortlichkeiten strikt in zwei Schritten:

sequenceDiagram
autonumber
actor Usuario as Benutzer
participant Front as Frontend (Händler)
participant Back as Backend (Händler)
participant API as Wealth Reader API
participant Widget as Widget Payments
participant Banco as Bankinstitut (SCA)
Note over Back,API: Vorbereitender Schritt (nur verwaltete Profile)
Back->>API: POST /payments/?action=profile-institutions
API-->>Back: Profilkatalog (institution_code)
Note over Back,API: Schritt 1: Unveränderliche Zahlungsabsicht erstellen (Server-to-Server)
Back->>API: POST /payments/?action=create (mit X-API-Key und Idempotency-Key)
API-->>Back: 201 mit payment.id + kurzlebigem payment.widget.token
Note over Front,Widget: Schritt 2: Widget laden und autorisieren (Browser)
Back->>Front: Übergibt payment.id und payment.widget.token
Front->>Widget: WealthReaderPayments.mount(...) oder load-payments.js
Widget->>Usuario: Zeigt unveränderliches Institut, Betrag und Verwendungszweck
Usuario->>Widget: Autorisiert die Zahlung
Widget->>Banco: Weiterleitung / App to App (SCA)
Banco->>API: SCA-Rückleitung an den Callback von Wealth Reader
API-->>Widget: Technische Bestätigung der Autorisierung
Note over Back,API: Zahlungsabgleich und finanzielle Bestätigung
loop Bis zu einem endgültigen Status
Back->>API: POST /payments/?action=status
API-->>Back: payment_status: not_initiated | pending | settled | ...
end

1. Schritt 1 (Sicheres Backend): Ihr Server erstellt eine Zahlungsabsicht (POST /payments/?action=create) mit Ihrem X-API-Key, einem Idempotency-Key und Content-Type: application/json. Dieser Aufruf legt den Betrag (amount_minor, in Cent), die Währung (currency, derzeit nur EUR), den Empfänger (beneficiary.name und beneficiary.iban), den Verwendungszweck auf dem Kontoauszug (reference), Ihre interne Referenz (customer_reference) und den zulässigen Web-Ursprung (allowed_origin) unveränderlich fest. Diese sechs Felder sind Pflichtfelder, und für den Anfragebody gilt eine strikte Positivliste: Jedes unbekannte Feld führt zu 422 invalid_request.
2. Antwort: 201 mit {"success": true, "payment": {…}} — oder 200 bei einer idempotenten Wiederholung. Die Kennung der Zahlungsabsicht steht in payment.id, das kurzlebige Widget-Token in payment.widget.token.
3. Schritt 2 (Frontend des Händlers): Der Browser bindet das Widget mit dem offiziellen Skript load-payments.js oder der Funktion WealthReaderPayments.mount() ein und übergibt ausschließlich payment.id und payment.widget.token. Der Benutzer wählt seine Bank aus (sofern sie nicht in der Zahlungsabsicht vorgewählt wurde) und schließt die starke Kundenauthentifizierung (SCA) in der Bankoberfläche ab.
4. Finanzielle Bestätigung: Ihr Backend fragt den Status über POST /payments/?action=status ab; der Anfragebody lautet exakt {"payment_intent_id": "<id>"}. Es gibt keinen Webhook: Der Status wird bis zu einem endgültigen Zustand regelmäßig abgefragt.

Zwei Zahlungsmodelle

Wealth Reader unterstützt je nach Geschäftsanforderungen zwei Modelle:

1. Standardintegration für Händler (Eigener Empfänger):
   • Der Händler legt Name und IBAN des Empfängers, Betrag, Währung (EUR), Verwendungszweck und Bestellreferenz frei fest.
   • Mit allowed_institution_codes kann er die verfügbaren Banken einschränken oder den gesamten Katalog zulassen.
2. Verwaltete Profile (wie cruz_roja_demo):
   • Für Spenden und öffentliche Demonstrationen konzipiert.
   • Der Server legt die offiziellen Zielkonten fest, damit Gelder ausschließlich an die gemeinnützige Organisation fließen können (zum Beispiel an das Spanische Rote Kreuz mit Beträgen zwischen 0,01 EUR und 1,00 EUR).

Einheitliches Bankinstitutsverzeichnis

Wealth Reader stellt einen einheitlichen Katalog europäischer Institute für die Zahlungsinitiierung über PSD2 bereit:

• GET https://api.wealthreader.com/payments/entities/?country=ES

Er liefert eine Liste der Banken mit standardisierten Namen, Logos, unterstützten Überweisungsmethoden und technischen Anforderungen (etwa der Abfrage der IBAN des Zahlungspflichtigen). Unterstützt werden die Filter country, search (Alias q), code, payment_method, limit und offset.

Dieser Endpunkt ist öffentlich: Er benötigt keinen X-API-Key. Die Übermittlung bringt keinen Vorteil und verbraucht einen Aufruf aus dem Kontingent Ihres Zugangsschlüssels.

Verwenden Sie die Codes immer genau so, wie sie in code zurückgegeben werden. Beim Erstellen der Zahlungsabsicht wird das Format von allowed_institution_codes geprüft, nicht jedoch, ob die Codes im Katalog existieren: Ein falsch geschriebener Code verursacht beim Erstellen keinen Fehler, führt später aber zu einer leeren Bankauswahl.

Trennung der Verantwortlichkeiten

• Der Zahlungszugangsschlüssel (X-API-Key) wird ausschließlich zwischen Servern verwendet. Er darf niemals im Frontend oder in öffentlichen Repositorys enthalten sein.
• Der Browser erhält ausschließlich die Kennung der Zahlungsabsicht und ein kurzlebiges Token, das an den HTTPS-Ursprung gebunden ist.
• Das Widget kann Betrag, Währung, Empfänger, Verwendungszweck und zugelassene Institute nicht ändern.
• Das Schließen des Modals oder Widgets ersetzt nicht die Abfrage des finanziellen Status im Backend.
• Zahlungen teilen weder Zugangsschlüssel noch Tokens oder Callbacks mit dem Bankaggregationsprodukt von Wealth Reader.

Zugangsschlüssel und Kontingent

Für Ihren Zahlungszugangsschlüssel muss das Produkt PAYMENTS freigeschaltet sein; andernfalls antwortet die API mit 403 payments_not_allowed. Ein fehlender oder falsch formatierter Zugangsschlüssel führt zu 401 invalid_api_key.

Nächster Schritt

Fahren Sie mit Integration und Widget fort.