Plataforma / Integration Framework
Integra proporciona la plataforma. El PSP adapta la conectividad local.
El integration framework es el conjunto de APIs, webhooks, interfaces, estructuras de datos, eventos y puntos abiertos con los que el PSP conecta Integra a la infraestructura financiera de su país. Es la parte de la plataforma diseñada para que el PSP la extienda.
Qué incluye el framework.
APIs
Acceso programático a todos los módulos, con el mismo modelo de identificadores, estados y errores.
Webhooks
Eventos firmados hacia los sistemas del PSP y de sus clientes, y hacia la capa de adaptación local.
Integration points
Contratos definidos donde la plataforma entrega una operación aprobada y espera un resultado: el lugar donde vive cada adaptador de riel.
Interfaces
Pantallas de operación que muestran el estado reportado por los adaptadores, sin desarrollo adicional.
Estructuras de datos
Instrucción, beneficiario, cuenta, resultado, extracto: tipos comunes que el adaptador traduce al formato del riel.
Eventos
Catálogo de eventos de ciclo de vida que el adaptador consume y produce.
Mecanismos de comunicación
Llamadas síncronas para envío y consulta; entrega asíncrona de resultados; importación de archivos y extractos.
Documentación
Referencia de contratos, guías de adaptación y ambiente de pruebas para el equipo del PSP.
El recorrido de una operación a través del framework.
Instrucción
Un cliente del PSP crea una operación por interfaz, archivo o API. Integra la valida y la lleva por el workflow configurado.
Punto de integración
Aprobada la operación, Integra la entrega al adaptador del riel indicado con la estructura de datos común.
Adaptación local
El adaptador, construido por el PSP, traduce la instrucción al formato del banco, red o proveedor y la envía por el canal que corresponda.
Resultado
El adaptador reporta el resultado (referencia, confirmación, rechazo, devolución). Integra actualiza la transacción y emite el evento.
Conciliación
El adaptador importa extractos o reportes del proveedor; Integra concilia contra lo ejecutado y expone diferencias.
El contrato de un adaptador.
Un adaptador implementa un contrato pequeño y explícito. Todo lo que es específico del riel (autenticación, formatos, códigos de respuesta, ventanas, archivos) vive dentro del adaptador y pertenece al PSP.
- Enviar una instrucción y recibir un acuse.
- Consultar el estado de una referencia.
- Importar un extracto o reporte para conciliación.
- Declarar capacidades: monedas, horarios, límites, tipos de cuenta.
// Lo que el PSP implementa para conectar un riel de su mercado.
// Conceptual: nombres y firmas se entregan en la documentación.
interface RailAdapter {
readonly id: "psp-local:bank-transfer";
submit(tx: TransactionInstruction): Promise<Acknowledgement>;
status(ref: RailReference): Promise<RailState>;
importStatement(file: Statement): Promise<StatementLines>;
}
// Integra llama a submit() cuando la operación queda aprobada
// y actualiza la transacción con lo que el adaptador reporta.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"
}
}Qué significa "adaptación local".
La adaptación local es el trabajo del PSP: desarrollar o adaptar la conexión con las entidades de su mercado y mantenerla. Integra no la realiza y no afirma conectividad con ningún riel específico salvo que exista una integración desarrollada y confirmada.
Bancos
Redes y sistemas de pago
Cámaras de compensación
Proveedores financieros
Sistemas nacionales
Infraestructura local
Extensibilidad más allá de los rieles.
Workflows
Reglas de validación y aprobación por tipo de operación y por cliente.
Layouts de archivo
Formatos de entrada y de respuesta definidos por cliente.
Reglas de conciliación
Criterios de coincidencia y tolerancias por cuenta y por proveedor.
Catálogo de eventos
Suscripciones y destinos por tipo de evento, cliente y ambiente.
Campos y metadatos
Atributos adicionales en clientes, operaciones y transacciones para el negocio del PSP.
Construye y opera tu PSP sobre Integra.
Cuéntanos qué operas hoy y qué rieles necesitas conectar. Te mostramos la plataforma sobre tu caso.