Betalinger

Betalingsintentioner og idempotens

En betalingsintention fastsætter uforanderligt de økonomiske vilkår for transaktionen, før brugeren interagerer med widgetten. Dette forhindrer en ondsindet klient i at manipulere beløbet, destinationskontoen eller overførselskonceptet på frontend.

Parametre til oprettelse af betalingsintentioner (`POST /payments/?action=create`)

1. Standardmodel for købmænd (egen begunstiget)

I denne model definerer forhandleren alle indsamlingsdata:

Bane	Type	Påkrævet	Beskrivelse og regler
`amount_minor`	Heltal	Ja	Mængden i mindre enheder (cent). For eksempel repræsenterer `1500` `15,00 EUR`.
`currency`	Streng	Ja	ISO 4217 3-bogstavs valutakode. Aktuelt `EUR`.
`beneficiary`	Objekt	Ja	Destinationskontodata: `name` (ejer, 1 til 140 teksttegn) og `iban` (gyldigIBAN uden mellemrum, med tjekket kontrolciffer). Understøtter kun de to taster.
`reference`	Streng	Ja	Konceptet er synligt på kontoudtoget (maks. 140 tegn tekst).
`customer_reference`	Streng	Ja	Intern identifikator for din ordre eller kunde (1 til 128 tegn tekst: bogstaver, tal, `.`, `_`, `:`, `-`; skal starte med et bogstav eller tal).
`allowed_origin`	Streng	Ja	Præcis HTTPS kilde, der vil indlejre widgetten (f.eks. `https://tienda.example.com`), uden sti.
`allowed_institution_codes`	Array	Nej	Liste over tilladte enhedskoder (f.eks. `["santander-es", "bbva-es"]`). Hvis den udelades, er enhver enhed i kataloget tilladt.
`locale`	Streng	Nej	Sproget i widget-interfacet. Kun `es`accepteres i denne udgivelse; enhver anden værdi returnerer `422 invalid_locale`.
`expected_mode`	Streng	Nej	`mock` eller `live`. Tjekker, at du kalder det forventede miljø; ændrer ikke omgivelserne. Hvis det ikke matcher, `409 payment_mode_mismatch`.

Kroppen er en streng whitelist: at sende et felt, der ikke er i denne tabel, returnerer 422 invalid_request, ligesom udeladelse af et obligatorisk felt. Content-Type: application/json -headeren er obligatorisk (415 json_required) og kroppen er begrænset til 32 KB.

2. Model med administreret profil (Donationer/Demonstrationer)

For regulerede tilfælde eller offentlige demonstrationer som cruz_roja_demopålægger serveren de finansielle regler og fastsætter de officielle målkonti:

Bane	Type	Påkrævet	Beskrivelse og regler
`profile`	Streng	Ja	Profilidentifikator (f.eks. `cruz_roja_demo`).
`institution_code`	Streng	Ja	Brugervalgt entitetskode (fra `profile-institutions`).
`amount_minor`	Heltal	Ja	Beløbet er begrænset af profilpolicer (f.eks. fra 1 til 100 cent).
`customer_reference`	Streng	Ja	Dit systems egen revisionsreference.
`allowed_origin`	Streng	Ja	Widget HTTPS kilde.
`locale`	Streng	Nej	Widget-sprog (`es`).
`expected_mode`	Streng	Nej	Forventet tilstand (`mock` eller `live`).

Når profileer angivet, tildeler serveren automatisk den officielle modtager og det tilsvarende koncept. Send ikke beneficiary eller reference på forespørgsler med en administreret profil.

Reglen om `Idempotency-Key`

Idempotency-Key-headeren kræves i hvert kald til oprettelse af en betalingsintention. Den skal indeholde mellem 16 og 128 tegn synlig ASCII-tekst uden mellemrum (for eksempel en UUID v4). Dens omfang er unikt for det autentificerede firma:

Samme nøgle og samme krop: Returnerer den oprindelige tidligere oprettede hensigt sammen med idempotent_replay: true. En ny transaktion genereres ikke, og bankordren bliver ikke duplikeret.
Samme idempotensnøgle og forskelligt indhold: svar straks med HTTP 409 Conflict.
Samme nøgle i en anden virksomhed: den tilhører et andet fuldstændigt isoleret område af idempotens.

Hvis et create-kald får netværksafbrydelse eller timeout, prøv igen med præcis samme header Idempotency-Key og samme body. Generer ikke en ny nøgle i tilfælde af en midlertidig fejl.

Persistens og livscyklus

Forudgående persistens: Intentionen registreres i databasen, før svaret returneres eller interageres med en bankforbindelse.
Ephemeral widget-token: Svaret token (payment.widget.token) har en kort gyldighedstid (normalt 15 til 30 minutter) og kan kun bruges fra den erklærede allowed_origin .
Samtidighedslås: Systemet implementerer optimistisk kontrol og leasingaftaler for at forhindre, at to samtidige opkald autoriserer eller ændrer samme hensigt.

Almindelige fejlkoder

HTTP	Kode	Årsag	Anbefalet handling
`400`	`idempotency_key_required`	Den `Idempotency-Key` header mangler eller er forkert formateret.	Generer en gyldig nøgle på mellem 16 og 128 tegn synlig ASCII-tekst uden mellemrum.
`409`	`idempotency_conflict`	Nøglen er blevet genbrugt med andre betalingsoplysninger.	Lav en ny nøgle til andre betalinger eller genbrug den identiske anmodningstekst.
`409`	`payment_mode_mismatch`	`expected_mode` matcher ikke tilstanden i det miljø, du kalder.	Tjek om du sigter efter sandboxen eller produktionen; tilstanden sættes af deploymenten, ikke callet.
`401`	`invalid_api_key`	Den `X-API-Key`header mangler, dens format er ugyldigt, eller adgangsnøglen eksisterer ikke eller er inaktiv.	Gennemgå adgangskoden. Inkluder den aldrig i frontend.
`403`	`payments_not_allowed`	API-tasten har ikke produktet aktiveret `PAYMENTS`.	Kontakt Wealth Reader support for at aktivere betalinger på din konto.
`403`	`payment_profile_not_allowed`	Den administrerede profil er ikke aktiveret for din virksomhed.	Anmod om profilregistrering fra Wealth Reader.
`429`	`api_limit_reached`	Din API-nøgle har opbrugt den kumulative kaldgrænse.	Det løses ikke ved at prøve igen eller vente: der er intet vindue eller automatisk nulstilling. Anmod om at udvide grænsen.
`415`	`json_required`	Den `Content-Type: application/json`header mangler.	Send anmodningens indhold som JSON.
`422`	`invalid_request`	Et krævet felt mangler, eller et ikke-anerkendt felt er indsendt.	Tjek parametertabellen: kroppen er en streng whitelist.
`422`	`invalid_institution`	Den valgte enhed er utilgængelig eller ugyldig.	Se `GET /payments/entities/` for gyldige koder.
`422`	`invalid_amount`	Beløbet er mindre end minimumsbeløbet (€0,01) eller er ikke et heltal.	Verificér, at du sender et heltal i cent (`amount_minor`).

Næste skridt

Fortsæt med Status, afstemning og afstemning.

Senest opdateret 2026-09-10

Parametre til oprettelse af betalingsintentioner (POST /payments/?action=create)