OpObtenerVenta

Descripción

El método OpObtenerVenta permite consultar el estado actual de una venta previamente solicitada a través del Gateway de Pagos de OEL.

Mediante esta operación, el comercio puede recuperar información relacionada con una transacción, incluyendo su estado, códigos de respuesta, importe, referencias, datos de autorización y otros elementos retornados por el procesador de pagos.

Este método resulta especialmente útil para dar seguimiento a las operaciones, verificar resultados y consultar transacciones cuyo estado no haya podido determinarse durante el procesamiento inicial.

La consulta no requiere transmitir nuevamente el número de tarjeta, Track 2 ni los datos EMV de la operación original.

Importante: el método devuelve el estado de una venta según la información disponible en el Gateway.

Información del servicio

Se recomienda utilizar TLS 1.2 o superior, conforme a los requisitos de seguridad de la integración.

Autenticación

La operación utiliza la cabecera SOAP OpHeader, mediante las credenciales asignadas al comercio por OEL.

Adicionalmente, el cuerpo de la solicitud contempla comercioId y contrasena, utilizados para identificar al comercio que realiza la consulta.

Las credenciales deben mantenerse protegidas y no incorporarse en repositorios públicos, registros de diagnóstico ni ejemplos de documentación.

Parámetros de solicitud (Request)

El método recibe un objeto request de tipo cObtenerVentaReq, compuesto por 5 parámetros.

Consideraciones sobre los parámetros

comercioId

Identifica al comercio que realiza la consulta. Debe utilizarse el identificador asignado por OEL.

contrasena

Corresponde a la contraseña de autenticación del comercio. Debe mantenerse protegida y transmitirse exclusivamente mediante conexiones seguras.

transaccionId

Permite identificar la transacción que se desea consultar. Se recomienda conservar el identificador utilizado durante la operación original para facilitar las consultas posteriores y mantener la trazabilidad de los pagos.

deviceId

Identifica el dispositivo asociado a la operación.

version

Identifica la versión del SDK utilizado para realizar la solicitud, cuando corresponda.

Ejemplo XML Request — SOAP 1.1

El siguiente ejemplo muestra la estructura de una solicitud de consulta utilizando valores ficticios y simbólicos.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns="https://servidorseguro.operacionesenlinea.com/">

  <soap:Header>
    <OpHeader>
      <OpKey1>CLAVE_1_ASIGNADA</OpKey1>
      <OpKey2>CLAVE_2_ASIGNADA</OpKey2>
    </OpHeader>
  </soap:Header>

  <soap:Body>
    <OpObtenerVenta>
      <request>
        <comercioId>12345</comercioId>
        <contrasena>CLAVE_COMERCIO</contrasena>
        <transaccionId>ID_TRANSACCION</transaccionId>
        <deviceId>12345678</deviceId>
        <version>VERSION_SDK</version>
      </request>
    </OpObtenerVenta>

Los valores son exclusivamente ilustrativos y no representan credenciales ni identificadores válidos.

Para enviar la solicitud mediante SOAP 1.1, utiliza las siguientes cabeceras HTTP:

Parámetros de respuesta (Response)

El servicio devuelve un mensaje SOAP que contiene el elemento OpObtenerVentaResponse y, dentro de él, el objeto OpObtenerVentaResult, de tipo cObtenerVentaResp.

La respuesta contiene 30 parámetros, organizados en las siguientes categorías.

Identificación y estado de la transacción

Resultado del procesamiento

Información de afiliación

Información de tarjeta y emisor

Información EMV de la transacción

Ejemplo XML Response — Consulta de una venta

