Pagos
Intenciones de pago e idempotencia
Una intención fija la orden antes de abrir el widget. En un perfil administrado, el cliente elige únicamente una institución publicada, el importe permitido, su referencia y el origen; Wealth Reader construye los datos económicos restantes.
Creación con el perfil de donativos
POST /payments/?action=create acepta para cruz_roja_demo:
| Campo | Regla |
|---|---|
profile |
Debe ser cruz_roja_demo. |
institution_code |
Debe proceder de profile-institutions. |
amount_minor |
Entero entre 1 y 100, ambos incluidos. |
customer_reference |
Letras, números, ., _, :, -; referencia propia del cliente. |
allowed_origin |
Origen HTTPS exacto que alojará el widget, sin ruta. |
locale |
Opcional; es es el valor predeterminado y revisado. |
expected_mode |
Opcional, pero recomendado: mock o live; una discrepancia se rechaza. |
currency |
Opcional; si se envía, debe ser EUR. |
No envíe beneficiary, reference ni una lista de instituciones: el perfil los fija en el servidor. La API rechaza propiedades desconocidas y cambios de política.
La creación genérica anterior se conserva para clientes autorizados que no están asignados a un perfil administrado. Una credencial asignada a cruz_roja_demo no puede omitir el perfil para eludir sus límites. No mezcle ambos esquemas en la misma solicitud.
Regla de Idempotency-Key
La cabecera es obligatoria y contiene entre 16 y 128 caracteres ASCII visibles, sin espacios. Su alcance es la empresa autenticada:
- Misma clave y mismo cuerpo canónico: devuelve la intención original y
idempotent_replay: true; no inicia otro pago. - Misma clave y cuerpo distinto: responde HTTP
409. - Misma clave en otra empresa: pertenece a otro espacio de idempotencia.
Conserve la misma clave cuando repita una creación cuya respuesta HTTP se perdió. No genere otra clave ante un timeout ambiguo.
Persistencia y autorización
La intención se guarda antes de cualquier llamada externa. La API también exige:
- credencial server-to-server de alta entropía con permiso de pagos; una clave heredada corta no es válida;
- acceso a la intención limitado a la empresa autenticada;
- token de widget breve, almacenado solo como hash y ligado al origen;
- política inmutable de perfil, versión e institución;
- control optimista y lease para serializar inicio, callback y consulta.
Si el inicio pudo haber llegado al banco y la respuesta es ambigua, la intención queda en conciliación y no se inicia automáticamente otra vez.
Errores relevantes
| HTTP | Situación | Acción |
|---|---|---|
400 |
Falta o formato inválido de Idempotency-Key. |
Corrija la cabecera antes de reintentar. |
409 |
La clave ya pertenece a otro cuerpo. | Recupere la orden original; no cambie el cuerpo. |
409 |
El modo esperado no coincide o la intención está ocupada. | Detenga la creación y consulte/configure el entorno. |
401 |
Token de widget vencido. | Consulte la intención existente desde su backend. |
403 |
Credencial o perfil sin permiso. | Solicite la autorización correspondiente. |
422 |
Institución, importe o esquema no válido. | Actualice la lista de instituciones y corrija la solicitud. |
503 |
Pagos o nuevas altas deshabilitados. | No intente una operación real hasta la activación. |
Siguiente paso
Implemente Estados y conciliación.