ecommercePreCancelacion

El método ecommercePreCancelacion permite solicitar la precancelación de un cargo mediante comercio electrónico, utilizando el servicio OpGateway.

Esta operación forma parte de las funcionalidades disponibles para gestionar el ciclo de vida de las transacciones procesadas por OEL.

En particular, puede utilizarse dentro de un flujo de procesamiento que contempla una preautorización y operaciones posteriores relacionadas con ella, siempre que se cumplan las condiciones operativas aplicables.

Descripción oficial del WSDL

Procesa la Pre-Cancelación de un Cargo mediante Comercio Electronico.

Consideración importante

Aunque el nombre del método sugiere una relación con operaciones previamente autorizadas, el WSDL no especifica formalmente:

• Los estados de transacción que permiten solicitar una precancelación.

• Si únicamente aplica a preautorizaciones.

• Si puede ejecutarse después de una postautorización.

• Si admite precancelaciones parciales.

• Los plazos máximos para solicitarla.

• El momento en que los fondos pueden quedar disponibles nuevamente para el tarjetahabiente.

Por tanto, estas condiciones deberán confirmarse con OEL antes de implementar reglas automáticas de precancelación.

2. Casos de uso

La precancelación puede resultar útil en escenarios donde un comercio necesita solicitar la cancelación de una operación que todavía se encuentra en una etapa de procesamiento compatible con este método.

Los escenarios anteriores son ejemplos conceptuales.

La elegibilidad real de cada operación depende de las reglas de OEL, del procesador y de las condiciones aplicables al comercio.

3. Especificaciones técnicas

3.1. Namespace

https://servidorseguro.operacionesenlinea.com/

3.2. Endpoint definido en el WSDL

https://servidorseguro.operacionesenlinea.com/Gateway/OpGateway.asmx

La configuración de los ambientes disponibles se documentará posteriormente en la sección Ambientes.

3.3. SOAPAction

https://servidorseguro.operacionesenlinea.com/ecommercePreCancelacion

3.4. Elementos SOAP

El WSDL declara request y ecommercePreCancelacionResult con minOccurs="0".

Esto indica que los elementos pueden omitirse estructuralmente, pero no garantiza que una solicitud sin datos pueda procesarse correctamente.

4. Autenticación

La operación utiliza los mecanismos de autenticación definidos para OpGateway.

4.1. Encabezado SOAP OpHeader

Ejemplo:

<soap:Header>
  <OpHeader xmlns="https://servidorseguro.operacionesenlinea.com/">
    <OpKey1>CLAVE_1_ASIGNADA</OpKey1>
    <OpKey2>CLAVE_2_ASIGNADA</OpKey2>
  </OpHeader>
</soap:Header>

Aunque ambos campos tienen minOccurs="0", el WSDL no confirma que puedan omitirse funcionalmente.

4.2. Credenciales del comercio

La solicitud incluye:

• comercioId: identificador del comercio.

• contrasena: credencial utilizada para autenticar la operación.

4.3. Autenticación mediante ecommerceSessionID

De acuerdo con el mecanismo funcional confirmado para Bloomin, el campo contrasena puede recibir un token temporal generado previamente mediante ecommerceSessionID.

El token:

1. Se obtiene mediante una solicitud autenticada.

2. Se devuelve en el campo sessionId.

3. Sustituye la contraseña permanente del comercio.

4. Es de un solo uso.

Ejemplo:

<comercioId>12345</comercioId>
<contrasena>TOKEN_UN_SOLO_USO_PRECANCELACION</contrasena>

Importante: si la operación original utilizó un token, este no debe reutilizarse para solicitar la precancelación.

Debe obtenerse un token nuevo para cada operación que utilice este mecanismo.

El uso del token no confirma que las claves del encabezado OpHeader puedan exponerse en un navegador.

5. Parámetros de solicitud (Request)

El método utiliza el modelo cCancelacionReq, compartido con ecommerceCancelacion.

El WSDL define 12 parámetros, en el siguiente orden:

