Zahlungen

Status, Statusabfragen und Zahlungsabgleich

Fragen Sie den Zahlungsstatus von Ihrem Backend aus ab, bis ein eindeutiges Ergebnis der Bank vorliegt. Ein Callback, eine SCA-Rückleitung oder das Schließen des Widgets ist keine finanzielle Bestätigung.

Abfrage aus dem Backend

: "${WR_API_KEY:?Defina WR_API_KEY en el entorno seguro de su backend}"

curl --request POST 'https://api.wealthreader.com/payments/?action=status' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${WR_API_KEY}" \
  --data '{
    "payment_intent_id": "11111111-1111-4111-8111-111111111111",
    "refresh": true
  }'

refresh ist optional und standardmäßig true . Wealth Reader begrenzt externe Anfragen nach Absicht; wende Backoff auch auf deinem Backend an und erstelle keine weitere Absicht, solange das Ergebnis mehrdeutig ist.

Drei verschiedene Dimensionen

Spielfeld	Grundwerte	Was du antwortest
`state`	`ready`, `authorization_required`, `processing`, `reconciliation_required`, Terminals	Dauerhafter Flusszustand.
`interaction_status`	`not_started`, `authorization_required`, `processing`, `completed`, `finished`	Ob die technische Interaktion beendet ist oder noch läuft.
`payment_status`	`not_initiated`, `pending`, `unknown`, `settled`, `rejected`, `cancelled`, `expired`, `failed`	Normalisiertes finanzielles Ergebnis.

Die einzige positive Bestätigung ist payment_status: settled, abgeleitet aus einem ausdrücklichen Status der Bank, der die endgültige Ausführung bestätigt. Ein technisches Ergebnis DONE, interaction_status: completed oder payment_status: pending kommt niemals einer Abwicklung gleich.

Mehrdeutiges Ergebnis

Ein nicht erkannter Netzwerkausfall, Timeout oder Antwort nach dem Start ändert die Absicht auf reconciliation_required und legt payment_status: unknownfrei. Der Start wiederholt sich nicht automatisch.

Der aktuelle Anbieter bietet keine Abfrage an, die eine Initiierung rekonstruiert, deren Antwort verloren gegangen ist: Seine Zustandsanfrage benötigt den undurchsichtigen Kontext, der von derselben Initiierung zurückgegeben wird. Daher benötigt dieser Fall eine manuelle Abstimmung; sie kann nicht durch Auto-Polling oder durch die Suche nach der callback-ID abgerufen werden.

In diesem Fall:

Bewahren Sie die Kennung und den Idempotenzschlüssel auf;
schafft keine weitere Absicht und autorisiert nicht erneut;
Sehen Sie sich den authentifizierten Status von Wealth Reader an und behalten Sie Ihre sichere Abstimmungsreferenz;
Wenden Sie sich an den technischen Support; setzen Sie die Statusabfragen nicht fort, wenn automatic_recovery falseist.

Für eine Absicht, die manuell abgestimmt werden muss, kann die Server-zu-Server-Abfrage folgendes umfassen:

{
  "payment_status": "unknown",
  "reconciliation_required": true,
  "reconciliation": {
    "automatic_recovery": false,
    "reference": "wrp_recon_0123456789abcdef0123",
    "request_id": "11111111-1111-4111-8111-111111111111",
    "correlation_id": "22222222-2222-4222-8222-222222222222",
    "reason": "initiation_rejected"
  }
}

Diese Kennungen sind bereinigte Referenzen für den Support. Sie werden nicht an das Widget geliefert und erlauben es dem Kunden nicht, den internen Zustand des Anbieters abzufragen oder zu rekonstruieren.

reason ist ein Wealth Reader-Code, niemals Freitext des Anbieters. initiation_rejected zeigt an, dass der Anbieter mit einer eindeutigen Ablehnung der Initiation reagiert hat; initiation_response_unavailable, dass keine erkennbare Antwort vorlag. In beiden Fällen wurde die Initiation bereits übermittelt, daher wird sie nicht wiederholt: Behalten Sie die Referenz und eskalieren Sie zur Unterstützung.

Rückruf und Wiederholung

Die SCA-Rückleitung erreicht einen ausschließlich für Zahlungen vorgesehenen Callback. Wealth Reader prüft die Zuordnung, leitet die Parameter der Bank unverändert an den Anbieter weiter (unerwartete Parameternamen werden protokolliert, führen aber niemals zur Ablehnung einer bereits autorisierten Rückleitung), verarbeitet die Rückleitung genau einmal und speichert den sensiblen Zustand verschlüsselt. Eine Wiederholung liefert ausschließlich HTTP 409; verlassen Sie sich nicht auf einen internen Fehlercode im Antwortbody.

Die Authentifizierung kann mehrere Weiterleitungen erfordern. Jede validierte REDIRECT läuft im selben SCA Fenster weiter und öffnet einen neuen callbackKontrollpunkt; es erzeugt keine weitere Initiierung. Ein Ergebnis DECOUPLED hält die Absicht in processing , damit das Widget nach dem Status abfragt. Ein explizites RETRY wiederholt nur den bereits vorbereiteten Abschluss, mit begrenzter Wartezeit und Anzahl von Versuchen. ERROR, PASSWORD, MORE_INFO, SELECT_OPTION, ein unbekanntes Ergebnis oder die Erschöpfung dieser Grenzen endet in einer Abstimmung, niemals in einer neuen Initiierung.

Der Händler muss diesen Callback weder bereitstellen noch verarbeiten. Diese Version sendet keine Webhooks an den Händler: Die öffentliche Schnittstelle zur Zahlungsbestätigung verwendet serverseitige Statusabfragen.

Schließen des Widgets

flow_closed signalisiert das Ende der sichtbaren Interaktion. Das Frontend kann das Modal schließen, darf aufgrund dieses Ereignisses aber nicht „bezahlt“ anzeigen. Das Backend bleibt für die Bestätigung oder den Zahlungsabgleich verantwortlich.

Nächster Schritt

Vervollständige die Liste von Sicherheit und Tests.

Zuletzt aktualisiert 2026-09-10