Zahlungen

Fast-Track-Zahlungen

Wenn Sie diesen Weg wählen, müssen Sie weder das Widget einbinden noch die übrigen Abschnitte zu Zahlungen befolgen. Ein einziger POST liefert die Zahlungs-URL, und Wealthreader benachrichtigt Ihren Server, wenn das Ergebnis OK oder KO ist. Speichern Sie zur Absicherung die payment_intent_id aus der Antwort: Damit können Sie den Status abfragen, falls die Benachrichtigung nicht ankommt.

Der Zahler öffnet diese URL und autorisiert die Zahlung bei seiner Bank. Im Hintergrund wird dieselbe unveränderliche Zahlungsabsicht erstellt wie im Rest der API: Betrag, Empfänger und Verwendungszweck werden festgelegt, bevor sie den Browser erreichen, und der Header Idempotency-Key verhindert eine zweite Belastung, falls der Aufruf abbricht.

Zahlung erstellen

POST /payments/?action=fast-track

Erforderliche Header: Content-Type: application/json, X-API-Key und Idempotency-Key. Der Schlüssel ist 16 bis 128 Zeichen lang, beginnt mit einem Buchstaben oder einer Ziffer und erlaubt nur Buchstaben, Ziffern und . _ : -; eine UUID v4 ist geeignet. Fehlt er oder ist seine Länge ungültig, lautet die Antwort 400 idempotency_key_required; enthält er andere Zeichen, 422 invalid_customer_reference. Dieser Schlüssel ist zugleich die Händlerreferenz: Sie müssen ihn nicht im Body senden. Wenn Sie denselben Schlüssel mit demselben Body wiederholen, erhalten Sie erneut dieselbe URL. Wenn Sie ihn mit anderen Daten wiederverwenden, lautet die Antwort 409 idempotency_conflict.

Feld	Typ	Beschreibung
`amount`	Zeichenfolge	Betrag in Haupteinheiten als JSON-Zeichenfolge. `"15.50"` entspricht 15,50. Auch eine Ganzzahl ohne Dezimalstellen (`"15"`) ist zulässig. Höchstens zwei Dezimalstellen: `"15.5"` und `"15.50"` sind derselbe Betrag. Minimum `0.01`. Der Höchstbetrag ist auf das Limit begrenzt, das der jeweilige Kunde bei seiner Bank eingerichtet hat. Außerhalb dieser Formatregeln `422 invalid_amount`.
`currency`	Zeichenfolge	Währung nach ISO 4217. In dieser Version `EUR`.
`beneficiary`	Objekt	Empfänger: `name` (1 bis 140 Zeichen) und `iban` (ohne Leerzeichen, mit Prüfziffern).
`reference`	Zeichenfolge	Verwendungszweck auf dem Kontoauszug, bis zu 140 Zeichen.
`priority`	Zeichenfolge	`normal` oder `instant`.
`notification_url`	Zeichenfolge	Öffentliche `https`-URL, an die das OK oder KO gemeldet wird.
`logo`	Zeichenfolge	Optional. Öffentliche `https`-URL des Logos Ihres Unternehmens im SVG-Format: Der Pfad muss auf `.svg` enden (Abfrageparameter sind zulässig), ohne Zugangsdaten oder private Adressen, bis zu 2048 ASCII-Zeichen. Die Zahlungsseite zeigt es über der Zusammenfassung neben dem Namen des Empfängers an; ohne `logo` gibt es keinen Händler-Header. Wealthreader lädt die URL nicht herunter: Der Browser des Zahlers lädt sie. Jeder andere Wert führt zu `422 invalid_logo`.

Alle Felder sind Pflichtfelder außer logo. Der Body ist eine Allowlist. Ein zusätzliches Feld oder ein fehlendes Pflichtfeld führt zu 422 invalid_request. logo ist Teil der Zahlung: Denselben Idempotency-Key mit einem anderen logo zu wiederholen, führt ebenfalls zu 409 idempotency_conflict.

Eine Echtzeitüberweisung hat in dieser API keine eigene Obergrenze. Die Bank lehnt ab, was sie nicht annehmen kann, auch wegen des Betrags, und diese Ablehnung kommt als KO an der notification_url an.