Interpretación de obligatoriedad

• minOccurs="1": campo obligatorio en el XSD.

• minOccurs="0": campo opcional en el XSD.

La obligatoriedad estructural no determina por sí sola qué parámetros son necesarios para procesar una precancelación.

En particular, aunque transaccionId y codigoAprobacion son opcionales estructuralmente, no debe asumirse que el Gateway pueda localizar la operación original sin identificadores suficientes.

6. Descripción detallada de los parámetros

6.1. comercioId

Identificador numérico del comercio que solicita la precancelación.

Tipo: int
Obligatorio en XSD: Sí

Se recomienda utilizar el identificador del comercio relacionado con la operación original.

El WSDL no establece qué ocurre si se intenta precancelar una transacción perteneciente a otro comercio.

6.2. contrasena

Credencial utilizada para autenticar la solicitud.

Tipo: string
Obligatorio en XSD: No

Puede contener la contraseña permanente o un token temporal de un solo uso.

Para integraciones desde navegador, el token permite evitar la exposición de la contraseña permanente.

6.3. modo

Parámetro de modo de operación.

Tipo: string
Obligatorio en XSD: No

El WSDL no publica un catálogo de valores admitidos.

6.4. monto

Importe relacionado con la precancelación solicitada.

Tipo: decimal
Obligatorio en XSD: Sí

Ejemplo:

<monto>1250.00</monto>

El contrato no especifica:

• Moneda.

• Importe mínimo o máximo.

• Precisión decimal.

• Si el importe debe coincidir con el de la operación original.

• Si se admiten precancelaciones parciales.

• Si se permite precancelar un importe inferior al originalmente autorizado.

Estas condiciones deben confirmarse con OEL.

6.5. transaccionId

Identificador de transacción.

Tipo: string
Obligatorio en XSD: No

Es un dato potencialmente relevante para relacionar la precancelación con una operación anterior.

Se recomienda conservar los identificadores devueltos por los métodos de procesamiento originales.

Sin embargo, el WSDL no define:

• Si debe utilizarse el mismo identificador de la preautorización.

• Si debe generarse un identificador nuevo.

• Si debe coincidir con el valor enviado originalmente.

• Si funciona como llave de idempotencia.

6.6. codigoAprobacion

Código de aprobación relacionado con la operación.

Tipo: string
Obligatorio en XSD: No

Ejemplo:

<codigoAprobacion>APR-DEMO-001</codigoAprobacion>

El campo también aparece en la respuesta de ecommercePreAutorizacion.

Esta coincidencia permite identificar una posible relación funcional entre ambos métodos.

No obstante, el WSDL no confirma que el código de aprobación sea obligatorio ni suficiente para identificar la operación que se desea precancelar.

6.7. referencia

Referencia comercial o administrativa.

Tipo: string
Obligatorio en XSD: No

Puede utilizarse para relacionar la solicitud con un pedido, reservación o registro interno.

El WSDL no especifica longitud ni formato.

6.8. firma

Dato de firma relacionado con la solicitud.

Tipo: string
Obligatorio en XSD: No

Este campo merece atención especial.

El WSDL incluye firma dentro de cCancelacionReq, pero no define:

• Su significado funcional.

• El algoritmo utilizado para generarla.

• Si representa una firma criptográfica.

• Si corresponde a una firma del tarjetahabiente.

• Si debe obtenerse de otra operación.

• Su formato.

• Su longitud.

• Los escenarios donde resulta obligatoria.

No debe asumirse que firma representa una firma criptográfica o una firma manuscrita sin confirmación de OEL.

6.9. dirIp

Dirección IP relacionada con la solicitud.

Tipo: string
Obligatorio en XSD: No

El contrato no especifica si corresponde al comprador, al servidor integrador u otro origen.

6.10. deviceId

Identificador de dispositivo.

Tipo: string
Obligatorio en XSD: No

Aunque aparece en una operación de comercio electrónico, el WSDL no define su función específica.

