Pagaments

Intencions de pagament i idempotència

Una intenció de pagament estableix de manera immutable els termes econòmics de la transacció abans que l'usuari interactuï amb el widget. Això evita que un client maliciós manipuli l'import, el compte de destinació o el concepte de transferència al frontend.

Paràmetres de creació (`POST /payments/?action=create`)

1. Model estàndard per a comerciants (beneficiari propi)

En aquest model, el comerciant defineix totes les dades de cobrament:

Camp	Tipus	Obligatori	Descripció i normes
`amount_minor`	Enter	Sí	Quantitat en unitats més petites (cèntims). Per exemple, `1500` representa `15,00 EUR`.
`currency`	Cadena	Sí	Codi de moneda ISO 4217 de 3 lletres. Actualment `EUR`.
`beneficiary`	Objecte	Sí	Dades del compte de destinació: `name` (propietari, d'1 a 140 caràcters de text) i `iban` (IBAN vàlida sense espais, amb xifre de control marcat). Només admet aquestes dues claus.
`reference`	Cadena	Sí	Concepte visible a l'extracte bancari (màxim 140 caràcters de text).
`customer_reference`	Cadena	Sí	Identificador intern de la teva comanda o client (1 a 128 caràcters de text: lletres, números, `.`, `_`, `:`, `-`; ha de començar per una lletra o un número).
`allowed_origin`	Cadena	Sí	Exactament HTTPS font que incrustarà el widget (per exemple, `https://tienda.example.com`), sense ruta.
`allowed_institution_codes`	Array	No	Llista de codis d'entitat permesos (per exemple, `["santander-es", "bbva-es"]`). Si s'omet, qualsevol entitat del catàleg està permesa.
`locale`	Cadena	No	El llenguatge de la interfície del widget. Només s'accepten `es`en aquesta versió; qualsevol altre valor retorna `422 invalid_locale`.
`expected_mode`	Cadena	No	`mock` o `live`. Comprova que estàs cridant l'entorn previst; no canvia d'entorn. Si no coincideix, `409 payment_mode_mismatch`.

El cos és una llista blanca estricta: enviar un camp que no apareix en aquesta taula retorna 422 invalid_request, igual que ometre'n un d'obligatori. La capçalera Content-Type: application/json és obligatòria (415 json_required) i el cos està limitat a 32 KB.

2. Model amb perfil gestionat (Donacions/Demos)

Per a casos regulats o demostracions públiques com cruz_roja_demo, el servidor imposa les regles financeres i estableix els comptes objectiu oficials:

Camp	Tipus	Obligatori	Descripció i normes
`profile`	Cadena	Sí	Identificador de perfil (per exemple, `cruz_roja_demo`).
`institution_code`	Cadena	Sí	Codi d'entitat seleccionat per l'usuari (de `profile-institutions`).
`amount_minor`	Enter	Sí	Quantitat limitada per les pòlisses del perfil (per exemple, d'1 a 100 cèntims).
`customer_reference`	Cadena	Sí	La referència d'auditoria del teu propi sistema.
`allowed_origin`	Cadena	Sí	Widget HTTPS font.
`locale`	Cadena	No	Llenguatge de widgets (`es`).
`expected_mode`	Cadena	No	Mode esperat (`mock` o `live`).

Quan s'especifica profile, el servidor assigna automàticament el beneficiari oficial i el concepte corresponent. No enviïs beneficiary ni reference a sol·licituds amb un perfil gestionat.

Regla de `Idempotency-Key`

La capçalera Idempotency-Key és requerida en cada crida de creació. Ha de contenir entre 16 i 128 caràcters de text ASCII visible, sense espais (per exemple, una UUID v4). El seu abast és únic per a l'empresa autenticada:

Mateixa clau i mateix cos: Retorna la intenció original creada prèviament juntament amb idempotent_replay: true. No es genera cap nou càrrec i l'ordre bancària no es duplica.
Mateixa clau i cos diferent: respon immediatament amb HTTP 409 Conflict.
La mateixa clau en una altra empresa: pertany a un altre espai completament aïllat d'idempotència.

Si una crida de creació pateix una interrupció o un timeout de xarxa, torna a intentar-ho amb la mateixa capçalera Idempotency-Key i el mateix cos. No generis una nova clau en cas de fallada transitòria.

Persistència i cicle de vida

Persistència prèvia: La intenció es registra a la base de dades abans de retornar la resposta o d'interactuar amb qualsevol connector bancari.
Token de widget efímer: El token de resposta (payment.widget.token) té una validesa de temps curt (normalment de 15 a 30 minuts) i només es pot utilitzar des del allowed_origin declarat.
Bloqueig de concurrència: El sistema implementa controls optimistes i lloguers per evitar que dues trucades simultànies autoritzin o modifiquin la mateixa intenció.

Codis d'error comuns

HTTP	Codi	Causa	Acció recomanada
`400`	`idempotency_key_required`	La capçalera `Idempotency-Key` falta o està mal formatada.	Genera una clau vàlida d'entre 16 i 128 caràcters de text ASCII visible, sense espais.
`409`	`idempotency_conflict`	La clau s'ha reutilitzat amb diferents detalls de pagament.	Genera una nova clau per a diferents pagaments o reutilitza el mateix cos.
`409`	`payment_mode_mismatch`	`expected_mode` no coincideix amb el mode de l'entorn que estàs cridant.	Comprova si el teu objectiu és el sandbox o la producció; el mode es configura pel desplegament, no per la trucada.
`401`	`invalid_api_key`	La capçalera `X-API-Key`falta, el seu format és invàlid o la clau d'accés no existeix o està inactiva.	Revisa el codi. No l'incloguis mai a la interfície.
`403`	`payments_not_allowed`	La clau API no té el producte `PAYMENTS` activat.	Contacta amb Wealth Reader suport per activar els pagaments al teu compte.
`403`	`payment_profile_not_allowed`	El perfil gestionat no està activat per a la teva empresa.	Sol·licita l’activació del perfil a Wealth Reader.
`429`	`api_limit_reached`	El teu codi d'accés ha esgotat el comptador de trucades acumulat.	No es resol tornant a intentar o esperant: no hi ha finestra ni reinici automàtic. Sol·licita ampliar el límit.
`415`	`json_required`	Falta el `Content-Type: application/json`de capçalera.	Envia el cos com JSON.
`422`	`invalid_request`	Falta un camp requerit o s'ha presentat un camp no reconegut.	Consulta la taula de paràmetres: el cos és una llista blanca estricta.
`422`	`invalid_institution`	L'entitat seleccionada no està disponible o és invàlida.	Consulteu `GET /payments/entities/` per a codis vàlids.
`422`	`invalid_amount`	L'import és inferior al mínim (€0,01) o no és un enter.	Verifica que estàs enviant un enter en cèntims (`amount_minor`).

Següent pas

Continua amb Estats, consultes periòdiques i conciliació.

Última actualització 2026-09-10

Paràmetres de creació (POST /payments/?action=create)