Maksut

Maksuaikomukset ja idempotenssi

Maksuaikomus asettaa muuttumattomasti tapahtuman taloudelliset ehdot ennen kuin käyttäjä on vuorovaikutuksessa widgetin kanssa. Tämä estää haitallista asiakasta manipuloimasta summaa, kohdetiliä tai maksun viestiä käyttöliittymässä.

Maksuaikomuksen luomisen parametrit (`POST /payments/?action=create`)

1. Kauppiaiden standardimalli (oma edunsaaja)

Tässä mallissa kauppias määrittelee kaikki maksun vastaanottamista koskevat tiedot:

Kenttä	Tyyppi	Vaaditaan	Kuvaus ja säännöt
`amount_minor`	Kokonaisluku	Kyllä	Summa pienemmissä yksiköissä (senteissä). Esimerkiksi `1500` edustaa `15,00 EUR`.
`currency`	Tekstimerkkijono	Kyllä	ISO 4217 3-kirjaiminen valuuttakoodi. Tällä hetkellä `EUR`.
`beneficiary`	JSON-objekti	Kyllä	Kohdetilin tiedot: `name` (omistaja, 1–140 tekstimerkkiä) ja `iban` (voimassa oleva IBAN ilman välilyöntejä, jonka tarkistusnumero on validoitu). Tukee vain näitä kahta avainta.
`reference`	Tekstimerkkijono	Kyllä	Maksun viesti näkyy pankkitiliotteessa (enintään 140 merkkiä tekstiä).
`customer_reference`	Tekstimerkkijono	Kyllä	Tilauksesi tai asiakkaasi sisäinen tunniste (1–128 merkkiä: kirjaimet, numerot, `.`, `_`, `:`, `-`; tulee alkaa kirjaimella tai numerolla).
`allowed_origin`	Tekstimerkkijono	Kyllä	Tarkka HTTPS lähde, joka upottaa widgetin (esim. `https://tienda.example.com`), ilman polkua.
`allowed_institution_codes`	Taulukko	Ei	Sallittujen entiteettikoodien luettelo (esim. `["santander-es", "bbva-es"]`). Jos se jätetään pois, mikä tahansa luettelon entiteetti on sallittu.
`locale`	Tekstimerkkijono	Ei	Widget-käyttöliittymän kieli. Tässä julkaisussa hyväksytään vain `es`; muut arvot palauttavat `422 invalid_locale`.
`expected_mode`	Tekstimerkkijono	Ei	`mock` tai `live`. Tarkistaa, että kutsut odotettua ympäristöä; ei muuta ympäristöä. Jos se ei täsmää, `409 payment_mode_mismatch`.

Runko on tiukka valkoinen lista: kentän lähettäminen, joka ei ole tässä taulukossa, palauttaa 422 invalid_request, samoin kuin pakollisen kentän poisjättäminen. Content-Type: application/json otsikko on pakollinen (415 json_required) ja runko on rajoitettu 32 KB:iin.

2. Malli, jossa on hallittu profiili (lahjoitukset/demot)

Säädellyissä tapauksissa tai julkisissa esittelyissä, kuten cruz_roja_demo, palvelin asettaa taloussäännöt ja asettaa viralliset tavoitetilit:

Kenttä	Tyyppi	Vaaditaan	Kuvaus ja säännöt
`profile`	Tekstimerkkijono	Kyllä	Profiilitunniste (esim. `cruz_roja_demo`).
`institution_code`	Tekstimerkkijono	Kyllä	Käyttäjän valitsema entiteettikoodi (lähteestä `profile-institutions`).
`amount_minor`	Kokonaisluku	Kyllä	Summa on rajoitettu profiilin säännöillä (esim. 1–100 senttiä).
`customer_reference`	Tekstimerkkijono	Kyllä	Järjestelmäsi oma tarkastusviite.
`allowed_origin`	Tekstimerkkijono	Kyllä	Widget HTTPS lähde.
`locale`	Tekstimerkkijono	Ei	Widget-kieli (`es`).
`expected_mode`	Tekstimerkkijono	Ei	Odotettu tila (`mock` tai `live`).

Kun profile on määritelty, palvelin asettaa automaattisesti virallisen maksunsaajan ja maksun viestin. Älä sisällytä kenttiä beneficiary tai reference hallittua profiilia käyttäviin pyyntöihin.

Sääntö `Idempotency-Key`