6.11. subcomercio

Dato relacionado con la identificación de un subcomercio.

Tipo: string
Obligatorio en XSD: No

Su formato y reglas de utilización deben confirmarse.

6.12. version

Parámetro de versión.

Tipo: string
Obligatorio en XSD: No

El contrato no indica qué componente o protocolo identifica ni cuáles valores admite.

7. Ejemplo de solicitud SOAP 1.1

El siguiente ejemplo muestra la estructura de una solicitud de precancelación.

Se utilizan identificadores ficticios para ilustrar una posible relación con una operación previa.

El ejemplo es estructural y no confirma cuáles identificadores exige OEL para ejecutar una precancelación real.

7.1. Encabezados HTTP

POST /Gateway/OpGateway.asmx HTTP/1.1
Host: servidorseguro.operacionesenlinea.com
Content-Type: text/xml; charset=utf-8
SOAPAction: "https://servidorseguro.operacionesenlinea.com/ecommercePreCancelacion"

7.2. Solicitud XML

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

  <soap:Header>
    <OpHeader
        xmlns="https://servidorseguro.operacionesenlinea.com/">
      <OpKey1>CLAVE_1_ASIGNADA</OpKey1>
      <OpKey2>CLAVE_2_ASIGNADA</OpKey2>
    </OpHeader>
  </soap:Header>

  <soap:Body>
    <ecommercePreCancelacion
        xmlns="https://servidorseguro.operacionesenlinea.com/">

      <request>
        <comercioId>12345</comercioId>
        <contrasena>TOKEN_UN_SOLO_USO_PRECANCELACION</contrasena>
        <monto>1250.00</monto>
        <transaccionId>PREAUTH-DEMO-000001</transaccionId>
        <codigoAprobacion>APR-DEMO-001</codigoAprobacion>
        <referencia>RESERVA-DEMO-001</referencia>
        <dirIp>192.0.2.10</dirIp>
      </request>

    </ecommercePreCancelacion>
  </soap:Body>

</soap:Envelope>

7.3. Consideraciones

1. Todos los valores son ficticios.

2. El campo contrasena contiene un token nuevo de un solo uso.

3. Los valores de transaccionId y codigoAprobacion ilustran una posible correlación con la operación original.

4. Se omite firma porque no se dispone de una regla verificada para construirla.

5. Se omiten los demás campos opcionales cuyo uso no está definido.

6. El orden de los elementos incluidos corresponde a cCancelacionReq.

7. La dirección IP utilizada está reservada para documentación.

8. La solicitud no debe considerarse lista para ejecutarse sin validar los requisitos operativos de OEL.

8. Parámetros de respuesta (Response)

El método devuelve el elemento ecommercePreCancelacionResult, de tipo cCancelacionResp.

El WSDL define 15 parámetros, en el siguiente orden:

8.1. comercioId

Identificador del comercio relacionado con la respuesta.

Se recomienda verificar su correspondencia con el comercio solicitante.

8.2. terminalId

Identificador de terminal reportado por el Gateway.

El WSDL no define su significado específico en comercio electrónico.

8.3. transaccionId

Identificador de transacción devuelto por el servicio.

Se recomienda conservarlo para seguimiento.

El contrato no especifica si corresponde a la operación original o a la solicitud de precancelación.

8.4. fechaTransaccion y horaTransaccion

Datos temporales de la operación.

Ambos son de tipo string, sin formato ni zona horaria definidos en el WSDL.

8.5. monto

Importe reportado por el servicio.

Debe compararse con la solicitud y con las reglas operativas correspondientes.

8.6. referencia

Referencia devuelta por el Gateway.

Puede facilitar la correlación con los registros internos del comercio.

8.7. numeroControl

Número de control relacionado con el procesamiento.

Su significado y formato no están definidos en el contrato.

8.8. codigoRespuesta

Código funcional de respuesta.

Debe interpretarse utilizando el catálogo oficial de OEL.

8.9. procReturnMsg

