Arquitectura pensada para operar dinero de terceros.
Un core modular sobre un modelo de datos común, contratos explícitos hacia afuera y hacia la capa de adaptación local, y controles que hacen parte del flujo. Lo que sigue es cómo está construida la plataforma.
Arquitectura
Integra se organiza en módulos que comparten un modelo de datos y un bus de eventos. Cada módulo expone su API y sus eventos; la capa de adaptación local se conecta a través de contratos definidos y no toca el core.
| Core | Modelo de datos común: clientes, cuentas, operaciones, transacciones, archivos, periodos de conciliación. |
|---|---|
| Módulos | Servicios por dominio con su propia API y su catálogo de eventos, sobre el mismo modelo. |
| Bus de eventos | Cada cambio de estado se publica una vez y lo consumen la interfaz, los webhooks y los adaptadores. |
| Integration points | Contratos hacia los adaptadores del PSP: envío, consulta de estado, importación de extractos. |
| Interfaz | Aplicación web de operación y administración sobre las mismas APIs. |
| Despliegue | Ambientes de pruebas y producción separados; configuración por ambiente. |
APIs
REST sobre HTTPS con JSON. Un modelo consistente en toda la plataforma.
| Autenticación | Claves de API por ambiente con alcances (lectura, escritura, administración). Rotación sin interrupción. |
|---|---|
| Idempotencia | Cabecera Idempotency-Key en toda operación de escritura. Reintentar nunca duplica. |
| Estados | received → validated → processing → confirmed | rejected | returned. Los mismos para operaciones y transacciones. |
| Errores | Código, mensaje y detalle por campo. Errores de validación antes de mover cualquier recurso. |
| Paginación | Por cursor, con filtros por fecha, estado, cliente y referencia. |
| Versionado | Versión en la ruta (/v1). Cambios incompatibles solo en versiones nuevas, con convivencia. |
POST /v1/operations
Authorization: Bearer sk_test_••••••••
Idempotency-Key: cust-7781-payroll-2026-09
{
"customer_id": "cus_01J9K2",
"type": "payout",
"currency": "COP",
"items": [
{ "beneficiary": { "id_type": "CC", "id": "1020304050" },
"destination": { "rail": "psp-local:bank-transfer", "account": "4581••••••" },
"amount": 1850000, "reference": "Servicios septiembre" }
],
"workflow": "two-step-approval"
}{
"id": "op_01J9K3Q8X2",
"state": "received",
"workflow": { "name": "two-step-approval", "step": "validation" },
"items": { "total": 1, "valid": 0, "rejected": 0 },
"created_at": "2026-09-15T14:02:11-05:00"
}Webhooks
Eventos firmados con HMAC y marca de tiempo, entregados con reintentos y registro. El PSP y sus clientes se suscriben por tipo de evento.
| Firma | Cabecera X-Integra-Signature con marca de tiempo y HMAC sobre el cuerpo. |
|---|---|
| Entrega | Reintentos con espera creciente ante respuestas distintas de 2xx; cada intento queda registrado. |
| Orden | Identificador único y marca de tiempo por evento; los consumidores se diseñan idempotentes. |
| Reenvío | Desde la interfaz o por API. |
POST https://psp.example/webhooks/integra
X-Integra-Signature: t=1758037331,v1=6d1f…
{
"id": "evt_01J9K5",
"type": "transaction.confirmed",
"data": {
"transaction_id": "txn_01J9K4",
"operation_id": "op_01J9K3Q8X2",
"rail": "psp-local:bank-transfer",
"rail_reference": "…",
"amount": 1850000, "currency": "COP"
}
}Seguridad
Cifrado
TLS en tránsito; cifrado en reposo de credenciales, datos de cuentas y datos personales.
Acceso
Permisos por rol y por acción; segregación de funciones; autenticación reforzada en la interfaz.
Credenciales
Claves con alcances por ambiente e integración; rotación sin interrupción.
Integridad
Idempotencia, validación por registro y eventos firmados.
Auditoría
Registro inmutable de acciones humanas y de sistema con antes y después.
Datos
Datos de beneficiarios tratados solo para ejecutar la instrucción que los originó.
Escalabilidad
La plataforma procesa por evento y por lote. Las colas absorben picos, la validación por registro aísla errores y el procesamiento asíncrono mantiene la API rápida mientras la ejecución avanza.
- Validación por registro: un rechazo no detiene el lote.
- Procesamiento asíncrono: la API responde de inmediato; la ejecución y la confirmación llegan por evento.
- Consultas por cursor para reconciliar grandes volúmenes sin descargar todo.
- Límites y ventanas configurables por cliente, por riel y por ambiente.
Integration Framework
El punto donde la plataforma termina y la conectividad local del PSP empieza. Contratos pequeños y explícitos para enviar instrucciones, consultar estados e importar extractos; todo lo específico del riel vive en el adaptador del PSP.
Observabilidad
- Estados consultables por interfaz y por API para cada operación, transacción, archivo y periodo.
- Registro de entregas de webhooks y de llamadas a adaptadores, con reintentos visibles.
- Métricas operativas: volúmenes, tiempos por etapa, rechazos por causa, diferencias abiertas.
- Alertas configurables por umbral (por ejemplo, rechazos por encima de lo esperado en un riel).
No publicamos certificaciones, cifras de disponibilidad ni volúmenes que no podamos sostener con evidencia. Los parámetros aplicables a cada PSP se definen por escrito antes de producción.
Construye y opera tu PSP sobre Integra.
Cuéntanos qué operas hoy y qué rieles necesitas conectar. Te mostramos la plataforma sobre tu caso.