: "${WR_API_KEY:?Defina WR_API_KEY en el entorno seguro de su backend}"
: "${WR_PAYMENT_IDEMPOTENCY_KEY:?Genere un UUID v4 para este pago}"

curl --request POST 'https://api.wealthreader.com/payments/?action=fast-track' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${WR_API_KEY}" \
  --header "Idempotency-Key: ${WR_PAYMENT_IDEMPOTENCY_KEY}" \
  --data '{
    "amount": "15.50",
    "currency": "EUR",
    "beneficiary": {
      "name": "Comercio Online S.L.",
      "iban": "ES9121000418450200051332"
    },
    "reference": "Pedido 78901",
    "priority": "normal",
    "notification_url": "https://tienda.example.com/pagos/aviso",
    "logo": "https://tienda.example.com/marca/logo.svg"
  }'

Die Antwort, beim ersten Mal mit 201 und mit 200, wenn der Schlüssel bereits existierte, enthält die URL und die Kennung der Zahlung:

{
  "url": "https://widget.wealthreader.com/payments/pay/#payment_intent_id=…&widget_token=…&api_origin=https%3A%2F%2Fapi.wealthreader.com",
  "payment_intent_id": "22222222-2222-4222-8222-222222222222"
}

Leiten Sie den Zahler zur URL weiter. Das Token steht im Fragment, läuft mit dem Widget ab (in der Regel nach 15 Minuten) und darf nicht in Ihren Logs gespeichert werden. Speichern Sie payment_intent_id zusammen mit Ihrer Bestellung.

Benachrichtigung über OK oder KO

Wenn Wealthreader den Status der Zahlung prüft und einen Endstatus feststellt, sendet es einen POST an notification_url mit Content-Type: application/json und User-Agent: WealthReader-Payments:

{
  "outcome": "ok",
  "payment_status": "settled",
  "customer_reference": "11111111-1111-4111-8111-111111111111",
  "payment_intent_id": "22222222-2222-4222-8222-222222222222"
}

outcome ist nur dann ok, wenn die Bank die Zahlung abgewickelt hat (settled). rejected, cancelled, expired und failed werden als ko gemeldet. Ein mehrdeutiges Ergebnis (reconciliation_required) ist nicht endgültig und wird nicht gemeldet.
customer_reference ist Ihr Idempotency-Key, und payment_intent_id ist die Kennung, die beim Erstellen der Zahlung zurückgegeben wurde.
Antworten Sie mit 2xx, damit die Benachrichtigung als zugestellt gilt. Wealthreader wartet höchstens 3 Sekunden und folgt keinen Weiterleitungen.
Dieselbe Benachrichtigung kann mehr als einmal ankommen: Behandeln Sie customer_reference plus outcome als idempotent.
Eine URL, die keine öffentliche https-URL ist, wird beim Erstellen der Zahlung abgelehnt und vor jedem Versand erneut geprüft.

Wann sie ankommt. Der Status wird geprüft, solange der Zahler auf der Zahlungsseite bleibt, die ihn bis zum Endergebnis oder bis zum Ablauf der Zahlungssitzung abfragt, sowie jedes Mal, wenn Sie POST /payments/?action=status aufrufen. Es gibt keinen separaten geplanten Versand: Schließt der Zahler die Seite, bevor die Bank abgeschlossen hat, oder antwortet Ihr Server nicht mit 2xx, wird die Benachrichtigung bei der nächsten Prüfung gesendet. Wenn Sie die Benachrichtigung einige Minuten nach der Weiterleitung des Zahlers noch nicht erhalten haben, fragen Sie daher den Status mit der payment_intent_id ab; diese Abfrage löst auch die ausstehende Benachrichtigung aus. Siehe Status, Statusabfragen und Zahlungsabgleich.

Die Benachrichtigung ist nicht signiert. Bevor Sie eine wertvolle Ware oder Dienstleistung liefern, bestätigen Sie das Ergebnis mit POST /payments/?action=status unter Verwendung Ihres X-API-Key und der payment_intent_id: Nur payment_status: settled in dieser Antwort ist eine finanzielle Bestätigung.

Zuletzt aktualisiert 2026-11-08