Íocaíochtaí

Rúin íocaíochta agus idempotency

Socraíonn rún íocaíochta téarmaí airgeadais an idirbhirt go do-athraithe sula n-idirghníomhaíonn an t-úsáideoir leis an ngiuirléid. Cuireann sé seo cosc ar chliant mailíseach an méid, an cuntas cinn scríbe nó tuairisc an aistrithe a athrú sa frontend.

Paraiméadair chruthaithe (`POST /payments/?action=create`)

1. Samhail chaighdeánach do cheannaithe (Tairbhí dá gcuid féin)

Sa tsamhail seo, socraíonn an ceannaí na sonraí glactha íocaíochta go léir:

Réimse	Cineál	Riachtanach	Cur síos agus rialacha
`amount_minor`	Slánuimhir	Tá	Méid sna haonaid is lú (ceinteanna). Mar shampla, seasann `1500` do `15,00 EUR`.
`currency`	Teaghrán	Tá	Cód airgeadra ISO 4217 trí litir. `EUR` faoi láthair.
`beneficiary`	Oibiacht	Tá	Sonraí an chuntais cinn scríbe: `name` (sealbhóir, 1 go 140 carachtar) agus `iban` (IBAN bailí gan spásanna, agus an digit seiceála fíoraithe). Ní cheadaítear ach an dá eochair sin.
`reference`	Teaghrán	Tá	Tuairisc na híocaíochta atá le feiceáil ar an ráiteas bainc (140 carachtar ar a mhéad).
`customer_reference`	Teaghrán	Tá	Aitheantóir inmheánach d’ordaithe nó do chustaiméara (1 go 128 carachtar: litreacha, uimhreacha, `.`, `_`, `:`, `-`; caithfidh litir nó uimhir a bheith ar dtús).
`allowed_origin`	Teaghrán	Tá	An bunús HTTPS cruinn a leabóidh an ghiuirléid (m.sh. `https://tienda.example.com`), gan chonair.
`allowed_institution_codes`	Eagar	Níl	Liosta de chóid institiúidí ceadaithe (m.sh. `["santander-es", "bbva-es"]`). Má fhágtar ar lár é, ceadaítear aon institiúid sa chatalóg.
`locale`	Teaghrán	Níl	Teanga chomhéadan na giuirléide. Sa leagan seo ní ghlactar ach le `es`; tugann aon luach eile `422 invalid_locale`.
`expected_mode`	Teaghrán	Níl	`mock` nó `live`. Seiceálann sé go bhfuil an timpeallacht ionchais á húsáid; ní athraíonn sé an timpeallacht. Mura bhfuil comhoiriúnú ann, tugtar `409 payment_mode_mismatch`.

Leanann corp an iarratais liosta ceadaithe docht: má sheoltar réimse nach bhfuil sa tábla seo, tugtar 422 invalid_request, mar a tharlaíonn má fhágtar réimse riachtanach ar lár. Tá an ceanntásc Content-Type: application/json riachtanach (415 json_required) agus tá an corp teoranta do 32 KB.

2. Samhail le próifíl bhainistithe (Síntiúis / Taispeántais)

I gcásanna rialaithe nó taispeántais phoiblí ar nós cruz_roja_demo, forchuireann an freastalaí na rialacha airgeadais agus socraíonn sé na cuntais oifigiúla cinn scríbe:

Réimse	Cineál	Riachtanach	Cur síos agus rialacha
`profile`	Teaghrán	Tá	Aitheantóir na próifíle (m.sh. `cruz_roja_demo`).
`institution_code`	Teaghrán	Tá	Cód na hinstitiúide a roghnaigh an t-úsáideoir (ó `profile-institutions`).
`amount_minor`	Slánuimhir	Tá	Méid teoranta ag rialacha na próifíle (m.sh. 1 go 100 ceint).
`customer_reference`	Teaghrán	Tá	Tagairt iniúchta do chórais féin.
`allowed_origin`	Teaghrán	Tá	Bunús HTTPS na giuirléide.
`locale`	Teaghrán	Níl	Teanga na giuirléide (`es`).
`expected_mode`	Teaghrán	Níl	An mód ionchais (`mock` nó `live`).

Nuair a shonraítear profile, socraíonn an freastalaí an tairbhí oifigiúil agus tuairisc na híocaíochta go huathoibríoch. Ná seol beneficiary ná reference in iarratais le próifíl bhainistithe.

Riail `Idempotency-Key`