Mensaje relacionado con el procesamiento de la operación.

8.10. ccErrorCode

Código complementario de resultado o error.

El WSDL no proporciona su catálogo.

8.11. ccReturnMsg

Mensaje complementario devuelto por el Gateway.

8.12. codigoAprobacion

Código de aprobación reportado cuando corresponda.

No debe asumirse que su presencia indica por sí sola una precancelación satisfactoria.

8.13. afiliacion

Dato de afiliación reportado por el servicio.

8.14. afiliacionEmpresa

Dato de afiliación de empresa reportado por el servicio.

Los significados exactos de ambos campos deben confirmarse con OEL.

9. Ejemplo de respuesta SOAP 1.1

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

  <soap:Body>
    <ecommercePreCancelacionResponse
        xmlns="https://servidorseguro.operacionesenlinea.com/">

      <ecommercePreCancelacionResult>
        <comercioId>12345</comercioId>
        <terminalId>TERMINAL-DEMO</terminalId>
        <transaccionId>PREAUTH-DEMO-000001</transaccionId>
        <fechaTransaccion>FECHA_DE_EJEMPLO</fechaTransaccion>
        <horaTransaccion>HORA_DE_EJEMPLO</horaTransaccion>
        <monto>1250.00</monto>
        <referencia>RESERVA-DEMO-001</referencia>
        <numeroControl>CONTROL-DEMO-001</numeroControl>
        <codigoRespuesta>0</codigoRespuesta>
        <procReturnMsg>MENSAJE_ILUSTRATIVO</procReturnMsg>
        <ccErrorCode>0</ccErrorCode>
        <ccReturnMsg>MENSAJE_ILUSTRATIVO</ccReturnMsg>
        <codigoAprobacion>APR-DEMO-001</codigoAprobacion>
        <afiliacion>AFILIACION-DEMO</afiliacion>
        <afiliacionEmpresa>EMPRESA-DEMO</afiliacionEmpresa>
      </ecommercePreCancelacionResult>

    </ecommercePreCancelacionResponse>
  </soap:Body>

</soap:Envelope>

Consideraciones

• La respuesta es ilustrativa.

• Los códigos 0 no deben interpretarse automáticamente como aprobación.

• Los campos opcionales pueden omitirse.

• El ejemplo no representa una operación bancaria real.

• La confirmación de una precancelación depende de la interpretación oficial de los resultados.

10. Flujo de precancelación

El siguiente flujo representa una propuesta de integración.

Etapa 1. Identificar la operación original

El sistema del comercio localiza la transacción sobre la cual desea solicitar una precancelación.

Etapa 2. Verificar su estado

El integrador determina si la operación se encuentra en un estado compatible con una precancelación, conforme a las reglas de OEL.

Etapa 3. Recuperar identificadores

Se obtienen los datos conservados de la operación original.

Etapa 4. Preparar autenticación

Si se utiliza ecommerceSessionID, se obtiene un token nuevo.

Etapa 5. Construir la solicitud

La aplicación prepara cCancelacionReq, incluyendo los identificadores y parámetros requeridos.

Etapa 6. Invocar ecommercePreCancelacion

La aplicación envía la solicitud SOAP.

Etapa 7. Interpretar la respuesta

Se evalúan codigoRespuesta, ccErrorCode y los mensajes asociados.

Etapa 8. Actualizar el registro comercial

El sistema registra el resultado confirmado o indeterminado.

Etapa 9. Dar seguimiento

Cuando corresponda, se verifica el resultado mediante los mecanismos de consulta o conciliación disponibles.

Diagrama conceptual

SISTEMA DEL COMERCIO
        |
        v
Identificar operación original
        |
        v
Verificar estado de la operación
        |
        +---- No elegible
        |         |
        |         v
        |   No solicitar precancelación
        |
        v
Recuperar identificadores
        |
        v
Obtener token nuevo (si aplica)
        |
        v
ecommercePreCancelacion
        |
        v