Idempotency-Key-otsikko vaaditaan kaikissa pyynnöissä maksuaikomuksen luomiseksi. Sen tulee sisältää 16–128 merkkiä näkyvää ASCII-tekstiä ilman välilyöntejä (esim. v4 UUID). Sen laajuus on ainutlaatuinen todennetulle yritykselle:

Sama idempotenssiavain ja sama runko: Palauttaa aiemmin luodun alkuperäisen intention yhdessä idempotent_replay: truekanssa. Uutta veloitusta ei synnytä eikä pankkitilausta kopioida.
Sama idempotenssiavain ja eri pyynnön runko: API palauttaa välittömästi HTTP 409 Conflict.
Sama idempotenssiavain toisessa yrityksessä: kuuluu toiseen täysin erilliseen idempotenssialueeseen.

Jos maksuaikomuksen luomispyyntö aiheuttaa verkkokatkon tai aikakatkaisun, kokeile uudelleen täsmälleen samalla otsikolla Idempotency-Key ja samalla rungolla. Älä luo uutta avainta tilapäisen virheen sattuessa.

Pysyvyys ja elinkaari

Aiempi pysyvyys: Aikomus tallennetaan tietokantaan ennen vastauksen palauttamista tai minkään pankkiliittimen kanssa vuorovaikutusta.
Lyhytaikainen widget-token: Vastauksen token (payment.widget.token) on lyhytaikainen (yleensä 15–30 minuuttia) ja sitä voi käyttää vain ilmoitetusta allowed_origin :stä.
Samanaikaisuuden lukitus: Järjestelmä toteuttaa optimistisen ja leases hallinnan estääkseen kahta samanaikaista kutsua valtuuttamasta tai muuttamasta samaa tarkoitusta.

Yleiset virhekoodit

HTTP	Koodi	Syy	Suositeltu toimenpide
`400`	`idempotency_key_required`	`Idempotency-Key`-otsikko puuttuu tai on väärin muotoiltu.	Luo kelvollinen avain, jossa on 16–128 merkkiä näkyvää ASCII-tekstiä ilman välilyöntejä.
`409`	`idempotency_conflict`	Avainta on käytetty uudelleen eri maksutietojen kanssa.	Luo uusi avain eri maksuihin tai käytä täsmälleen samaa pyynnön runkoa uudelleen.
`409`	`payment_mode_mismatch`	`expected_mode` ei vastaa ympäristön tilaa, johon soitat.	Tarkista, tähtäätkö hiekkalaatikkoon vai tuotantoon; tila määräytyy käyttöönoton mukaan, ei kutsun mukaan.
`401`	`invalid_api_key`	`X-API-Key`-otsikko puuttuu, sen muoto on virheellinen, tai API-avain ei ole olemassa tai on passiivinen.	Tarkista pääsykoodi. Älä koskaan laita sitä frontendiin.
`403`	`payments_not_allowed`	API-avaimella ei ole käytössä tuotetta `PAYMENTS`.	Ota yhteyttä Wealth Reader tukeen aktivoidaksesi maksut tililläsi.
`403`	`payment_profile_not_allowed`	Hallittua profiilia ei ole käytössä yrityksessäsi.	Pyydä profiilitilin rekisteröintiä Wealth Reader:lta.
`429`	`api_limit_reached`	API-avaimesi kumulatiivinen kutsukiintiö on käytetty loppuun.	Sitä ei ratkaista yrittämällä uudelleen tai odottamalla: ei ole ikkunaa tai automaattista nollausta. Pyydä rajoituksen pidentämistä.
`415`	`json_required`	`Content-Type: application/json`otsikko puuttuu.	Lähetä pyynnön runko JSON-muodossa.
`422`	`invalid_request`	Pakollinen kenttä puuttuu tai tunnistamaton kenttä on lähetetty.	Katso parametritaulukko: runko on tiukka valkoinen lista.
`422`	`invalid_institution`	Valittu yksikkö on käyttökelvoton tai mitätön.	Katso `GET /payments/entities/` kelvollisia koodeja.
`422`	`invalid_amount`	Summa on pienempi kuin minimi (€0,01) tai ei ole kokonaisluku.	Varmista, että lähetät kokonaislukua sentteinä (`amount_minor`).

Seuraava askel

Jatka Tilat, tilakyselyt ja täsmäytys.

Päivitetty viimeksi 2026-09-10

Maksuaikomuksen luomisen parametrit (POST /payments/?action=create)