Tá an ceanntásc Idempotency-Key riachtanach i ngach glao cruthaithe. Caithfidh idir 16 agus 128 carachtar infheicthe ASCII a bheith ann, gan spásanna (mar shampla UUID v4). Tá a raon feidhme teoranta don chuideachta fhíordheimhnithe:

An eochair chéanna agus an corp céanna: tugtar ar ais an rún bunaidh a cruthaíodh cheana, mar aon le idempotent_replay: true. Ní chruthaítear muirear nua agus ní dhéantar an t-ordú bainc a dhúbailt.
An eochair chéanna agus corp difriúil: freagraíonn an API láithreach le HTTP 409 Conflict.
An eochair chéanna i gcuideachta eile: baineann sí le spás idempotency eile atá scoite amach go hiomlán.

Má tharlaíonn briseadh líonra nó teorainn ama le glao cruthaithe, bain triail eile as leis an gceannteideal céanna Idempotency-Key agus an corp céanna go beacht. Ná gin eochair nua mar gheall ar earráid shealadach.

Stóráil mharthanach agus saolré

Stóráil roimh ré: Taifeadtar an rún sa bhunachar sonraí sula dtugtar freagra nó sula ndéantar teagmháil le haon nascóir bainc.
Token gearrshaolach na giuirléide: Bíonn token an fhreagra (payment.widget.token) bailí ar feadh tréimhse ghearr (15 go 30 nóiméad de ghnáth) agus ní féidir é a úsáid ach ón allowed_origin sonraithe.
Glasáil chomhthráthachta: Úsáideann an córas rialú dóchasach agus leases chun cosc a chur ar dhá ghlao chomhuaineacha an rún céanna a údarú nó a athrú.

Cóid earráide choitianta

HTTP	Cód	Cúis	Gníomh molta
`400`	`idempotency_key_required`	Tá an ceanntásc `Idempotency-Key` ar iarraidh nó san fhormáid mhícheart.	Gin eochair bhailí le 16 go 128 carachtar infheicthe ASCII, gan spásanna.
`409`	`idempotency_conflict`	Athúsáideadh an eochair le sonraí íocaíochta difriúla.	Gin eochair nua d’íocaíochtaí difriúla nó athúsáid an corp céanna go beacht.
`409`	`payment_mode_mismatch`	Ní mheaitseálann `expected_mode` mód na timpeallachta atá á glaoch agat.	Seiceáil an bhfuil tú ag díriú ar sandbox nó ar tháirgeadh; is é an t-imscaradh a shocraíonn an mód, ní an glao.
`401`	`invalid_api_key`	Tá an ceanntásc `X-API-Key` ar iarraidh, san fhormáid mhícheart, nó níl an dintiúr ann nó tá sé neamhghníomhach.	Seiceáil an dintiúr. Ná cuir sa frontend é riamh.
`403`	`payments_not_allowed`	Níl an táirge `PAYMENTS` cumasaithe don eochair API.	Déan teagmháil le tacaíocht Wealth Reader chun íocaíochtaí a chumasú ar do chuntas.
`403`	`payment_profile_not_allowed`	Níl an phróifíl bhainistithe cumasaithe do do chuideachta.	Iarr ar Wealth Reader an phróifíl a chlárú.
`429`	`api_limit_reached`	Tá cuóta carnach glaonna an dintiúir ídithe.	Ní réitítear é trí thriail eile ná trí fanacht: níl aon fhuinneog ama ná athlíonadh uathoibríoch ann. Iarr méadú ar an teorainn.
`415`	`json_required`	Tá an ceanntásc `Content-Type: application/json` ar iarraidh.	Seol corp an iarratais mar JSON.
`422`	`invalid_request`	Tá réimse riachtanach ar iarraidh nó seoladh réimse anaithnid.	Seiceáil an tábla paraiméadar: leanann an corp liosta ceadaithe docht.
`422`	`invalid_institution`	Níl an institiúid roghnaithe ar fáil nó níl sí bailí.	Féach `GET /payments/entities/` chun cóid bhailí a fháil.
`422`	`invalid_amount`	Tá an méid faoi bhun an íosmhéid (€0.01) nó ní slánuimhir é.	Seiceáil go seolann tú slánuimhir i gceinteanna (`amount_minor`).

An chéad chéim eile

Lean ar aghaidh le Stádais, seiceáil thréimhsiúil agus réiteach íocaíochtaí.

Nuashonraithe 2026-09-10

Paraiméadair chruthaithe (POST /payments/?action=create)