Evaluar respuesta funcional
        |
        +---- Resultado indeterminado
        |             |
        |             v
        |       Verificar / conciliar
        |
        v
Registrar resultado confirmado

El diagrama no representa una garantía de liberación inmediata de fondos.

11. Relación con ecommercePreAutorizacion

ecommercePreAutorizacion permite solicitar una preautorización mediante comercio electrónico.

Por su parte, ecommercePreCancelacion permite solicitar una precancelación.

Ambos métodos forman parte del conjunto de operaciones de comercio electrónico de OpGateway.

Información potencialmente relacionada

La respuesta de ecommercePreAutorizacion puede incluir:

• comercioId.

• transaccionId.

• monto.

• codigoAprobacion.

• referenciaTransaccionBancaria.

La solicitud de ecommercePreCancelacion incluye:

• comercioId.

• monto.

• transaccionId.

• codigoAprobacion.

• referencia.

Esta coincidencia de campos permite identificar posibles datos de correlación.

Sin embargo, el WSDL no define cuál es la combinación obligatoria para localizar la operación original.

Recomendación

Conservar los identificadores y resultados de la preautorización, evitando asumir que cualquiera de ellos, por sí solo, sea suficiente para solicitar una precancelación.

12. Diferencias respecto de ecommerceCancelacion

Ambos métodos comparten las estructuras cCancelacionReq y cCancelacionResp.

Diferencia fundamental

Aunque ambas operaciones utilizan los mismos modelos de datos, no deben considerarse equivalentes.

Cada método representa una operación distinta para el Gateway.

El WSDL no define completamente los criterios que determinan cuándo debe utilizarse uno u otro.

La selección debe basarse en las reglas operativas oficiales de OEL.

13. Precancelación y disponibilidad de fondos

La precancelación puede estar relacionada con la cancelación de una autorización previa.

Sin embargo, es importante distinguir entre:

1. La recepción de una solicitud de precancelación.

2. La confirmación funcional de su procesamiento.

3. Los efectos financieros que puedan producirse.

4. La actualización del saldo disponible del tarjetahabiente.

El WSDL no establece que estos eventos ocurran simultáneamente.

Tampoco garantiza un plazo uniforme para la disponibilidad de fondos.

Recomendación de comunicación al comprador

El comercio no debería informar que los fondos han sido liberados inmediatamente basándose únicamente en el envío de la solicitud.

Cualquier confirmación al comprador debe corresponder al resultado efectivamente verificado.

14. Manejo de errores

La operación puede presentar errores de autenticación, validación, comunicación o procesamiento.

Los escenarios anteriores son situaciones que conviene contemplar en una integración; el WSDL no publica códigos específicos para cada una.

15. Prevención de precancelaciones duplicadas

El WSDL no confirma que transaccionId actúe como llave de idempotencia.

Por ello, no debe suponerse que reenviar una solicitud produzca siempre el mismo resultado sin efectos adicionales.

Recomendaciones

1. Registrar cada solicitud de precancelación.

2. Relacionarla con la operación original.

3. Conservar los identificadores enviados.

4. Registrar el resultado funcional recibido.

5. Distinguir entre solicitudes rechazadas y solicitudes con resultado indeterminado.

6. Evitar reintentos automáticos sin verificar el estado previo.

Manejo de timeout

Ante una interrupción de comunicación:

• No asumir que la operación falló.

• No asumir que la operación fue procesada.

• Conservar los identificadores.

• Verificar el estado mediante los mecanismos habilitados.

• Reintentar únicamente cuando exista certeza suficiente de que corresponde hacerlo.

Un token nuevo no elimina el riesgo de duplicación.

16. Consideraciones de seguridad

16.1. Credenciales permanentes

Las credenciales permanentes deben mantenerse protegidas en componentes seguros.

16.2. Tokens temporales

Cada solicitud que utilice ecommerceSessionID debe emplear un token nuevo.

No deben reutilizarse tokens consumidos.

16.3. Encabezado OpHeader

