Crea una nueva transacción para enviar fondos a un beneficiario.
El cuerpo del request debe estar encriptado.
Importante: Asegúrate de que la billetera de tu empresa tenga saldo suficiente antes de iniciar una transacción.
Características principales
- Creación automática de beneficiario: Proporciona un objeto
beneficiary_datacompleto. La API buscará automáticamente un beneficiario existente que coincida con eldocument_numbery elbreb_key, o creará uno nuevo si no encuentra coincidencia. - Aprobación automática: Al crear una transacción usando una API Key, esta se marca automáticamente como
approved. - Transacciones Bre-b: Para transferir fondos a través de Bre-b, proporciona el valor de la llave Bre-b en el campo
breb_key.
Validación síncrona para Bre-b
Si estás creando una transacción hacia un nuevo beneficiario Bre-b, el sistema validará la existencia de la llave de forma síncrona antes de crear la transacción. Si la llave es inválida o la red bancaria no está disponible, el request fallará de inmediato con un 400 Bad Request y un status_code específico.
Ciclo de estados de la transacción
| Estado | Descripción |
|---|---|
created | La transacción fue creada pero aún no aprobada (creación estándar por UI) |
approved | En espera de procesamiento (al usar API Key se aprueba automáticamente) |
processing | La transacción está siendo ejecutada |
done | La transacción se completó exitosamente |
fail | La transacción falló y los fondos fueron reembolsados |
cancelled | La transacción fue cancelada antes del procesamiento y los fondos fueron reembolsados |
compliance_cancelled | La transacción fue cancelada por cumplimiento normativo |
Headers
| Header | Tipo | Requerido | Descripción |
|---|---|---|---|
X-API-KEY | password | ✅ Sí | Tu llave de API |
Content-Type | string | ✅ Sí | application/json |
Cuerpo del request (Body)
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
amount | string | ✅ Sí | Monto de la transacción (no vacío, máx. 1000 caracteres) |
idempotency_key | string (UUID) | ✅ Sí | Llave única para evitar solicitudes duplicadas. Se recomienda UUID v4 |
timestamp | string (ISO8601) | ✅ Sí | Fecha y hora UTC en que se creó el request |
beneficiary_data | object | ✅ Sí | Datos del beneficiario (ver detalle abajo) |
beneficiary_data.name | string | ✅ Sí | Nombre completo del beneficiario |
beneficiary_data.document_number | string | ✅ Sí | Número de documento del beneficiario |
beneficiary_data.document_type | integer | ✅ Sí | ID del tipo de documento del beneficiario |
beneficiary_data.breb_key | string | ✅ Sí | Valor de la llave Bre-b del beneficiario |
Respuestas
✅ 201 — Transacción creada
{
"id": "uuid-de-la-transaccion",
"amount": "150000",
"status": "approved",
"created_date": "2024-07-29T15:51:28.071Z",
"started_date": null,
"finished_date": null,
"beneficiary_data": {},
}
| Campo | Tipo | Descripción |
|---|---|---|
id | string (UUID) | ID único de la transacción |
amount | string | Monto de la transacción |
status | string | Estado actual de la transacción |
created_date | string (datetime) | Fecha de creación |
started_date | string (datetime) / null | Fecha de inicio del procesamiento |
finished_date | string (datetime) / null | Fecha de finalización |
beneficiary_data | object | Datos del beneficiario enviados en el request |
❌ 400 — Error de validación
El request contiene datos inválidos o la llave Bre-b no pudo ser validada. La respuesta incluirá un campo status_code indicando el problema.
❌ 403 — Prohibido
No tienes permisos para acceder a este recurso.