El siguiente ejemplo representa una respuesta ficticia que contiene todos los elementos definidos en el contrato SOAP.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns="https://servidorseguro.operacionesenlinea.com/">

  <soap:Body>
    <OpObtenerVentaResponse>
      <OpObtenerVentaResult>
        <comercioId>12345</comercioId>
        <terminalId>12345678</terminalId>
        <transaccionId>ID_TRANSACCION</transaccionId>
        <fechaTransaccion>10/16/26</fechaTransaccion>
        <horaTransaccion>10:30:00</horaTransaccion>
        <monto>500.00</monto>
        <referencia>VENTA000001</referencia>
        <numeroControl>CTRL000001</numeroControl>
        <estatus>0</estatus>
        <codigoRespuesta>0</codigoRespuesta>
        <procReturnMsg>00</procReturnMsg>
        <ccErrorCode>0</ccErrorCode>
        <ccReturnMsg>MENSAJE_SIMBOLICO</ccReturnMsg>
        <codigoAprobacion>123456</codigoAprobacion>
        <afiliacion>AFILIACION_ID</afiliacion>
        <afiliacionEmpresa>EMPRESA_ID</afiliacionEmpresa>
        <emvData>DATOS_EMV_SIMBOLICOS</emvData>
        <operType>TIPO_OPERACION</operType>
        <cardType>TIPO_TARJETA</cardType>
        <cardBrand>MARCA_TARJETA</cardBrand>
        <issuerData>DATOS_EMISOR_SIMBOLICOS</issuerData>
        <issuingBank>BANCO_EJEMPLO</issuingBank>
        <auth_result>RESULTADO_SIMBOLICO</auth_result>
        <referred_card>VALOR_RESTRINGIDO</referred_card>
        <aid>AID_SIMBOLICO</aid>
        <tvr>TVR_SIMBOLICO</tvr>
        <tsi>TSI_SIMBOLICO</tsi>
        <apn>APN_SIMBOLICO</apn>
        <al>AL_SIMBOLICO</al>
        <arqc>ARQC_SIMBOLICO</arqc>
      </OpObtenerVentaResult>
    </OpObtenerVentaResponse>

Los campos que contienen valores simbólicos no representan necesariamente valores válidos del procesador.

En particular, referred_card se ha sustituido por un marcador para evitar mostrar datos reales de tarjetas.

Interpretación de la respuesta

El resultado de la consulta debe evaluarse considerando la información retornada por el servicio.

Campo estatus

Es un parámetro de tipo int que representa el estado actual de la venta.

El WSDL no incluye un catálogo de estados ni establece sus significados. Por esta razón, no deben asignarse interpretaciones específicas a sus valores hasta contar con la documentación oficial.

Campo codigoRespuesta

Es un parámetro de tipo int que informa el resultado principal de la operación. Se identifican los siguientes valores:

Campos del procesador

Los parámetros procReturnMsg, ccErrorCode y ccReturnMsg proporcionan información adicional sobre el procesamiento de la transacción.

Su interpretación debe realizarse conforme a los catálogos de respuesta oficiales de OEL y del procesador correspondiente.

Importante: no debe asumirse que estatus y codigoRespuesta son equivalentes ni que un valor determinado en uno de ellos implica automáticamente un resultado específico en el otro.

Consideraciones técnicas

• Identificación: conservar el identificador de transacción utilizado durante el procesamiento original.

• Consultas de seguimiento: utilizar el método para recuperar información cuando sea necesario verificar el estado de una venta.

• Respuestas indeterminadas: ante una falla de comunicación durante una venta, consultar su estado antes de decidir si corresponde iniciar una nueva operación.

• Campos opcionales: contemplar respuestas que no incluyan todos los parámetros definidos en el WSDL.

• Seguridad: proteger las credenciales de autenticación y utilizar conexiones HTTPS seguras.

• Información sensible: la respuesta puede contener información de tarjeta o datos EMV. Evitar almacenar o registrar estos valores sin una necesidad justificada y los controles de seguridad correspondientes.

• Control de duplicados: no utilizar una respuesta incompleta o un error de consulta como prueba de que una venta no fue procesada.

• Conciliación: conservar los identificadores, importes, fechas y resultados necesarios para relacionar las consultas con las operaciones originales.

Relación con otros métodos