Las claves OpKey1 y OpKey2 deben manejarse conforme a las reglas de seguridad de OEL.

No debe asumirse que el token temporal permite exponerlas públicamente.

16.4. Datos de tarjeta

La estructura cCancelacionReq no incluye campos para número de tarjeta, fecha de vencimiento o código de seguridad.

Esto evita solicitar nuevamente esos datos dentro de la estructura de precancelación.

El alcance PCI DSS depende de la arquitectura completa de integración.

16.5. Registros

Se recomienda conservar:

• Identificador del comercio.

• Identificador de transacción.

• Importe.

• Referencia.

• Código de aprobación.

• Número de control.

• Código funcional.

• Código complementario.

• Fecha y hora reportadas.

No deben registrarse contraseñas permanentes ni tokens activos.

16.6. Control de acceso

Se recomienda que únicamente usuarios y procesos autorizados puedan solicitar precancelaciones.

La autorización de la acción dentro del sistema del comercio debe mantenerse separada de la autenticación técnica ante el Gateway.

17. Restricciones y limitaciones conocidas

El WSDL no especifica:

• Estados de transacción elegibles.

• Plazos máximos de precancelación.

• Moneda.

• Importes mínimos o máximos.

• Posibilidad de precancelaciones parciales.

• Posibilidad de múltiples precancelaciones.

• Reglas de correlación con la operación original.

• Obligatoriedad funcional de codigoAprobacion.

• Significado y generación de firma.

• Reglas de deviceId.

• Catálogo de modo.

• Reglas de subcomercio.

• Valores admitidos para version.

• Catálogo oficial de errores.

• Reglas de idempotencia.

• Tiempo máximo de respuesta.

• Procedimiento de conciliación.

• Plazos de liberación de fondos.

• Condiciones de certificación.

Estas condiciones deberán validarse con OEL antes de considerarlas características soportadas.

18. Aspectos pendientes de confirmación

Para completar la documentación funcional y operativa será necesario confirmar:

1. Qué tipos de operación admiten precancelación.

2. Si la precancelación aplica exclusivamente a preautorizaciones.

3. Estados de transacción permitidos.

4. Plazo máximo para solicitar una precancelación.

5. Si puede precancelarse una operación postautorizada.

6. Si se permiten precancelaciones parciales.

7. Si se permiten múltiples precancelaciones.

8. Si monto debe coincidir con el importe original.

9. Si debe utilizarse el mismo transaccionId.

10. Si codigoAprobacion es obligatorio funcionalmente.

11. Qué identificadores permiten localizar la operación original.

12. Significado y formato de firma.

13. Si firma debe generarse mediante otro método.

14. Catálogo de valores de modo.

15. Significado de deviceId.

16. Reglas de subcomercio.

17. Significado de version.

18. Reglas de dirIp.

19. Moneda y límites de importe.

20. Catálogo de codigoRespuesta.

21. Catálogo de ccErrorCode.

22. Significado de numeroControl.

23. Significado de afiliacion.

24. Significado de afiliacionEmpresa.

25. Formato y zona horaria de fecha y hora.

26. Comportamiento ante solicitudes duplicadas.

27. Procedimiento ante timeout.

28. Vigencia y consumo del token temporal.

29. Manejo seguro de OpHeader desde navegador.

30. Políticas CORS aplicables.

31. Plazos y condiciones de liberación de fondos.

32. Requisitos de certificación y pruebas.

19. Métodos relacionados

20. Referencias técnicas

Contrato: OpGateway.xml

Definiciones utilizadas:

• ecommercePreCancelacion.

• cCancelacionReq.

• ecommercePreCancelacionResponse.

• cCancelacionResp.

• OpHeader.

• SOAPAction de ecommercePreCancelacion.

Información funcional complementaria: mecanismo de autenticación mediante token temporal de un solo uso, confirmado para ecommerceSessionID.

Estado de la documentación: estructura contractual completa; pendientes de confirmación las reglas operativas de precancelación, correlación, vigencia y efectos financieros.