Inicio
Pagos Presenciales
Tokenización
Aliados
Ambientes
Referencia API
Recursos
Pagos Presenciales
Integración de pagos, autorizaciones y operaciones transaccionales
2
min read
2
2
min read
SOAP Gateway es el conjunto de servicios web que permite integrar aplicaciones y sistemas comerciales con el Gateway de Pagos de Operaciones en Línea (OEL), utilizando el protocolo SOAP.
A través de esta interfaz, los desarrolladores pueden procesar pagos con tarjeta, gestionar autorizaciones, realizar cancelaciones y devoluciones, consultar transacciones, obtener información para conciliación y ejecutar operaciones complementarias, como el almacenamiento de firmas autógrafas y el envío de comprobantes electrónicos.
Información general
Característica | Descripción |
|---|---|
Servicio |
|
Tipo de integración | API SOAP |
Protocolos disponibles | SOAP 1.1 y SOAP 1.2 |
Transporte | HTTPS |
Formato de mensajes | XML |
Estilo de comunicación |
|
Autenticación | Credenciales de comercio y encabezado SOAP |
Operaciones documentadas | 15 métodos |
Definición del contrato | WSDL |
Endpoint del servicio
Namespace
Cada operación dispone de su propia estructura de solicitud (Request) y respuesta (Response), definida en el contrato WSDL.
Métodos disponibles
Los 15 métodos documentados se organizan en cuatro grupos funcionales.
1. Procesamiento de pagos y autorizaciones
Estos métodos permiten iniciar operaciones financieras y gestionar autorizaciones previamente procesadas.
Método | Descripción | Condiciones y limitaciones operativas |
|---|---|---|
| Procesa una solicitud de autorización de venta con tarjeta. | Requiere un importe y los datos aplicables al mecanismo de captura de la tarjeta. El WSDL también exige el elemento |
| Solicita una preautorización de cargo. | Debe utilizarse dentro de un flujo de preautorización admitido por el comercio y el procesador. El contrato no define los plazos de vigencia, las reglas de liberación ni las condiciones para completar posteriormente la operación. |
| Solicita una postautorización de cargo. | Utiliza información de la operación original, incluyendo identificadores y código de aprobación. Deben confirmarse las condiciones bajo las cuales puede completarse una preautorización, así como los límites de importe y tiempo aplicables. |
| Solicita una reautorización de cargo. | Requiere relacionar la solicitud con una operación previa. El WSDL no especifica los escenarios permitidos, las restricciones de importe ni el efecto exacto sobre la autorización original. |
| Operación asociada al flujo de precancelación. | Comparte las estructuras de solicitud y respuesta con |
| Solicita la cancelación de un cargo previamente procesado. | Utiliza los datos de identificación de la operación original. La disponibilidad de la cancelación puede depender del estado de la transacción y de las reglas del procesador. El WSDL no establece una ventana máxima de cancelación. |
| Procesa una solicitud de devolución de un cargo. | Debe relacionarse con una operación existente. Las reglas para devoluciones parciales, límites de importe, plazos y disponibilidad de fondos no están definidas en el WSDL. |
| Solicita la reversa de un cargo. | Es una operación distinta de la cancelación y la devolución. Debe identificarse la transacción original y confirmar las circunstancias en las que el procesador admite una reversa, especialmente ante resultados indeterminados. |
Consideración importante: las operaciones de venta, preautorización, postautorización, reautorización, cancelación, devolución y reversa tienen finalidades diferentes. No deben utilizarse indistintamente para corregir o modificar una transacción.
Las condiciones de autorización, límites de importe, plazos y restricciones de cada operación pueden depender de la configuración del comercio, la afiliación bancaria y las reglas del procesador.
2. Consulta de transacciones y conciliación
Estos métodos permiten recuperar información de operaciones registradas y obtener datos para seguimiento administrativo y conciliación.
Método | Descripción | Condiciones y limitaciones operativas |
|---|---|---|
| Obtiene el estado actual de una venta solicitada. | Utiliza el identificador de la transacción como criterio de consulta. La respuesta incluye un campo |
| Obtiene un listado de transacciones correspondientes a los criterios proporcionados. | Requiere fechas de inicio y fin ( |
| Consulta información de cortes diarios del comercio. | Requiere un intervalo de fechas. La información de cortes no debe interpretarse automáticamente como confirmación de depósito o liquidación bancaria; es necesario validar su alcance contable. |
| Obtiene información del estado de cuenta del comercio. | Requiere el parámetro entero |
Consideración importante: consultar una transacción, obtener un corte diario y consultar un estado de cuenta son operaciones diferentes.
Los datos del Gateway pueden servir para seguimiento y conciliación, pero su equivalencia con depósitos bancarios, liquidaciones definitivas o saldos disponibles debe confirmarse según el proceso financiero correspondiente.
3. Verificación y evidencias de transacciones
Estos métodos complementan las operaciones financieras mediante mecanismos de validación y almacenamiento de evidencia.
Método | Descripción | Condiciones y limitaciones operativas |
|---|---|---|
| Recibe y almacena la firma autógrafa digitalizada del tarjetahabiente, vinculándola con una transacción previamente procesada. | La firma se captura en la terminal como un arreglo de bits y se transmite codificada en Base64. Se utiliza cuando corresponde recabar firma, por ejemplo, en determinadas operaciones MagStripe, cancelaciones, devoluciones o ventas Contactless que la requieren. No genera una nueva autorización bancaria. |
| Valida un código de aprobación bancaria correspondiente a las últimas 24 horas. | La solicitud utiliza |
Consideración importante: estos métodos no deben confundirse con operaciones de autorización o movimiento de fondos.
OpFirma conserva evidencia complementaria de una operación, mientras que validaAutorizacion permite verificar información asociada a un código de aprobación reciente.
4. Comprobantes y notificaciones
Este grupo contempla el envío electrónico de comprobantes de operaciones previamente procesadas.
Método | Descripción | Condiciones y limitaciones operativas |
|---|---|---|
| Solicita el envío del comprobante de una venta a la dirección de correo electrónico indicada. | El voucher se presenta directamente dentro del cuerpo del correo electrónico, sin adjuntarse como archivo PDF. La respuesta SOAP informa el resultado del procesamiento, pero no confirma necesariamente que el destinatario haya recibido o visualizado el mensaje. |
Consideración importante: enviaVoucher no devuelve un documento descargable ni un archivo PDF en su respuesta. Su finalidad es solicitar al Gateway el envío del comprobante correspondiente a una venta existente.
Condiciones generales de operación
Antes de utilizar cualquiera de los métodos del SOAP Gateway, deben considerarse las siguientes condiciones técnicas y operativas.
Autenticación y acceso
Todas las operaciones documentadas utilizan el encabezado SOAP OpHeader, que contiene las claves OpKey1 y OpKey2. Adicionalmente, los métodos incluyen credenciales de identificación del comercio en sus respectivas solicitudes.
El integrador debe disponer de credenciales válidas y de los permisos o capacidades habilitados para las operaciones que desea ejecutar.
Seguridad de la comunicación
Las solicitudes deben transmitirse mediante HTTPS, protegiendo las credenciales y los datos intercambiados con el Gateway.
Cuando una operación incluya información de tarjeta, datos EMV o firmas digitalizadas, deben aplicarse los controles de seguridad correspondientes.
No deben almacenarse datos sensibles en bitácoras, mensajes de error o herramientas de diagnóstico sin una justificación y protección adecuadas.
Disponibilidad de operaciones
La presencia de un método en el WSDL no garantiza que todas las operaciones estén habilitadas para cualquier comercio.
La disponibilidad funcional puede depender de las condiciones de afiliación, configuración del comercio, capacidades del procesador y mecanismos de captura admitidos.
Obligatoriedad de parámetros
El WSDL define la estructura XML y la obligatoriedad técnica de cada elemento mediante atributos como minOccurs. Sin embargo, un parámetro estructuralmente opcional puede ser necesario para que una operación específica se procese correctamente.
Cada integración debe atender tanto las restricciones del contrato como las reglas funcionales del servicio.
Códigos de respuesta
Los métodos transaccionales utilizan campos como codigoRespuesta, procReturnMsg, ccErrorCode y ccReturnMsg para comunicar resultados. La interpretación de estos valores debe realizarse conforme al catálogo aplicable a cada operación.
No debe asumirse que un mismo código tenga necesariamente el mismo significado en todos los métodos.
Control de transacciones duplicadas
Cuando se presente un tiempo de espera agotado, una interrupción de comunicación o una respuesta indeterminada, no debe asumirse automáticamente que la operación no fue procesada.
Antes de repetir una operación financiera, el integrador debe aplicar el procedimiento de verificación y recuperación que corresponda.
Límites y restricciones operativas
El contrato WSDL no define de manera general:
Límites mínimos o máximos de importe estan dados en base a la negociación comercial con OEL
Cantidad máxima de solicitudes por período.
Ventanas de tiempo para cancelaciones, devoluciones o reversas.
Plazos de vigencia de preautorizaciones.
Cantidad máxima de registros en consultas.
Políticas generales de reintentos o solicitudes duplicadas.
Estos aspectos deben confirmarse con OEL y, cuando corresponda, con el procesador o la institución financiera involucrada.
La excepción temporal explícita identificada entre los métodos documentados es validaAutorizacion, cuya descripción establece una consulta sobre las últimas 24 horas.
Recomendaciones para integradores
Para desarrollar una integración confiable con SOAP Gateway, se recomienda:
Identificar el flujo transaccional: seleccionar el método apropiado para cada operación y evitar utilizar cancelaciones, devoluciones y reversas como mecanismos equivalentes.
Conservar los identificadores originales: almacenar de forma segura
transaccionId,referencia,codigoAprobaciony los demás datos necesarios para futuras consultas u operaciones relacionadas.Interpretar las respuestas correctamente: distinguir entre autorizaciones bancarias, resultados funcionales del Gateway y errores de comunicación.
Implementar mecanismos de recuperación: utilizar las operaciones de consulta disponibles para investigar transacciones con resultados indeterminados, sin asumir que una nueva solicitud sea siempre segura.
Proteger la información sensible: aplicar controles de seguridad apropiados a credenciales, información de tarjeta, datos EMV, firmas digitalizadas y datos personales.
Consultar la documentación específica: revisar los parámetros, estructuras XML, ejemplos y restricciones particulares antes de implementar cada método.
Documentación de referencia
Cada uno de los 15 métodos cuenta con una página técnica individual que incluye:
Descripción funcional.
Información del servicio y autenticación.
Parámetros de solicitud y respuesta.
Ejemplos XML de integración SOAP.
Interpretación de resultados y errores.
Consideraciones de implementación.
Condiciones operativas y aspectos pendientes de validación.
Nota sobre el alcance de esta documentación
Esta sección combina las definiciones técnicas verificadas en el WSDL de OEL con la información funcional confirmada durante la elaboración de la documentación.
Cuando el contrato no especifica una regla de negocio, límite operativo o comportamiento del procesador, se identifica expresamente como un aspecto pendiente de confirmación. No debe interpretarse la ausencia de una restricción en el WSDL como garantía de que dicha restricción no existe.
SOAP Gateway es el conjunto de servicios web que permite integrar aplicaciones y sistemas comerciales con el Gateway de Pagos de Operaciones en Línea (OEL), utilizando el protocolo SOAP.
A través de esta interfaz, los desarrolladores pueden procesar pagos con tarjeta, gestionar autorizaciones, realizar cancelaciones y devoluciones, consultar transacciones, obtener información para conciliación y ejecutar operaciones complementarias, como el almacenamiento de firmas autógrafas y el envío de comprobantes electrónicos.
Información general
Característica | Descripción |
|---|---|
Servicio |
|
Tipo de integración | API SOAP |
Protocolos disponibles | SOAP 1.1 y SOAP 1.2 |
Transporte | HTTPS |
Formato de mensajes | XML |
Estilo de comunicación |
|
Autenticación | Credenciales de comercio y encabezado SOAP |
Operaciones documentadas | 15 métodos |
Definición del contrato | WSDL |
Endpoint del servicio
Namespace
Cada operación dispone de su propia estructura de solicitud (Request) y respuesta (Response), definida en el contrato WSDL.
Métodos disponibles
Los 15 métodos documentados se organizan en cuatro grupos funcionales.
1. Procesamiento de pagos y autorizaciones
Estos métodos permiten iniciar operaciones financieras y gestionar autorizaciones previamente procesadas.
Método | Descripción | Condiciones y limitaciones operativas |
|---|---|---|
| Procesa una solicitud de autorización de venta con tarjeta. | Requiere un importe y los datos aplicables al mecanismo de captura de la tarjeta. El WSDL también exige el elemento |
| Solicita una preautorización de cargo. | Debe utilizarse dentro de un flujo de preautorización admitido por el comercio y el procesador. El contrato no define los plazos de vigencia, las reglas de liberación ni las condiciones para completar posteriormente la operación. |
| Solicita una postautorización de cargo. | Utiliza información de la operación original, incluyendo identificadores y código de aprobación. Deben confirmarse las condiciones bajo las cuales puede completarse una preautorización, así como los límites de importe y tiempo aplicables. |
| Solicita una reautorización de cargo. | Requiere relacionar la solicitud con una operación previa. El WSDL no especifica los escenarios permitidos, las restricciones de importe ni el efecto exacto sobre la autorización original. |
| Operación asociada al flujo de precancelación. | Comparte las estructuras de solicitud y respuesta con |
| Solicita la cancelación de un cargo previamente procesado. | Utiliza los datos de identificación de la operación original. La disponibilidad de la cancelación puede depender del estado de la transacción y de las reglas del procesador. El WSDL no establece una ventana máxima de cancelación. |
| Procesa una solicitud de devolución de un cargo. | Debe relacionarse con una operación existente. Las reglas para devoluciones parciales, límites de importe, plazos y disponibilidad de fondos no están definidas en el WSDL. |
| Solicita la reversa de un cargo. | Es una operación distinta de la cancelación y la devolución. Debe identificarse la transacción original y confirmar las circunstancias en las que el procesador admite una reversa, especialmente ante resultados indeterminados. |
Consideración importante: las operaciones de venta, preautorización, postautorización, reautorización, cancelación, devolución y reversa tienen finalidades diferentes. No deben utilizarse indistintamente para corregir o modificar una transacción.
Las condiciones de autorización, límites de importe, plazos y restricciones de cada operación pueden depender de la configuración del comercio, la afiliación bancaria y las reglas del procesador.
2. Consulta de transacciones y conciliación
Estos métodos permiten recuperar información de operaciones registradas y obtener datos para seguimiento administrativo y conciliación.
Método | Descripción | Condiciones y limitaciones operativas |
|---|---|---|
| Obtiene el estado actual de una venta solicitada. | Utiliza el identificador de la transacción como criterio de consulta. La respuesta incluye un campo |
| Obtiene un listado de transacciones correspondientes a los criterios proporcionados. | Requiere fechas de inicio y fin ( |
| Consulta información de cortes diarios del comercio. | Requiere un intervalo de fechas. La información de cortes no debe interpretarse automáticamente como confirmación de depósito o liquidación bancaria; es necesario validar su alcance contable. |
| Obtiene información del estado de cuenta del comercio. | Requiere el parámetro entero |
Consideración importante: consultar una transacción, obtener un corte diario y consultar un estado de cuenta son operaciones diferentes.
Los datos del Gateway pueden servir para seguimiento y conciliación, pero su equivalencia con depósitos bancarios, liquidaciones definitivas o saldos disponibles debe confirmarse según el proceso financiero correspondiente.
3. Verificación y evidencias de transacciones
Estos métodos complementan las operaciones financieras mediante mecanismos de validación y almacenamiento de evidencia.
Método | Descripción | Condiciones y limitaciones operativas |
|---|---|---|
| Recibe y almacena la firma autógrafa digitalizada del tarjetahabiente, vinculándola con una transacción previamente procesada. | La firma se captura en la terminal como un arreglo de bits y se transmite codificada en Base64. Se utiliza cuando corresponde recabar firma, por ejemplo, en determinadas operaciones MagStripe, cancelaciones, devoluciones o ventas Contactless que la requieren. No genera una nueva autorización bancaria. |
| Valida un código de aprobación bancaria correspondiente a las últimas 24 horas. | La solicitud utiliza |
Consideración importante: estos métodos no deben confundirse con operaciones de autorización o movimiento de fondos.
OpFirma conserva evidencia complementaria de una operación, mientras que validaAutorizacion permite verificar información asociada a un código de aprobación reciente.
4. Comprobantes y notificaciones
Este grupo contempla el envío electrónico de comprobantes de operaciones previamente procesadas.
Método | Descripción | Condiciones y limitaciones operativas |
|---|---|---|
| Solicita el envío del comprobante de una venta a la dirección de correo electrónico indicada. | El voucher se presenta directamente dentro del cuerpo del correo electrónico, sin adjuntarse como archivo PDF. La respuesta SOAP informa el resultado del procesamiento, pero no confirma necesariamente que el destinatario haya recibido o visualizado el mensaje. |
Consideración importante: enviaVoucher no devuelve un documento descargable ni un archivo PDF en su respuesta. Su finalidad es solicitar al Gateway el envío del comprobante correspondiente a una venta existente.
Condiciones generales de operación
Antes de utilizar cualquiera de los métodos del SOAP Gateway, deben considerarse las siguientes condiciones técnicas y operativas.
Autenticación y acceso
Todas las operaciones documentadas utilizan el encabezado SOAP OpHeader, que contiene las claves OpKey1 y OpKey2. Adicionalmente, los métodos incluyen credenciales de identificación del comercio en sus respectivas solicitudes.
El integrador debe disponer de credenciales válidas y de los permisos o capacidades habilitados para las operaciones que desea ejecutar.
Seguridad de la comunicación
Las solicitudes deben transmitirse mediante HTTPS, protegiendo las credenciales y los datos intercambiados con el Gateway.
Cuando una operación incluya información de tarjeta, datos EMV o firmas digitalizadas, deben aplicarse los controles de seguridad correspondientes.
No deben almacenarse datos sensibles en bitácoras, mensajes de error o herramientas de diagnóstico sin una justificación y protección adecuadas.
Disponibilidad de operaciones
La presencia de un método en el WSDL no garantiza que todas las operaciones estén habilitadas para cualquier comercio.
La disponibilidad funcional puede depender de las condiciones de afiliación, configuración del comercio, capacidades del procesador y mecanismos de captura admitidos.
Obligatoriedad de parámetros
El WSDL define la estructura XML y la obligatoriedad técnica de cada elemento mediante atributos como minOccurs. Sin embargo, un parámetro estructuralmente opcional puede ser necesario para que una operación específica se procese correctamente.
Cada integración debe atender tanto las restricciones del contrato como las reglas funcionales del servicio.
Códigos de respuesta
Los métodos transaccionales utilizan campos como codigoRespuesta, procReturnMsg, ccErrorCode y ccReturnMsg para comunicar resultados. La interpretación de estos valores debe realizarse conforme al catálogo aplicable a cada operación.
No debe asumirse que un mismo código tenga necesariamente el mismo significado en todos los métodos.
Control de transacciones duplicadas
Cuando se presente un tiempo de espera agotado, una interrupción de comunicación o una respuesta indeterminada, no debe asumirse automáticamente que la operación no fue procesada.
Antes de repetir una operación financiera, el integrador debe aplicar el procedimiento de verificación y recuperación que corresponda.
Límites y restricciones operativas
El contrato WSDL no define de manera general:
Límites mínimos o máximos de importe estan dados en base a la negociación comercial con OEL
Cantidad máxima de solicitudes por período.
Ventanas de tiempo para cancelaciones, devoluciones o reversas.
Plazos de vigencia de preautorizaciones.
Cantidad máxima de registros en consultas.
Políticas generales de reintentos o solicitudes duplicadas.
Estos aspectos deben confirmarse con OEL y, cuando corresponda, con el procesador o la institución financiera involucrada.
La excepción temporal explícita identificada entre los métodos documentados es validaAutorizacion, cuya descripción establece una consulta sobre las últimas 24 horas.
Recomendaciones para integradores
Para desarrollar una integración confiable con SOAP Gateway, se recomienda:
Identificar el flujo transaccional: seleccionar el método apropiado para cada operación y evitar utilizar cancelaciones, devoluciones y reversas como mecanismos equivalentes.
Conservar los identificadores originales: almacenar de forma segura
transaccionId,referencia,codigoAprobaciony los demás datos necesarios para futuras consultas u operaciones relacionadas.Interpretar las respuestas correctamente: distinguir entre autorizaciones bancarias, resultados funcionales del Gateway y errores de comunicación.
Implementar mecanismos de recuperación: utilizar las operaciones de consulta disponibles para investigar transacciones con resultados indeterminados, sin asumir que una nueva solicitud sea siempre segura.
Proteger la información sensible: aplicar controles de seguridad apropiados a credenciales, información de tarjeta, datos EMV, firmas digitalizadas y datos personales.
Consultar la documentación específica: revisar los parámetros, estructuras XML, ejemplos y restricciones particulares antes de implementar cada método.
Documentación de referencia
Cada uno de los 15 métodos cuenta con una página técnica individual que incluye:
Descripción funcional.
Información del servicio y autenticación.
Parámetros de solicitud y respuesta.
Ejemplos XML de integración SOAP.
Interpretación de resultados y errores.
Consideraciones de implementación.
Condiciones operativas y aspectos pendientes de validación.
Nota sobre el alcance de esta documentación
Esta sección combina las definiciones técnicas verificadas en el WSDL de OEL con la información funcional confirmada durante la elaboración de la documentación.
Cuando el contrato no especifica una regla de negocio, límite operativo o comportamiento del procesador, se identifica expresamente como un aspecto pendiente de confirmación. No debe interpretarse la ausencia de una restricción en el WSDL como garantía de que dicha restricción no existe.
SOAP Gateway es el conjunto de servicios web que permite integrar aplicaciones y sistemas comerciales con el Gateway de Pagos de Operaciones en Línea (OEL), utilizando el protocolo SOAP.
A través de esta interfaz, los desarrolladores pueden procesar pagos con tarjeta, gestionar autorizaciones, realizar cancelaciones y devoluciones, consultar transacciones, obtener información para conciliación y ejecutar operaciones complementarias, como el almacenamiento de firmas autógrafas y el envío de comprobantes electrónicos.
Información general
Característica | Descripción |
|---|---|
Servicio |
|
Tipo de integración | API SOAP |
Protocolos disponibles | SOAP 1.1 y SOAP 1.2 |
Transporte | HTTPS |
Formato de mensajes | XML |
Estilo de comunicación |
|
Autenticación | Credenciales de comercio y encabezado SOAP |
Operaciones documentadas | 15 métodos |
Definición del contrato | WSDL |
Endpoint del servicio
Namespace
Cada operación dispone de su propia estructura de solicitud (Request) y respuesta (Response), definida en el contrato WSDL.
Métodos disponibles
Los 15 métodos documentados se organizan en cuatro grupos funcionales.
1. Procesamiento de pagos y autorizaciones
Estos métodos permiten iniciar operaciones financieras y gestionar autorizaciones previamente procesadas.
Método | Descripción | Condiciones y limitaciones operativas |
|---|---|---|
| Procesa una solicitud de autorización de venta con tarjeta. | Requiere un importe y los datos aplicables al mecanismo de captura de la tarjeta. El WSDL también exige el elemento |
| Solicita una preautorización de cargo. | Debe utilizarse dentro de un flujo de preautorización admitido por el comercio y el procesador. El contrato no define los plazos de vigencia, las reglas de liberación ni las condiciones para completar posteriormente la operación. |
| Solicita una postautorización de cargo. | Utiliza información de la operación original, incluyendo identificadores y código de aprobación. Deben confirmarse las condiciones bajo las cuales puede completarse una preautorización, así como los límites de importe y tiempo aplicables. |
| Solicita una reautorización de cargo. | Requiere relacionar la solicitud con una operación previa. El WSDL no especifica los escenarios permitidos, las restricciones de importe ni el efecto exacto sobre la autorización original. |
| Operación asociada al flujo de precancelación. | Comparte las estructuras de solicitud y respuesta con |
| Solicita la cancelación de un cargo previamente procesado. | Utiliza los datos de identificación de la operación original. La disponibilidad de la cancelación puede depender del estado de la transacción y de las reglas del procesador. El WSDL no establece una ventana máxima de cancelación. |
| Procesa una solicitud de devolución de un cargo. | Debe relacionarse con una operación existente. Las reglas para devoluciones parciales, límites de importe, plazos y disponibilidad de fondos no están definidas en el WSDL. |
| Solicita la reversa de un cargo. | Es una operación distinta de la cancelación y la devolución. Debe identificarse la transacción original y confirmar las circunstancias en las que el procesador admite una reversa, especialmente ante resultados indeterminados. |
Consideración importante: las operaciones de venta, preautorización, postautorización, reautorización, cancelación, devolución y reversa tienen finalidades diferentes. No deben utilizarse indistintamente para corregir o modificar una transacción.
Las condiciones de autorización, límites de importe, plazos y restricciones de cada operación pueden depender de la configuración del comercio, la afiliación bancaria y las reglas del procesador.
2. Consulta de transacciones y conciliación
Estos métodos permiten recuperar información de operaciones registradas y obtener datos para seguimiento administrativo y conciliación.
Método | Descripción | Condiciones y limitaciones operativas |
|---|---|---|
| Obtiene el estado actual de una venta solicitada. | Utiliza el identificador de la transacción como criterio de consulta. La respuesta incluye un campo |
| Obtiene un listado de transacciones correspondientes a los criterios proporcionados. | Requiere fechas de inicio y fin ( |
| Consulta información de cortes diarios del comercio. | Requiere un intervalo de fechas. La información de cortes no debe interpretarse automáticamente como confirmación de depósito o liquidación bancaria; es necesario validar su alcance contable. |
| Obtiene información del estado de cuenta del comercio. | Requiere el parámetro entero |
Consideración importante: consultar una transacción, obtener un corte diario y consultar un estado de cuenta son operaciones diferentes.
Los datos del Gateway pueden servir para seguimiento y conciliación, pero su equivalencia con depósitos bancarios, liquidaciones definitivas o saldos disponibles debe confirmarse según el proceso financiero correspondiente.
3. Verificación y evidencias de transacciones
Estos métodos complementan las operaciones financieras mediante mecanismos de validación y almacenamiento de evidencia.
Método | Descripción | Condiciones y limitaciones operativas |
|---|---|---|
| Recibe y almacena la firma autógrafa digitalizada del tarjetahabiente, vinculándola con una transacción previamente procesada. | La firma se captura en la terminal como un arreglo de bits y se transmite codificada en Base64. Se utiliza cuando corresponde recabar firma, por ejemplo, en determinadas operaciones MagStripe, cancelaciones, devoluciones o ventas Contactless que la requieren. No genera una nueva autorización bancaria. |
| Valida un código de aprobación bancaria correspondiente a las últimas 24 horas. | La solicitud utiliza |
Consideración importante: estos métodos no deben confundirse con operaciones de autorización o movimiento de fondos.
OpFirma conserva evidencia complementaria de una operación, mientras que validaAutorizacion permite verificar información asociada a un código de aprobación reciente.
4. Comprobantes y notificaciones
Este grupo contempla el envío electrónico de comprobantes de operaciones previamente procesadas.
Método | Descripción | Condiciones y limitaciones operativas |
|---|---|---|
| Solicita el envío del comprobante de una venta a la dirección de correo electrónico indicada. | El voucher se presenta directamente dentro del cuerpo del correo electrónico, sin adjuntarse como archivo PDF. La respuesta SOAP informa el resultado del procesamiento, pero no confirma necesariamente que el destinatario haya recibido o visualizado el mensaje. |
Consideración importante: enviaVoucher no devuelve un documento descargable ni un archivo PDF en su respuesta. Su finalidad es solicitar al Gateway el envío del comprobante correspondiente a una venta existente.
Condiciones generales de operación
Antes de utilizar cualquiera de los métodos del SOAP Gateway, deben considerarse las siguientes condiciones técnicas y operativas.
Autenticación y acceso
Todas las operaciones documentadas utilizan el encabezado SOAP OpHeader, que contiene las claves OpKey1 y OpKey2. Adicionalmente, los métodos incluyen credenciales de identificación del comercio en sus respectivas solicitudes.
El integrador debe disponer de credenciales válidas y de los permisos o capacidades habilitados para las operaciones que desea ejecutar.
Seguridad de la comunicación
Las solicitudes deben transmitirse mediante HTTPS, protegiendo las credenciales y los datos intercambiados con el Gateway.
Cuando una operación incluya información de tarjeta, datos EMV o firmas digitalizadas, deben aplicarse los controles de seguridad correspondientes.
No deben almacenarse datos sensibles en bitácoras, mensajes de error o herramientas de diagnóstico sin una justificación y protección adecuadas.
Disponibilidad de operaciones
La presencia de un método en el WSDL no garantiza que todas las operaciones estén habilitadas para cualquier comercio.
La disponibilidad funcional puede depender de las condiciones de afiliación, configuración del comercio, capacidades del procesador y mecanismos de captura admitidos.
Obligatoriedad de parámetros
El WSDL define la estructura XML y la obligatoriedad técnica de cada elemento mediante atributos como minOccurs. Sin embargo, un parámetro estructuralmente opcional puede ser necesario para que una operación específica se procese correctamente.
Cada integración debe atender tanto las restricciones del contrato como las reglas funcionales del servicio.
Códigos de respuesta
Los métodos transaccionales utilizan campos como codigoRespuesta, procReturnMsg, ccErrorCode y ccReturnMsg para comunicar resultados. La interpretación de estos valores debe realizarse conforme al catálogo aplicable a cada operación.
No debe asumirse que un mismo código tenga necesariamente el mismo significado en todos los métodos.
Control de transacciones duplicadas
Cuando se presente un tiempo de espera agotado, una interrupción de comunicación o una respuesta indeterminada, no debe asumirse automáticamente que la operación no fue procesada.
Antes de repetir una operación financiera, el integrador debe aplicar el procedimiento de verificación y recuperación que corresponda.
Límites y restricciones operativas
El contrato WSDL no define de manera general:
Límites mínimos o máximos de importe estan dados en base a la negociación comercial con OEL
Cantidad máxima de solicitudes por período.
Ventanas de tiempo para cancelaciones, devoluciones o reversas.
Plazos de vigencia de preautorizaciones.
Cantidad máxima de registros en consultas.
Políticas generales de reintentos o solicitudes duplicadas.
Estos aspectos deben confirmarse con OEL y, cuando corresponda, con el procesador o la institución financiera involucrada.
La excepción temporal explícita identificada entre los métodos documentados es validaAutorizacion, cuya descripción establece una consulta sobre las últimas 24 horas.
Recomendaciones para integradores
Para desarrollar una integración confiable con SOAP Gateway, se recomienda:
Identificar el flujo transaccional: seleccionar el método apropiado para cada operación y evitar utilizar cancelaciones, devoluciones y reversas como mecanismos equivalentes.
Conservar los identificadores originales: almacenar de forma segura
transaccionId,referencia,codigoAprobaciony los demás datos necesarios para futuras consultas u operaciones relacionadas.Interpretar las respuestas correctamente: distinguir entre autorizaciones bancarias, resultados funcionales del Gateway y errores de comunicación.
Implementar mecanismos de recuperación: utilizar las operaciones de consulta disponibles para investigar transacciones con resultados indeterminados, sin asumir que una nueva solicitud sea siempre segura.
Proteger la información sensible: aplicar controles de seguridad apropiados a credenciales, información de tarjeta, datos EMV, firmas digitalizadas y datos personales.
Consultar la documentación específica: revisar los parámetros, estructuras XML, ejemplos y restricciones particulares antes de implementar cada método.
Documentación de referencia
Cada uno de los 15 métodos cuenta con una página técnica individual que incluye:
Descripción funcional.
Información del servicio y autenticación.
Parámetros de solicitud y respuesta.
Ejemplos XML de integración SOAP.
Interpretación de resultados y errores.
Consideraciones de implementación.
Condiciones operativas y aspectos pendientes de validación.
Nota sobre el alcance de esta documentación
Esta sección combina las definiciones técnicas verificadas en el WSDL de OEL con la información funcional confirmada durante la elaboración de la documentación.
Cuando el contrato no especifica una regla de negocio, límite operativo o comportamiento del procesador, se identifica expresamente como un aspecto pendiente de confirmación. No debe interpretarse la ausencia de una restricción en el WSDL como garantía de que dicha restricción no existe.
¿Listo para integrar?
Comienza en ambiente de desarrollo, valida tus primeras operaciones y prepara tu integración para certificación. Cuando el flujo este completo, podrás solicitar el paso a produccion.
¿Listo para integrar?
Comienza en ambiente de desarrollo, valida tus primeras operaciones y prepara tu integración para certificación. Cuando el flujo este completo, podrás solicitar el paso a produccion.
© 2026 Derechos Reservados
© 2026 Derechos Reservados