Equipos Propios
Conecta tus equipos y sistemas mediante integración SOAP
Integra tus propias aplicaciones de punto de venta y equipos compatibles con los servicios de pago presencial de OEL mediante SOAP. Conoce la arquitectura de comunicación, los mecanismos de autenticación, las operaciones disponibles y los requisitos necesarios para construir una integración segura y confiable.
Consultar métodos SOAP Ver ambientes de integración
¿Qué es la integración SOAP con equipos propios?
Esta modalidad permite que un sistema de punto de venta, una aplicación comercial o una solución de hardware compatible consuma directamente los servicios SOAP de OpGateway para procesar operaciones de pago presencial.
A diferencia de la integración mediante SDK Android, esta alternativa está dirigida a desarrolladores que necesitan implementar su propio cliente de servicios web y controlar la comunicación entre su aplicación y el Gateway.
El integrador es responsable de implementar correctamente las solicitudes, gestionar las respuestas, controlar los errores y respetar los requisitos de seguridad y compatibilidad establecidos para la solución.
¿Cuándo debes utilizar esta modalidad?
Esta integración puede ser adecuada cuando:
Dispones de una aplicación POS desarrollada internamente.
Necesitas integrar pagos en una solución de software existente.
Tu arquitectura requiere consumir servicios SOAP.
Cuentas con equipos compatibles con los requisitos de procesamiento de Tarjeta Presente.
Necesitas controlar directamente el flujo de comunicación entre tu sistema y OpGateway.
Importante: disponer de un equipo propio no garantiza su compatibilidad con la plataforma. La captura de datos de tarjeta, los mecanismos de protección, el firmware y los requisitos de certificación deben cumplir las condiciones aplicables a la solución.
Arquitectura de integración
Una integración SOAP conecta tu sistema comercial con los servicios de OpGateway a través de solicitudes y respuestas estructuradas en XML.
El flujo general es el siguiente:
Sistema del comercio. Genera la operación de venta y prepara los datos requeridos.
Equipo o componente de pago. Gestiona la captura del medio de pago mediante los mecanismos autorizados para la integración.
Cliente SOAP. Construye la solicitud y la envía al servicio correspondiente.
OpGateway. Valida la solicitud y gestiona el procesamiento de la operación.
Respuesta del servicio. Devuelve el resultado y los datos disponibles de la transacción.
Sistema del comercio. Interpreta la respuesta, actualiza el estado de la venta y registra la información necesaria para su seguimiento.
La implementación concreta depende del equipo, del software del comercio y de las operaciones habilitadas.
Requisitos previos
Antes de comenzar, asegúrate de contar con los siguientes elementos.
Requisitos técnicos
Un sistema o aplicación capaz de consumir servicios web SOAP.
Un equipo compatible con la integración de pagos presenciales.
Acceso al contrato del servicio, WSDL y documentación técnica vigente.
Credenciales de desarrollo autorizadas.
Endpoint correspondiente al ambiente de pruebas.
Conocimiento de los métodos y parámetros que utilizará tu implementación.
Una estrategia para registrar las operaciones y gestionar los errores.
Información que debes solicitar o confirmar
Elemento | Propósito |
|---|---|
Endpoint SOAP | Dirección del servicio al que se enviarán las solicitudes. |
WSDL | Contrato que define operaciones, parámetros y estructuras de respuesta. |
| Credenciales de autenticación utilizadas en la cabecera SOAP. |
| Identificador del comercio asociado a la operación. |
| Credencial del comercio requerida por el método correspondiente. |
Configuración del ambiente | Parámetros necesarios para operar en desarrollo o producción. |
Métodos habilitados | Operaciones disponibles para el comercio y la integración. |
La necesidad y ubicación exacta de cada parámetro dependen del contrato del servicio y del método invocado.
Comunicación con OpGateway
La integración utiliza servicios SOAP sobre HTTPS. La especificación técnica de OpGateway contempla SOAP 1.1/1.2 y comunicación segura mediante TLS 1.2 o superior.
¿Qué es SOAP?
SOAP es un protocolo de mensajería que permite intercambiar información estructurada en XML entre sistemas.
En esta integración, tu aplicación construye una solicitud conforme al contrato del servicio, la envía al endpoint correspondiente y procesa la respuesta recibida.
¿Qué es el WSDL?
El WSDL describe la interfaz del servicio web, incluyendo sus operaciones, parámetros, tipos de datos y estructuras de mensajes.
Antes de implementar un método, consulta el WSDL correspondiente para conocer:
El nombre exacto de la operación.
Los parámetros obligatorios y opcionales.
Los tipos de datos esperados.
La estructura de la respuesta.
Los namespaces XML.
Las excepciones y los errores definidos por el servicio.
No construyas las solicitudes únicamente a partir de ejemplos aislados: el contrato vigente es la referencia para implementar correctamente el cliente SOAP.
Autenticación de las solicitudes
Las llamadas a los servicios SOAP de OpGateway requieren la autenticación definida para la integración.
Cabecera SOAP
La especificación contempla el uso de OpHeader con los campos OpKey1 y OpKey2 para la autenticación del servicio.
Además, las operaciones que lo requieren utilizan las credenciales asociadas al comercio, como comercioId y contrasena.
Debes distinguir entre las credenciales utilizadas para autenticar la llamada al servicio y los datos requeridos para identificar al comercio en una operación específica.
Recomendaciones de implementación
Utiliza exclusivamente las credenciales entregadas para tu ambiente.
Protege los secretos fuera del código fuente.
Evita registrar cabeceras de autenticación en logs.
No compartas credenciales entre ambientes.
Verifica la estructura de autenticación definida en el WSDL y en la documentación vigente.
Gestiona los errores de autenticación sin revelar información sensible al usuario final.
Operaciones disponibles
OpGateway contempla métodos para procesar pagos presenciales y administrar el ciclo de vida de las transacciones. La disponibilidad y las condiciones de uso deben verificarse en la referencia técnica de cada método.
1. Operaciones de venta y autorización
Venta — OpVenta
Permite solicitar el procesamiento de una operación de venta.
Preautorización — OpPreAutorizacion
Permite solicitar una autorización previa cuando el servicio y la configuración del comercio admiten este flujo.
Postautorización — OpPostAutorizacion
Permite completar una operación previamente preautorizada, de acuerdo con las reglas del servicio.
2. Operaciones posteriores
Cancelación — OpCancelacion
Solicita la cancelación de una operación cuando cumple las condiciones establecidas.
Devolución — OpDevolucion
Solicita la devolución de una transacción previamente procesada, conforme a las reglas aplicables.
Reversa — OpReversa
Permite gestionar una reversa de acuerdo con el flujo de procesamiento correspondiente.
Importante: La cancelación, la devolución y la reversa no deben tratarse como operaciones equivalentes. Implementa cada una conforme a sus condiciones y efectos específicos.
3. Consultas y servicios complementarios
Entre los métodos identificados en la documentación se encuentran:
OpObtenerVenta: consulta información de una venta.OpTransacciones: consulta información de transacciones.OpCortesDiarios: consulta información de cortes diarios.OpVersion: consulta información de la versión del servicio.enviaVoucher: gestiona el envío de información de voucher via correo electrónico.enviaVoucherImagen: genera y envía una imágen con la información del voucher.
Consulta la referencia técnica para conocer los parámetros, las restricciones y las respuestas de cada operación.
Flujo de una transacción
Una integración robusta debe contemplar el proceso completo, desde la preparación de la solicitud hasta el registro del resultado.
Paso 1. Preparar la operación
Genera un identificador único para la venta y valida los datos comerciales requeridos por el método.
Verifica los parámetros obligatorios, el monto y la configuración del comercio antes de enviar la solicitud.
Paso 2. Construir la solicitud SOAP
Genera el mensaje XML conforme al WSDL, incluyendo la cabecera de autenticación y los parámetros específicos de la operación.
No reutilices estructuras de otros métodos sin verificar que correspondan al contrato de la operación que deseas ejecutar.
Paso 3. Enviar la solicitud
Envía el mensaje al endpoint del ambiente correspondiente mediante HTTPS.
Configura tiempos de espera razonables y gestiona adecuadamente los errores de transporte, autenticación y validación.
Paso 4. Interpretar la respuesta
Procesa la respuesta SOAP y valida los campos que determinan el resultado de la operación.
Distingue entre una aprobación, un rechazo, un error técnico y una situación en la que no es posible determinar inmediatamente el resultado.
Paso 5. Registrar el resultado
Relaciona la respuesta con la venta original y conserva la información operativa necesaria para seguimiento, atención de incidencias y conciliación.
Paso 6. Resolver situaciones excepcionales
Si se interrumpe la comunicación o no se recibe una respuesta concluyente, determina el estado de la operación mediante los mecanismos de consulta disponibles antes de intentar nuevamente el cobro.
Parámetros y respuestas
Cada método cuenta con su propia estructura de solicitud y respuesta. Debes consultar el contrato correspondiente para conocer los nombres exactos, tipos y restricciones de sus campos.
Datos de la solicitud
Según la operación, el mensaje puede requerir información como:
Identificador del comercio.
Credenciales o parámetros de autenticación.
Identificador de la transacción.
Monto de la operación.
Referencia comercial.
Datos específicos del flujo de pago.
Parámetros adicionales definidos por el método.
Datos de la respuesta
Dependiendo del método, la respuesta puede incluir información como:
codigoRespuesta.codigoAprobacion.transaccionId.Referencia bancaria.
Monto procesado.
Mensajes descriptivos.
Identificadores de seguimiento.
Los campos disponibles y su significado deben validarse contra el contrato de cada operación.
Importante: una respuesta HTTP exitosa no significa necesariamente que el pago haya sido aprobado. Tu aplicación debe interpretar el resultado de negocio devuelto por el servicio.
Seguridad en Tarjeta Presente
La seguridad es una parte fundamental de cualquier integración de pagos presenciales.
Protección de los datos de tarjeta
Los datos sensibles de tarjeta deben gestionarse exclusivamente mediante los mecanismos autorizados para la solución.
En el flujo transaccional de Tarjeta Presente, datos como PAN, Track 2 y EMV Tags se consideran volátiles: no deben almacenarse y solo deben mantenerse durante el procesamiento cuando resulte necesario y esté autorizado.
No registres estos datos en archivos de diagnóstico, bases de datos comerciales, mensajes de error ni sistemas de monitoreo.
Comunicación segura
Utiliza HTTPS y los requisitos de TLS establecidos para el servicio.
Valida los certificados del servidor.
No deshabilites la validación TLS para resolver errores de conexión.
Protege las credenciales de autenticación.
Evita exponer datos sensibles en las solicitudes registradas.
Cumple los requisitos de cifrado, captura y certificación aplicables al dispositivo.
Trazabilidad operativa
Registra la información necesaria para dar seguimiento a las operaciones, como identificadores de transacción, fechas, montos y códigos de resultado, siempre que su almacenamiento esté permitido.
La trazabilidad debe permitir investigar incidencias sin exponer datos sensibles de pago.
Manejo de errores
Durante la integración pueden presentarse errores de comunicación, autenticación, validación o procesamiento.
Escenario | Acción recomendada |
|---|---|
Error de autenticación | Verificar las credenciales y el ambiente. |
Error de estructura SOAP | Validar el XML y contrastarlo con el WSDL. |
Parámetro inválido | Revisar los campos obligatorios, tipos y restricciones. |
Método no habilitado | Confirmar las capacidades autorizadas para el comercio. |
Timeout | Consultar el estado de la operación antes de reintentar. |
Respuesta SOAP inesperada | Registrar el incidente sin asumir una aprobación. |
Error de comunicación TLS | Revisar certificados, configuración y requisitos de conexión. |
Operación rechazada | Interpretar el código y mensaje conforme a la documentación oficial. |
Evita duplicar cobros
Un timeout o una interrupción de comunicación no demuestra que la operación haya fallado.
Implementa un procedimiento de recuperación que permita determinar el estado de la transacción antes de volver a enviarla. Utiliza identificadores únicos y los mecanismos de consulta disponibles para reducir el riesgo de cargos duplicados.
Pruebas de integración
Antes de solicitar la habilitación productiva, valida los escenarios correspondientes a tu implementación.
Checklist técnico
El WSDL corresponde al servicio y ambiente correctos.
La conexión HTTPS funciona correctamente.
La autenticación SOAP está configurada.
Los métodos utilizados están habilitados.
Los mensajes XML cumplen el contrato del servicio.
Se valida una operación aprobada.
Se manejan operaciones rechazadas.
Se prueban errores de autenticación y validación.
Se contemplan timeouts y respuestas indeterminadas.
Se valida el comportamiento de cancelaciones y devoluciones, cuando estén habilitadas.
Se verifica la trazabilidad de las operaciones.
No se almacenan datos sensibles de tarjeta.
Se han completado los requisitos de certificación aplicables.
Paso a producción
Antes de utilizar la integración en operaciones reales, confirma que:
El comercio y los equipos están habilitados.
Se completaron las pruebas requeridas.
Las credenciales productivas fueron entregadas y verificadas.
El endpoint y la configuración corresponden al ambiente productivo.
Los mecanismos de recuperación y seguimiento están implementados.
Se cumplen los requisitos de seguridad y certificación.
Existe un procedimiento para atender incidencias y conciliar las operaciones.
No utilices credenciales productivas durante el desarrollo inicial.
Preguntas frecuentes
¿Puedo integrar cualquier terminal mediante SOAP?
No necesariamente. El equipo debe cumplir los requisitos de compatibilidad, captura, seguridad y certificación aplicables a la solución.
¿Necesito utilizar el SDK Android?
No para esta modalidad. La integración SOAP permite consumir directamente los servicios documentados desde un cliente compatible, siempre que se cumplan los requisitos de hardware y procesamiento.
¿Dónde consulto los parámetros exactos de cada método?
En el WSDL y en la referencia técnica del servicio. Estos recursos definen la estructura y los parámetros que debe utilizar tu implementación.
¿Qué debo hacer si no recibo una respuesta?
No asumas que el pago fue rechazado. Utiliza los mecanismos de consulta o recuperación disponibles para determinar su estado antes de iniciar una nueva operación.
¿Puedo usar las mismas credenciales en desarrollo y producción?
No. Utiliza las credenciales y los endpoints asignados a cada ambiente.
Recursos para desarrolladores
Referencia de métodos SOAP
Consulta las operaciones, sus parámetros y sus estructuras de respuesta.
Ambiente de desarrollo
Revisa la configuración y las credenciales necesarias para realizar pruebas.
SDK Android
Conoce la alternativa de integración para aplicaciones Android y dispositivos compatibles.
Terminales compatibles
Consulta los requisitos técnicos de los equipos admitidos.