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

Betalingen

Betalingsintenties en idempotentie

Een betalingsintentie bepaalt onveranderlijk de economische voorwaarden van de transactie voordat de gebruiker met de widget interacteert. Dit voorkomt dat een kwaadaardige klant knoeit met het bedrag, het bestemmingsaccount of het overdrachtsconcept aan de frontend.

Parameters voor het creëren van een betalingsintentie (POST /payments/?action=create)

1. Standaardmodel voor handelaren (Eigen begunstigde)

In dit model definieert de handelaar alle verzamelgegevens:

Veld Type Verplicht Beschrijving en regels
amount_minor Geheel getal Ja Bedrag in kleinere eenheden (centen). Bijvoorbeeld, 1500 vertegenwoordigt 15,00 EUR.
currency Tekststring Ja ISO 4217 3-letter valutacode. Momenteel EUR.
beneficiary JSON-object Ja Bestemmingsaccountgegevens: name (eigenaar, 1 tot 140 teksttekens) en iban (geldigIBAN zonder spaties, met gecontroleerd controlecijfer). Ondersteunt alleen die twee sleutels.
reference Tekststring Ja De betalingsomschrijving die zichtbaar is op het bankafschrift (maximaal 140 tekens tekst).
customer_reference Tekststring Ja Interne identificatie van uw bestelling of klant (1 tot 128 tekens tekst: letters, cijfers, ., _, :, -; moet beginnen met een letter of getal).
allowed_origin Tekststring Ja Exacte HTTPS bron die de widget zal inbedden (bijvoorbeeld https://tienda.example.com), zonder pad.
allowed_institution_codes Array Nee Lijst van toegestane entiteitscodes (bijv. ["santander-es", "bbva-es"]). Als deze wordt weggelaten, is elke entiteit in de catalogus toegestaan.
locale Tekststring Nee De taal van de widgetinterface. Alleen esworden in deze release geaccepteerd; elke andere waarde geeft 422 invalid_localeterug.
expected_mode Tekststring Nee mock of live. Controleert of je de verwachte omgeving aanroept; verandert de omgeving niet. Als het niet overeenkomt, 409 payment_mode_mismatch.

De body is een strikte whitelist: het verzenden van een veld dat niet in deze tabel staat, levert 422 invalid_requestterug, net als het weglaten van een verplicht veld. De Content-Type: application/json header is verplicht (415 json_required) en de body is beperkt tot 32 KB.

2. Model met beheerd profiel (Donaties/Demo's)

Voor gereguleerde gevallen of openbare demonstraties zoals cruz_roja_demolegt de server de financiële regels op en stelt de officiële doelrekeningen vast:

Veld Type Verplicht Beschrijving en regels
profile Tekststring Ja Profielidentificatie (bijv. cruz_roja_demo).
institution_code Tekststring Ja Door de gebruiker geselecteerde entiteitscode (van profile-institutions).
amount_minor Geheel getal Ja Bedrag beperkt door profielregels (bijvoorbeeld van 1 tot 100 cent).
customer_reference Tekststring Ja De eigen auditreferentie van je systeem.
allowed_origin Tekststring Ja Widget HTTPS bron.
locale Tekststring Nee Widgettaal (es).
expected_mode Tekststring Nee Verwachte modus (mock of live).

Wanneer profile is opgegeven, wijst de server automatisch de officiële begunstigde en de bijbehorende betalingsomschrijving toe. Neem beneficiary en reference niet op in verzoeken met een beheerd profiel.

Regel van Idempotency-Key

De Idempotency-Key -header is vereist in elk verzoek om een betalingsintentie te creëren. Deze moet tussen de 16 en 128 tekens zichtbare ASCII-tekst bevatten, zonder spaties (bijvoorbeeld een v4 UUID ). De scope is uniek voor het geauthenticeerde bedrijf:

  • Zelfde idempotentiesleutel en dezelfde body: Retourneert de oorspronkelijke intentie die eerder is gecreëerd samen met idempotent_replay: true. Er wordt geen nieuwe betaling gegenereerd en de bankorder wordt niet gedupliceerd.
  • Dezelfde idempotentiesleutel en een andere requestbody: de API antwoordt direct met HTTP 409 Conflict.
  • Zelfde idempotentiesleutel in een ander bedrijf: behoort tot een andere, volledig geïsoleerde idempotentieruimte.

Als een verzoek om een betalingsintentie te creëren een netwerkstoring of timeout ondervindt, probeer het dan opnieuw met exact dezelfde header Idempotency-Key en dezelfde requestbody. Genereer geen nieuwe sleutel in het geval van een tijdelijke storing.

Persistentie en levenscyclus

  1. Vooraanstaande persistentie: De intentie wordt in de database geregistreerd voordat het antwoord wordt teruggegeven of er interactie wordt gedaan met een bankverbinding.
  2. Efemerale widgettoken: De respons token (payment.widget.token) heeft een korte geldigheidsduur (meestal 15 tot 30 minuten) en kan alleen worden gebruikt vanuit de gedeclareerde allowed_origin .
  3. Gelijktijdige vergrendeling: Het systeem implementeert optimistische en leases controle om te voorkomen dat twee gelijktijdige oproepen dezelfde intentie autoriseren of wijzigen.

Veelvoorkomende foutcodes

HTTP Code Oorzaak Aanbevolen actie
400 idempotency_key_required De Idempotency-Key header ontbreekt of is verkeerd opgemaakt. Genereer een geldige sleutel van tussen de 16 en 128 tekens zichtbare ASCII-tekst, zonder spaties te gebruiken.
409 idempotency_conflict De sleutel is hergebruikt met andere betalingsgegevens. Genereer een nieuwe sleutel voor verschillende betalingen of hergebruik exact dezelfde requestbody.
409 payment_mode_mismatch expected_mode komt niet overeen met de modus van de omgeving die je aanroept. Controleer of je richt op de sandbox of productie; de modus wordt bepaald door de deployment, niet door de call.
401 invalid_api_key De X-API-Keyheader ontbreekt, het formaat is ongeldig, of de API-sleutel bestaat niet of is inactief. Bekijk de toegangscode. Voeg deze nooit toe aan de frontend.
403 payments_not_allowed De API -sleutel heeft het product niet PAYMENTS ingeschakeld. Neem contact op met Wealth Reader support om betalingen op je account te activeren.
403 payment_profile_not_allowed Het beheerde profiel is niet ingeschakeld voor jouw bedrijf. Vraag profielregistratie aan bij Wealth Reader.
429 api_limit_reached Je toegangscode heeft de cumulatieve oproepteller uitgeput. Het wordt niet opgelost door het opnieuw te proberen of te wachten: er is geen venster of automatische reset. Verzoek om de limiet te verlengen.
415 json_required De Content-Type: application/jsonheader ontbreekt. Stuur de requestbody als JSON.
422 invalid_request Er ontbreekt een verplicht veld of er is een niet-erkend veld ingediend. Controleer de parametertabel: de requestbody is een strikte whitelist.
422 invalid_institution De geselecteerde entiteit is niet beschikbaar of ongeldig. Zie GET /payments/entities/ voor geldige codes.
422 invalid_amount Het bedrag is lager dan het minimum (€0,01) of is geen geheel getal. Controleer of je een geheel getal in centen (amount_minor).

Volgende stap

Ga verder met Status, periodieke statusconsultatie en verzoening.

Laatst bijgewerkt