Betalinger

Betalingsintensjoner og idempotens

En betalingsintensjon fastsetter uforanderlig de økonomiske vilkårene for transaksjonen før brukeren interagerer med widgeten. Dette forhindrer at en ondsinnet klient tukler med beløpet, destinasjonskontoen eller overføringskonseptet på frontend.

Parametere for å opprette en betalingsintensjon (`POST /payments/?action=create`)

1. Standardmodell for handelsmenn (egen begunstiget)

I denne modellen definerer forhandleren all innsamlingsdata:

Felt	Type	Påkrevd	Beskrivelse og regler
`amount_minor`	Heltall	Ja	Beløp i mindre enheter (cent). For eksempel representerer `1500` `15,00 EUR`.
`currency`	Tekststreng	Ja	ISO 4217 3-bokstavers valutakode. For øyeblikket `EUR`.
`beneficiary`	JSON-dataobjekt	Ja	Destinasjonskontodata: `name` (eier, 1 til 140 teksttegn) og `iban` (gyldigIBAN uten mellomrom, med sjekket sjekksiffer). Støtter kun disse to nøklene.
`reference`	Tekststreng	Ja	Konseptet synlig på kontoutskriften (maks. 140 tegn med tekst).
`customer_reference`	Tekststreng	Ja	Intern identifikator for bestillingen eller kunden din (1 til 128 tegn med tekst: bokstaver, tall, `.`, `_`, `:`, `-`; må starte med en bokstav eller et tall).
`allowed_origin`	Tekststreng	Ja	Nøyaktig HTTPS kilde som vil legge inn widgeten (f.eks. `https://tienda.example.com`), uten sti.
`allowed_institution_codes`	Dataarray	Nei	Liste over tillatte enhetskoder (f.eks. `["santander-es", "bbva-es"]`). Hvis utelatt, er enhver enhet i katalogen tillatt.
`locale`	Tekststreng	Nei	Språket i widget-grensesnittet. Kun `es`aksepteres i denne utgivelsen; alle andre verdier returnerer `422 invalid_locale`.
`expected_mode`	Tekststreng	Nei	`mock` eller `live`. Sjekker at du kaller det forventede miljøet; endrer ikke miljøet. Hvis det ikke stemmer, `409 payment_mode_mismatch`.

Kroppen er en streng hviteliste: å sende et felt som ikke er i denne tabellen returnerer 422 invalid_request, det samme gjelder å utelate et obligatorisk felt. Den Content-Type: application/json headeren er obligatorisk (415 json_required) og kroppen er begrenset til 32 KB.

2. Modell med administrert profil (Donasjoner/Demoer)

For regulerte tilfeller eller offentlige demonstrasjoner som cruz_roja_demo, pålegger serveren de finansielle reglene og setter de offisielle målkontoene:

Felt	Type	Påkrevd	Beskrivelse og regler
`profile`	Tekststreng	Ja	Profilidentifikator (f.eks. `cruz_roja_demo`).
`institution_code`	Tekststreng	Ja	Brukervalgt enhetskode (fra `profile-institutions`).
`amount_minor`	Heltall	Ja	Beløpet er begrenset av profilpoliser (f.eks. fra 1 til 100 cent).
`customer_reference`	Tekststreng	Ja	Systemets egen revisjonsreferanse.
`allowed_origin`	Tekststreng	Ja	Widget HTTPS kilde.
`locale`	Tekststreng	Nei	Widget-språk (`es`).
`expected_mode`	Tekststreng	Nei	Forventet modus (`mock` eller `live`).

Når profileer spesifisert, tildeler serveren automatisk den offisielle mottakeren og det tilsvarende konseptet. Ikke send beneficiary eller reference på forespørsler med en administrert profil.

Regelen `Idempotency-Key`

Idempotency-Key-headeren kreves i enhver forespørsel for å opprette en betalingsintensjon. Den må inneholde mellom 16 og 128 tegn med synlig ASCII-tekst, uten mellomrom (f.eks. en v4 UUID). Omfanget er unikt for det autentiserte selskapet:

Samme idempotensnøkkel og samme kropp: Returnerer den opprinnelige intensjonen som tidligere ble opprettet sammen med idempotent_replay: true. Ingen ny belastning genereres og bankordren blir ikke duplisert.
Samme nøkkel av idempotens og annen kropp: svar umiddelbart med HTTP 409 Conflict.
Samme idempotensnøkkel i et annet selskap: tilhører et helt isolert idempotensrom.

Hvis en forespørsel om å opprette en betalingsintensjon får nettverksbrudd eller timeout, prøv på nytt med nøyaktig samme header Idempotency-Key og samme kropp. Ikke generer en ny nøkkel ved en forbigående feil.

Persistens og livssyklus

Forhåndspersistens: Intensjonen registreres i databasen før svaret returneres eller interageres med noen bankkontakt.
Kortvarig widget-token: Responsen token (payment.widget.token) har kort gyldighet (vanligvis 15 til 30 minutter) og kan kun brukes fra den deklarerte allowed_origin .
Samtidig-låsing: Systemet implementerer optimistisk og leases kontroll for å forhindre at to samtidige anrop autoriserer eller endrer samme intensjon.

Vanlige feilkoder

HTTP	Kode	Årsak	Anbefalt handling
`400`	`idempotency_key_required`	Den `Idempotency-Key` headeren mangler eller er feilformatert.	Generer en gyldig nøkkel på mellom 16 og 128 tegn med synlig ASCII-tekst, uten mellomrom.
`409`	`idempotency_conflict`	Nøkkelen har blitt gjenbrukt med andre betalingsdetaljer.	Generer en ny nøkkel for ulike betalinger eller gjenbruk nøyaktig samme forespørselsinnhold.
`409`	`payment_mode_mismatch`	`expected_mode` matcher ikke modusen til miljøet du kaller.	Sjekk om du sikter mot sandkasse eller produksjon; modusen settes av distribusjonen, ikke kallet.
`401`	`invalid_api_key`	Den `X-API-Key`headeren mangler, formatet er ugyldig, eller passnøkkelen eksisterer ikke eller er inaktiv.	Gå gjennom passordet. Aldri inkluder det i frontend.
`403`	`payments_not_allowed`	API-nøkkelen har ikke produktet aktivert `PAYMENTS`.	Kontakt Wealth Reader support for å aktivere betalinger på kontoen din.
`403`	`payment_profile_not_allowed`	Den administrerte profilen er ikke aktivert for selskapet ditt.	Be om profilregistrering fra Wealth Reader.
`429`	`api_limit_reached`	Passkoden din har brukt opp den samlede samtaletelleren.	Det løses ikke ved å prøve på nytt eller vente: det finnes ikke noe vindu eller automatisk tilbakestilling. Be om å utvide grensen.
`415`	`json_required`	Den `Content-Type: application/json`headeren mangler.	Send forespørselsinnholdet som JSON.
`422`	`invalid_request`	Et obligatorisk felt mangler eller et ikke-anerkjent felt er sendt inn.	Sjekk parametertabellen: hoveddelen er en streng hviteliste.
`422`	`invalid_institution`	Den valgte enheten er utilgjengelig eller ugyldig.	Se `GET /payments/entities/` for gyldige koder.
`422`	`invalid_amount`	Beløpet er mindre enn minimum (€0,01) eller er ikke et heltall.	Verifiser at du sender et heltall i cent (`amount_minor`).

Neste steg

Fortsett med Status, periodiske statusforespørsler og avstemming.

Sist oppdatert 2026-09-10

Parametere for å opprette en betalingsintensjon (POST /payments/?action=create)