Pagos

Intenciones de pago e idempotencia

Una intención de pago fija de forma inmutable los términos económicos de la transacción antes de que el usuario interactúe con el widget. Esto impide que un cliente malicioso manipule en el frontend el importe, la cuenta de destino o el concepto de la transferencia.

Parámetros de creación (`POST /payments/?action=create`)

1. Modelo estándar para comercios (Propio beneficiario)

En este modelo, el comercio define todos los datos de cobro:

Campo	Tipo	Obligatorio	Descripción y reglas
`amount_minor`	Entero	Sí	Importe en unidades menores (céntimos). Por ejemplo, `1500` representa `15,00 EUR`.
`currency`	Cadena	Sí	Código de divisa ISO 4217 de 3 letras. Actualmente `EUR`.
`beneficiary`	Objeto	Sí	Datos de la cuenta de destino: `name` (titular, 1 a 140 car.) e `iban` (IBAN válido sin espacios, con dígito de control comprobado). Solo admite esas dos claves.
`reference`	Cadena	Sí	Concepto visible en el extracto bancario (máx. 140 caracteres).
`customer_reference`	Cadena	Sí	Identificador interno de su pedido o cliente (1 a 128 car.: letras, números, `.`, `_`, `:`, `-`; debe empezar por letra o número).
`allowed_origin`	Cadena	Sí	Origen HTTPS exacto que incrustará el widget (ej. `https://tienda.example.com`), sin ruta.
`allowed_institution_codes`	Array	No	Lista de códigos de entidades permitidas (ej. `["santander-es", "bbva-es"]`). Si se omite, se permite cualquier entidad del catálogo.
`locale`	Cadena	No	Idioma de la interfaz del widget. En esta versión solo se acepta `es`; cualquier otro valor devuelve `422 invalid_locale`.
`expected_mode`	Cadena	No	`mock` o `live`. Comprueba que está llamando al entorno que cree; no cambia de entorno. Si no coincide, `409 payment_mode_mismatch`.

El cuerpo es una lista blanca estricta: enviar un campo que no esté en esta tabla devuelve 422 invalid_request, igual que omitir uno obligatorio. La cabecera Content-Type: application/json es obligatoria (415 json_required) y el cuerpo está acotado a 32 KB.

2. Modelo con perfil administrado (Donativos / Demos)

Para casos regulados o demostraciones públicas como cruz_roja_demo, el servidor impone las reglas financieras y fija las cuentas oficiales de destino:

Campo	Tipo	Obligatorio	Descripción y reglas
`profile`	Cadena	Sí	Identificador del perfil (ej. `cruz_roja_demo`).
`institution_code`	Cadena	Sí	Código de la entidad seleccionada por el usuario (procedente de `profile-institutions`).
`amount_minor`	Entero	Sí	Importe acotado por las políticas del perfil (ej. de 1 a 100 céntimos).
`customer_reference`	Cadena	Sí	Referencia de auditoría propia de su sistema.
`allowed_origin`	Cadena	Sí	Origen HTTPS del widget.
`locale`	Cadena	No	Idioma del widget (`es`).
`expected_mode`	Cadena	No	Modo esperado (`mock` o `live`).

Cuando se especifica profile, el servidor asigna automáticamente el beneficiario oficial y el concepto correspondiente. No envíe beneficiary ni reference en solicitudes con perfil administrado.

Regla de `Idempotency-Key`

La cabecera Idempotency-Key es obligatoria en toda llamada de creación. Debe contener entre 16 y 128 caracteres ASCII visibles, sin espacios (por ejemplo, un UUID v4). Su alcance es exclusivo de la empresa autenticada:

Misma clave y mismo cuerpo: devuelve la intención original creada previamente junto con idempotent_replay: true. No se genera un nuevo cobro ni se duplica la orden bancaria.
Misma clave y cuerpo distinto: responde inmediatamente con HTTP 409 Conflict.
Misma clave en otra empresa: pertenece a otro espacio de idempotencia completamente aislado.

Si una llamada de creación sufre un corte de red o timeout, reintente con exactamente la misma cabecera Idempotency-Key y el mismo cuerpo. No genere una nueva clave ante un error transitorio.

Persistencia y ciclo de vida

Persistencia previa: La intención queda registrada en base de datos antes de devolver la respuesta o interactuar con cualquier conector bancario.
Token efímero de widget: El token de la respuesta (payment.widget.token) tiene una validez temporal corta (habitualmente 15 a 30 minutos) y solo puede utilizarse desde el allowed_origin declarado.
Bloqueo de concurrencia: El sistema implementa control optimista y leases para impedir que dos llamadas simultáneas autoricen o modifiquen la misma intención.

Códigos de error frecuentes

HTTP	Código	Causa	Acción recomendada
`400`	`idempotency_key_required`	Falta la cabecera `Idempotency-Key` o su formato es incorrecto.	Genere una clave válida de entre 16 y 128 caracteres ASCII visibles, sin espacios.
`409`	`idempotency_conflict`	Se ha reutilizado la clave con datos de pago distintos.	Genere una nueva clave para pagos distintos o reutilice el cuerpo idéntico.
`409`	`payment_mode_mismatch`	`expected_mode` no coincide con el modo del entorno al que está llamando.	Compruebe si está apuntando al sandbox o a producción; el modo lo fija el despliegue, no la llamada.
`401`	`invalid_api_key`	Falta la cabecera `X-API-Key`, su formato no es válido, o la credencial no existe o está inactiva.	Revise la credencial. Nunca la incluya en el frontend.
`403`	`payments_not_allowed`	La API key no tiene el producto `PAYMENTS` habilitado.	Contacte con soporte de Wealth Reader para activar pagos en su cuenta.
`403`	`payment_profile_not_allowed`	El perfil administrado no está habilitado para su empresa.	Solicite el alta del perfil a Wealth Reader.
`429`	`api_limit_reached`	Su credencial ha agotado el contador acumulado de llamadas.	No se resuelve reintentando ni esperando: no hay ventana ni reposición automática. Solicite ampliar el límite.
`415`	`json_required`	Falta la cabecera `Content-Type: application/json`.	Envíe el cuerpo como JSON.
`422`	`invalid_request`	Falta un campo obligatorio o se ha enviado uno no reconocido.	Revise la tabla de parámetros: el cuerpo es una lista blanca estricta.
`422`	`invalid_institution`	La entidad seleccionada no está disponible o no es válida.	Consulte `GET /payments/entities/` para obtener códigos válidos.
`422`	`invalid_amount`	El importe es inferior al mínimo (0,01 €) o no es un entero.	Compruebe que envía un entero en céntimos (`amount_minor`).

Siguiente paso

Continúe con Estados, sondeo y conciliación.

Última actualización 2026-09-09

Parámetros de creación (POST /payments/?action=create)