Developers API & Widget
DE
ES · EspañolEN · EnglishFR · FrançaisCA · CatalàDA · DanskDE · DeutschEL · ΕλληνικάFI · SuomiGA · GaeilgeIT · ItalianoJA · 日本語NL · NederlandsNO · NorskPT · PortuguêsRO · RomânăRU · РусскийZH · 中文

Zahlungen

Zahlungsabsichten und Idempotenz

Eine Zahlungsabsicht legt unveränderlich die wirtschaftlichen Bedingungen der Transaktion fest, bevor der Nutzer mit dem Widget interagiert. Dies verhindert, dass ein bösartiger Client am Betrag, Zielkonto oder Übertragungskonzept im Frontend manipuliert.

Parameter zum Erstellen einer Zahlungsabsicht (POST /payments/?action=create)

1. Standardmodell für Händler (Eigener Begünstigter)

In diesem Modell definiert der Händler alle Erhebungsdaten:

Spielfeld Typ Erforderlich Beschreibung und Regeln
amount_minor Ganzzahl Ja Betrag in kleineren Einheiten (Cent). Zum Beispiel stellt 1500 15,00 EUR.
currency Zeichenfolge Ja ISO 4217 3-buchstabiger Währungscode. Derzeit EUR.
beneficiary Objekt Ja Zielkontodaten: name (Besitzer, 1 bis 140 Textzeichen) und iban (gültigesIBAN ohne Leerzeichen, mit geprüfter Prüfziffer). Unterstützt nur diese beiden Schlüssel.
reference Zeichenfolge Ja Das Konzept ist auf dem Kontoauszug sichtbar (maximal 140 Zeichen Text).
customer_reference Zeichenfolge Ja Interne Kennung Ihrer Bestellung oder Ihres Kunden (1 bis 128 Zeichen Text: Buchstaben, Zahlen, ., _, :, -; muss mit einem Buchstaben oder einer Zahl beginnen).
allowed_origin Zeichenfolge Ja Genaue HTTPS Quelle, die das Widget einbettet (z. B. https://tienda.example.com), ohne Pfad.
allowed_institution_codes Array Nein Liste der erlaubten Entitätscodes (z. B. ["santander-es", "bbva-es"]). Wenn ausgelassen, ist jede Entität im Katalog erlaubt.
locale Zeichenfolge Nein Die Sprache der Widget-Oberfläche. Nur eswerden in dieser Version akzeptiert; jeder andere Wert gibt 422 invalid_localezurück.
expected_mode Zeichenfolge Nein mock oder live. Prüft, ob du die erwartete Umgebung aufrufst; ändert die Umgebung nicht. Wenn sie nicht übereinstimmt, 409 payment_mode_mismatch.

Der Body ist eine strikte Whitelist: Das Senden eines Feldes, das nicht in dieser Tabelle ist, gibt 422 invalid_requestzurück, ebenso wie das Weglassen eines verpflichtenden Feldes. Der Content-Type: application/json Header ist verpflichtend (415 json_required) und der Body ist auf 32 KB begrenzt.

2. Modell mit verwaltetem Profil (Spenden/Demos)

Für regulierte Fälle oder öffentliche Demonstrationen wie cruz_roja_demolegt der Server die Finanzregeln fest und legt die offiziellen Zielkonten fest:

Spielfeld Typ Erforderlich Beschreibung und Regeln
profile Zeichenfolge Ja Profilkennung (z. B. cruz_roja_demo).
institution_code Zeichenfolge Ja Vom Benutzer gewählter Entitätscode (aus profile-institutions).
amount_minor Ganzzahl Ja Der Betrag ist durch Profilrichtlinien begrenzt (z. B. von 1 bis 100 Cent).
customer_reference Zeichenfolge Ja Die eigene Audit-Referenz Ihres Systems.
allowed_origin Zeichenfolge Ja Widget HTTPS Quelle.
locale Zeichenfolge Nein Widget-Sprache (es).
expected_mode Zeichenfolge Nein Erwarteter Modus (mock oder live).

Wenn profileangegeben ist, weist der Server automatisch den offiziellen Zahlungsempfänger und den entsprechenden Verwendungszweck zu. Senden Sie bei Anfragen mit einem verwalteten Profil weder beneficiary noch reference.

Regel der Idempotency-Key

Der Idempotency-Key -Header ist bei jedem Aufruf zur Erstellung einer Zahlungsabsicht erforderlich. Er muss zwischen 16 und 128 Zeichen sichtbaren ASCII-Textes enthalten, ohne Leerzeichen (zum Beispiel ein UUID v4). Sein Anwendungsbereich ist einzigartig für das authentifizierte Unternehmen:

  • Derselbe Schlüssel und derselbe Body: Gibt die zuvor erstellte ursprüngliche Absicht zusammen mit idempotent_replay: truezurück. Eine neue Belastung wird nicht generiert und die Bankanweisung wird nicht dupliziert.
  • Gleicher Idempotenzschlüssel und anderer Anfragetext: Die API antwortet sofort mit HTTP 409 Conflict.
  • Gleicher Schlüssel in einer anderen Firma: Es gehört zu einem völlig isolierten Bereich der Idempotenz.

Wenn ein Create-Call einen Netzwerkausfall oder Timeout erleidet, versuchen Sie es erneut mit exakt demselben Header Idempotency-Key und demselben Body. Generieren Sie keinen neuen Schlüssel im Falle eines vorübergehenden Ausfalls.

Persistenz und Lebenszyklus

  1. Vorherige Persistenz: Die Absicht wird in der Datenbank erfasst, bevor die Antwort zurückgegeben oder mit einem Bankverbindungspartner interagiert wird.
  2. Ephemerales Widget-Token: Die Antwort token (payment.widget.token) hat eine kurze Gültigkeit (üblicherweise 15 bis 30 Minuten) und kann nur aus dem deklarierten allowed_origin verwendet werden.
  3. Nebenläufigkeitssperre: Das System implementiert optimistische Kontrolle und Leases, um zu verhindern, dass zwei gleichzeitige Anrufe dieselbe Absicht autorisieren oder ändern.

Häufige Fehlercodes

HTTP Code Ursache Empfohlene Maßnahme
400 idempotency_key_required Der Idempotency-Key -Header fehlt oder ist falsch formatiert. Generiere einen gültigen Schlüssel mit 16 bis 128 Zeichen sichtbaren ASCII-Textes ohne Leerzeichen.
409 idempotency_conflict Der Schlüssel wurde mit anderen Zahlungsdetails wiederverwendet. Erstelle einen neuen Schlüssel für andere Zahlungen oder verwende denselben Körper wieder.
409 payment_mode_mismatch expected_mode passt nicht zum Modus der Umgebung, die du aufrufst. Überprüfe, ob du auf die Sandbox oder die Produktion zielst; der Modus wird durch die Bereitstellung festgelegt, nicht durch den Anruf.
401 invalid_api_key Der X-API-KeyHeader fehlt, sein Format ist ungültig oder der Passkey existiert nicht oder ist inaktiv. Überprüfen Sie den Passcode. Fügen Sie ihn niemals im Frontend an.
403 payments_not_allowed Der API -Schlüssel hat das Produkt PAYMENTS nicht aktiviert. Kontaktieren Sie Wealth Reader Support, um Zahlungen auf Ihrem Konto zu aktivieren.
403 payment_profile_not_allowed Das verwaltete Profil ist für dein Unternehmen nicht aktiviert. Fordere die Profil-Kontoregistrierung bei Wealth Readeran.
429 api_limit_reached Dein API-Schlüssel hat das kumulative Aufruflimit ausgeschöpft. Es wird nicht durch erneutes Versuchen oder Warten gelöst: Es gibt kein Fenster oder automatischen Zurücksetzen. Bitte um Verlängerung des Limits.
415 json_required Der Content-Type: application/jsonHeader fehlt. Senden Sie den Anfragebody als JSON.
422 invalid_request Ein erforderliches Feld fehlt oder ein nicht anerkanntes Feld wurde eingereicht. Überprüfen Sie die Parametertabelle: Der Körper ist eine strenge Whitelist.
422 invalid_institution Die ausgewählte Entität ist nicht verfügbar oder ungültig. Siehe GET /payments/entities/ für gültige Codes.
422 invalid_amount Der Betrag ist geringer als das Minimum (€0,01) oder keine ganze Zahl. Überprüfen Sie, dass Sie eine ganze Zahl in Cent senden (amount_minor).

Nächster Schritt

Fahren Sie fort mit Status, Umfragen und Abstimmung.

Zuletzt aktualisiert