OpPreCancelacion

El método OpPreCancelacion permite solicitar la cancelación de una OpPreAutorizacion previamente autorizada, utilizando el Gateway de Pagos de OEL.

Este método forma parte del flujo de autorización en dos etapas y se utiliza cuando el comercio necesita cancelar una preautorización en lugar de completarla mediante OpPostAutorizacion.

Para realizar la solicitud, el comercio debe proporcionar sus credenciales de autenticación y los datos necesarios para identificar la operación original.

A diferencia de los métodos que procesan una lectura de tarjeta, OpPreCancelacion no requiere transmitir nuevamente el número de tarjeta, Track 2 ni la información EMV.

Importante: la aceptación de la cancelación, la liberación de fondos retenidos y los plazos aplicables dependen de las reglas del adquirente y del banco emisor. Una respuesta aprobada del servicio no garantiza que la liberación del importe sea inmediata.

Información del servicio

Autenticación

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

Adicionalmente, el cuerpo de la solicitud debe incluir comercioId y contrasena, utilizados para identificar al comercio que solicita la cancelación.

Las credenciales deben mantenerse protegidas y no incorporarse en código fuente público, registros de diagnóstico ni ejemplos de documentación.

Parámetros de solicitud (Request)

El método recibe un objeto request de tipo cCancelacionReq, compuesto por 12 parámetros. Los tipos de datos y la obligatoriedad estructural se obtienen del WSDL.

Consideraciones sobre los parámetros

transaccionId

Identifica la operación dentro del sistema del comercio y permite establecer la relación con la preautorización. Este valor debe ser el mismo identificador de la preautorización original.

codigoAprobacion

Representa el código de aprobación bancaria asociado a la autorización previa.

monto

Representa el importe asociado a la autorización previa.

firma

Es un campo de tipo string incluido en el contrato SOAP y corresponde a la firma autografa del Tarjetahabiente recaba en la terminal.

Ejemplo XML Request — SOAP 1.1

El siguiente ejemplo ilustra la estructura de una solicitud de precancelación utilizando valores ficticios y simbólicos.

No representa una transacción ejecutable sin las credenciales, los identificadores y los datos de autorización válidos.

<?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>
    <OpPreCancelacion>
      <request>
        <comercioId>12345</comercioId>
        <contrasena>CLAVE_COMERCIO</contrasena>
        <modo>P</modo>
        <monto>500.00</monto>
        <transaccionId>ID_TRANSACCION</transaccionId>
        <codigoAprobacion>123456</codigoAprobacion>
        <referencia>RESERVA000001</referencia>
        <firma>FIRMA_SEGUN_ESPECIFICACION_OEL</firma>
        <dirIp>192.0.2.10</dirIp>
        <deviceId>12345678</deviceId>
        <subcomercio>SUBCOMERCIO_ID</subcomercio>
        <version>VERSION_SDK</version>
      </request>
    </OpPreCancelacion>

Los valores son exclusivamente ilustrativos. La representación de firma es un marcador simbólico y no constituye una firma válida.

Para una solicitud SOAP 1.1, utiliza las siguientes cabeceras HTTP:

Parámetros de respuesta (Response)

El servicio devuelve un mensaje SOAP que contiene el elemento OpPreCancelacionResponse y, dentro de él, el objeto OpPreCancelacionResult, de tipo cCancelacionResp.

La respuesta está compuesta por 15 parámetros.

Identificación y resultado de la operación

Información de afiliación

Ejemplo XML Response

El siguiente ejemplo representa una respuesta ficticia de una solicitud de precancelación aprobada.

La estructura corresponde al contrato SOAP. Los valores de los códigos y mensajes son ilustrativos y deben confirmarse mediante respuestas reales del servicio.

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

  <soap:Body>
    <OpPreCancelacionResponse>
      <OpPreCancelacionResult>
        <comercioId>12345</comercioId>
        <terminalId>12345678</terminalId>
        <transaccionId>ID_TRANSACCION</transaccionId>
        <fechaTransaccion>10/15/26</fechaTransaccion>
        <horaTransaccion>14:30:00</horaTransaccion>
        <monto>500.00</monto>
        <referencia>RESERVA000001</referencia>
        <numeroControl>CTRL000001</numeroControl>
        <codigoRespuesta>0</codigoRespuesta>
        <procReturnMsg>00</procReturnMsg>
        <ccErrorCode>0</ccErrorCode>
        <ccReturnMsg>APROBADA</ccReturnMsg>
        <codigoAprobacion>123456</codigoAprobacion>
        <afiliacion>AFILIACION_ID</afiliacion>
        <afiliacionEmpresa>EMPRESA_ID</afiliacionEmpresa>
      </OpPreCancelacionResult>
    </OpPreCancelacionResponse>

Códigos de respuesta

Los posibles valores para codigoRespuesta en el método OpPreCancelacion son:

Adicionalmente, el servicio puede devolver información del procesador de pagos mediante procReturnMsg, ccErrorCode y ccReturnMsg.

El WSDL no contiene el catálogo completo de códigos de error ni las reglas de interpretación de las respuestas bancarias.

Consideraciones técnicas

• Preautorización original: la solicitud debe relacionarse con una operación previamente autorizada. Los identificadores necesarios para establecer esta relación deben confirmarse con OEL.

• Importe: verificar que el monto enviado cumpla con las reglas del procesador para la cancelación de preautorizaciones.

• Código de aprobación: conservar el código devuelto por la autorización inicial cuando corresponda, para facilitar la identificación de la operación.

• Firma: no generar ni asumir un valor para firma sin conocer su especificación técnica.

• Seguridad: proteger las credenciales de autenticación y transmitir las solicitudes exclusivamente mediante conexiones HTTPS seguras.

• Datos sensibles: este método no requiere reenviar PAN, Track 2 ni información EMV.

• Control de duplicados: ante una respuesta indeterminada, verificar el estado de la operación antes de intentar nuevamente la cancelación.

• Liberación de fondos: la confirmación de una precancelación no implica necesariamente la liberación inmediata del importe retenido. Los tiempos pueden depender del banco emisor.

Relación con otros métodos