ecommerceCancelacion

El método ecommerceCancelacion permite solicitar la cancelación de un cargo procesado mediante comercio electrónico, utilizando el servicio web OpGateway de OEL.

Esta operación forma parte de las funcionalidades disponibles para administrar el ciclo de vida de las transacciones realizadas por un comercio.

Su propósito es permitir que el integrador solicite la cancelación de una operación anterior, proporcionando los datos necesarios para identificarla y procesar la solicitud.

Descripción funcional

ecommerceCancelacion procesa una solicitud de cancelación de un cargo mediante comercio electrónico.

La operación utiliza el modelo cCancelacionReq para recibir los parámetros y devuelve un objeto cCancelacionResp con la información del procesamiento.

Consideración importante

La cancelación de una transacción y la devolución de un pago no deben considerarse operaciones equivalentes.

El servicio OpGateway dispone de métodos independientes para:

• ecommerceCancelacion.

• ecommercePreCancelacion.

• ecommerceDevolucion.

• ecommerceReversa.

Cada uno representa una operación diferente.

El WSDL no establece las condiciones exactas que determinan cuándo corresponde utilizar cancelación, precancelación, devolución o reversa.

Estas reglas deben confirmarse con OEL.

2. Casos de uso

La cancelación puede utilizarse cuando un comercio necesita solicitar la anulación de una operación de pago anterior, siempre que su estado permita realizarla.

Estos ejemplos son escenarios posibles de integración.

No implican que todas las transacciones puedan cancelarse en cualquier momento.

La elegibilidad depende del estado de la operación y de las reglas del procesamiento.

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

Los endpoints correspondientes a los distintos ambientes se documentarán en la sección Ambientes.

3.3. SOAPAction

https://servidorseguro.operacionesenlinea.com/ecommerceCancelacion

3.4. Elementos SOAP

El WSDL declara el contenedor request y el elemento de resultado con minOccurs="0".

Esta opcionalidad estructural no significa que el Gateway pueda procesar una cancelación sin los datos necesarios.

4. Autenticación

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

4.1. Encabezado SOAP OpHeader

El encabezado SOAP contiene los siguientes parámetros:

Ejemplo:

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

Aunque ambos elementos son opcionales según el XSD, el contrato 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

El método puede utilizar el mecanismo de token temporal generado mediante ecommerceSessionID.

Este mecanismo permite sustituir la contraseña permanente del comercio por un token de un solo uso.

El procedimiento consiste en:

1. Solicitar un token mediante ecommerceSessionID.

2. Recibir el token en el campo sessionId.

3. Incorporarlo como valor de contrasena en ecommerceCancelacion.

4. Consumirlo al realizar la operación.

Ejemplo:

<comercioId>12345</comercioId>
<contrasena>TOKEN_UN_SOLO_USO_CANCELACION</contrasena>

Importante: el token utilizado en la venta original no debe reutilizarse para solicitar su cancelación.

Cuando se utilice este mecanismo, debe obtenerse un token nuevo para la cancelación.

La utilización del token no confirma que sea seguro exponer OpKey1 y OpKey2 en un navegador.

5. Parámetros de solicitud (Request)

El método utiliza la estructura cCancelacionReq.

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

Interpretación de obligatoriedad

• minOccurs="1": el campo es obligatorio según la estructura XSD.

• minOccurs="0": el campo puede omitirse según la estructura XSD.

La obligatoriedad estructural no equivale a la obligatoriedad funcional.

Por ejemplo, aunque transaccionId y codigoAprobacion son opcionales en el XSD, el Gateway necesita contar con información suficiente para identificar la operación que se desea cancelar.

El contrato no define qué combinación de parámetros resulta obligatoria para esa identificación.

6. Descripción detallada de los parámetros

6.1. comercioId

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

Tipo: int
Obligatorio en XSD: Sí

Se recomienda utilizar el identificador correspondiente al comercio que originó la transacción.

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 obtenido mediante ecommerceSessionID.

6.3. modo

Parámetro de modo de operación.

Tipo: string
Obligatorio en XSD: No

El WSDL no especifica un catálogo de valores ni su significado exacto.

6.4. monto

Importe relacionado con la cancelación solicitada.

Tipo: decimal
Obligatorio en XSD: Sí

Ejemplo:

<monto>1250.00</monto>

El WSDL no especifica:

• Moneda.

• Importe mínimo o máximo.

• Precisión decimal.

• Si debe coincidir exactamente con el importe original.

• Si se permiten cancelaciones parciales.

• Si una transacción puede cancelarse en varias operaciones.

Estas condiciones deben confirmarse con OEL.

6.5. transaccionId

Identificador de la transacción.

Tipo: string
Obligatorio en XSD: No

Es uno de los campos disponibles para relacionar la solicitud de cancelación con una operación anterior.

Se recomienda conservar los identificadores de las transacciones originales.

El WSDL no establece si debe enviarse el mismo identificador o generarse uno nuevo.

Tampoco confirma que este campo actúe como llave de idempotencia.

6.6. codigoAprobacion

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

Tipo: string
Obligatorio en XSD: No

Ejemplo:

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

Este campo también puede aparecer en las respuestas de otras operaciones de comercio electrónico.

Su presencia permite conservar una referencia potencialmente útil para relacionar la cancelación con el cargo original.

No obstante, el WSDL no confirma que sea obligatorio ni suficiente para identificar la transacción.

6.7. referencia

Referencia comercial o administrativa.

Tipo: string
Obligatorio en XSD: No

Puede utilizarse para relacionar la cancelación con el pedido o servicio del comercio.

El WSDL no establece longitud ni formato.

6.8. firma

Dato de firma incluido en la solicitud.

Tipo: string
Obligatorio en XSD: No

El contrato no define:

• Su significado funcional.

• El procedimiento para obtenerla.

• Su formato.

• Su longitud.

• Si representa una firma criptográfica.

• Si representa una firma del tarjetahabiente.

• En qué escenarios es obligatoria.

No debe asumirse una interpretación específica 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 debe corresponder al comprador, al servidor integrador o a otro origen.

6.10. deviceId

Identificador de dispositivo.

Tipo: string
Obligatorio en XSD: No

El WSDL no define su utilización específica en operaciones de comercio electrónico.

6.11. subcomercio

Dato relacionado con un subcomercio.

Tipo: string
Obligatorio en XSD: No

Su formato y reglas de utilización deben confirmarse con OEL.

6.12. version

Parámetro de versión.

Tipo: string
Obligatorio en XSD: No

El contrato no especifica qué componente representa ni cuáles valores admite.

7. Ejemplo de solicitud SOAP 1.1

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

Los identificadores son ficticios y se utilizan únicamente para ilustrar la relación con una operación anterior.

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/ecommerceCancelacion"

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>
    <ecommerceCancelacion
        xmlns="https://servidorseguro.operacionesenlinea.com/">

      <request>
        <comercioId>12345</comercioId>
        <contrasena>TOKEN_UN_SOLO_USO_CANCELACION</contrasena>
        <monto>1250.00</monto>
        <transaccionId>VENTA-DEMO-000001</transaccionId>
        <codigoAprobacion>APR-DEMO-001</codigoAprobacion>
        <referencia>PEDIDO-DEMO-001</referencia>
        <dirIp>192.0.2.10</dirIp>
      </request>

    </ecommerceCancelacion>
  </soap:Body>

</soap:Envelope>

7.3. Consideraciones del ejemplo

1. Todos los valores son ficticios.

2. El token representa una credencial temporal de un solo uso.

3. transaccionId y codigoAprobacion ilustran posibles datos de correlación con la operación original.

4. El ejemplo no confirma que esos valores sean suficientes para procesar una cancelación real.

5. Se omite firma porque su mecanismo de generación no está definido en el WSDL.

6. Se omiten los demás campos opcionales cuyo uso no está especificado.

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

8. La dirección IP está reservada para documentación.

8. Parámetros de respuesta (Response)

El método devuelve el elemento ecommerceCancelacionResult, 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 y conciliación.

El contrato no especifica si corresponde al identificador de la venta original o a uno asignado a la cancelación.

8.4. fechaTransaccion y horaTransaccion

Fecha y hora reportadas para la operación.

Ambos campos son de tipo string.

El WSDL no define su formato ni la zona horaria.

8.5. monto

Importe reportado por el Gateway.

Debe verificarse su correspondencia con la solicitud y con las reglas de cancelación aplicables.

8.6. referencia

Referencia devuelta por el servicio.

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

8.7. numeroControl

Número de control asociado con el procesamiento.

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

8.8. codigoRespuesta

Código funcional de respuesta.

Su interpretación debe realizarse mediante el catálogo oficial de OEL.

8.9. procReturnMsg

Mensaje relacionado con el resultado del procesamiento.

8.10. ccErrorCode

Código complementario de resultado o error.

El WSDL no proporciona un catálogo de valores.

8.11. ccReturnMsg

Mensaje complementario devuelto por el Gateway.

8.12. codigoAprobacion

Código de aprobación reportado cuando corresponda.

Su presencia no debe interpretarse por sí sola como confirmación de una cancelació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 estos 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>
    <ecommerceCancelacionResponse
        xmlns="https://servidorseguro.operacionesenlinea.com/">

      <ecommerceCancelacionResult>
        <comercioId>12345</comercioId>
        <terminalId>TERMINAL-DEMO</terminalId>
        <transaccionId>VENTA-DEMO-000001</transaccionId>
        <fechaTransaccion>FECHA_DE_EJEMPLO</fechaTransaccion>
        <horaTransaccion>HORA_DE_EJEMPLO</horaTransaccion>
        <monto>1250.00</monto>
        <referencia>PEDIDO-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>
      </ecommerceCancelacionResult>

    </ecommerceCancelacionResponse>
  </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 transacción bancaria real.

• La cancelación debe considerarse confirmada únicamente cuando los códigos y reglas oficiales así lo indiquen.

10. Flujo de cancelació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 que desea cancelar.

Etapa 2. Verificar su estado

El integrador determina si la operación es elegible para cancelación.

Etapa 3. Recuperar identificadores

Se obtienen los datos necesarios para relacionar la solicitud con la transacción original.

Etapa 4. Preparar autenticación

Si se utiliza ecommerceSessionID, se obtiene un token nuevo de un solo uso.

Etapa 5. Construir la solicitud

La aplicación prepara cCancelacionReq.

Etapa 6. Invocar ecommerceCancelacion

Se envía la solicitud SOAP.

Etapa 7. Interpretar la respuesta

Se evalúan los códigos y mensajes devueltos.

Etapa 8. Actualizar el registro comercial

El sistema registra el resultado confirmado o indeterminado.

Etapa 9. Conciliar

Se realiza el seguimiento correspondiente mediante los mecanismos disponibles.

Diagrama conceptual

SISTEMA DEL COMERCIO
        |
        v
Identificar transacción original
        |
        v
Verificar elegibilidad
        |
        +---- No elegible
        |         |
        |         v
        |   Evaluar operación alternativa
        |
        v
Recuperar identificadores
        |
        v
Obtener token nuevo (si aplica)
        |
        v
ecommerceCancelacion
        |
        v
Evaluar respuesta funcional
        |
        +---- Resultado indeterminado
        |             |
        |             v
        |       Verificar / conciliar
        |
        v
Registrar cancelación confirmada

El diagrama representa una secuencia recomendada para el integrador.

No implica que el Gateway realice automáticamente todas las validaciones mostradas.

11. Relación con ecommerceVenta

El método ecommerceVenta permite solicitar una venta directa mediante comercio electrónico.

Por su parte, ecommerceCancelacion permite solicitar la cancelación de un cargo.

Información potencialmente relacionada

La respuesta de ecommerceVenta puede incluir:

• comercioId.

• transaccionId.

• monto.

• codigoAprobacion.

• referenciaTransaccionBancaria.

La solicitud de ecommerceCancelacion incluye:

• comercioId.

• monto.

• transaccionId.

• codigoAprobacion.

• referencia.

Estos campos proporcionan posibles elementos de correlación.

Sin embargo, el WSDL no especifica cuáles son obligatorios para localizar la venta original.

Recomendación

El integrador debe conservar los identificadores devueltos por ecommerceVenta y confirmar con OEL cuáles deben utilizarse para solicitar su cancelación.

12. Diferencias respecto de ecommercePreCancelacion

Ambos métodos utilizan las mismas estructuras de entrada y salida.

Diferencia funcional

El WSDL distingue ambas operaciones mediante nombres de método y acciones SOAP independientes.

Por tanto, no deben utilizarse indistintamente, aunque compartan estructuras.

Las reglas que determinan cuándo corresponde utilizar cada una deberán confirmarse con OEL.

13. Diferencias respecto de ecommerceDevolucion

ecommerceCancelacion y ecommerceDevolucion son operaciones distintas.

Desde el punto de vista conceptual:

• Una cancelación solicita anular una operación cuando su estado permite utilizar ese mecanismo.

• Una devolución solicita procesar una operación de devolución sobre un cargo anterior, conforme a las reglas aplicables.

Sin embargo, el WSDL no define los estados financieros que separan formalmente ambos procedimientos.

Consideración importante

No debe asumirse que toda venta puede cancelarse después de cualquier plazo.

Tampoco debe suponerse que una devolución puede sustituir automáticamente a una cancelación.

La selección debe basarse en el estado real de la transacción y en las reglas operativas de OEL.

14. Manejo de errores

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

Los escenarios son recomendaciones de diseño para el integrador; el WSDL no proporciona códigos específicos para cada uno.

15. Prevención de cancelaciones duplicadas

El WSDL no confirma que transaccionId funcione como llave de idempotencia.

Por tanto, reenviar la misma solicitud no debe considerarse automáticamente seguro.

Recomendaciones

1. Registrar cada intento de cancelación.

2. Relacionarlo con la operación original.

3. Conservar los identificadores enviados.

4. Registrar los códigos y mensajes recibidos.

5. Distinguir entre resultados confirmados e indeterminados.

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

Manejo de timeout

Ante una interrupción de comunicación:

• No asumir que la cancelación falló.

• No asumir que fue procesada.

• Conservar los identificadores.

• Verificar el resultado mediante los mecanismos habilitados.

• Reintentar únicamente cuando corresponda.

La obtención de 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 el backend.

16.2. Tokens temporales

Cada operación 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.

La existencia del token temporal no demuestra que puedan exponerse públicamente.

16.4. Datos de tarjeta

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

Esto permite solicitar una cancelación sin volver a incorporar esos datos en la estructura del método.

El alcance PCI DSS depende de la arquitectura completa de la 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 almacenarse contraseñas permanentes ni tokens activos en los registros.

16.6. Control de acceso

Se recomienda limitar la capacidad de cancelar operaciones a usuarios y procesos autorizados.

La autorizació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 para cancelación.

• Plazos máximos.

• Moneda.

• Importes mínimos o máximos.

• Posibilidad de cancelaciones parciales.

• Posibilidad de múltiples cancelaciones.

• Reglas exactas 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.

• Condiciones de certificación.

Estas características deben confirmarse antes de considerarlas soportadas.

18. Aspectos pendientes de confirmación

Para completar la documentación operativa de ecommerceCancelacion será necesario confirmar:

1. Qué tipos de transacción admiten cancelación.

2. Estados de transacción elegibles.

3. Plazo máximo para solicitar una cancelación.

4. Si puede cancelarse una venta ya liquidada.

5. Si se permiten cancelaciones parciales.

6. Si se permiten múltiples cancelaciones.

7. Si monto debe coincidir con el importe original.

8. Si debe utilizarse el mismo transaccionId.

9. Si codigoAprobacion es obligatorio funcionalmente.

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

11. Significado y formato de firma.

12. Si firma debe generarse mediante otro procedimiento.

13. Catálogo de valores de modo.

14. Significado de deviceId.

15. Reglas de subcomercio.

16. Significado de version.

17. Reglas de dirIp.

18. Moneda y límites de importe.

19. Catálogo de codigoRespuesta.

20. Catálogo de ccErrorCode.

21. Significado de numeroControl.

22. Significado de afiliacion.

23. Significado de afiliacionEmpresa.

24. Formato y zona horaria de fecha y hora.

25. Comportamiento ante solicitudes duplicadas.

26. Procedimiento ante timeout.

27. Vigencia y consumo del token temporal.

28. Manejo seguro de OpHeader desde navegador.

29. Políticas CORS aplicables.

30. Diferencias operativas respecto de ecommercePreCancelacion.

31. Diferencias operativas respecto de ecommerceDevolucion.

32. Requisitos de certificación y pruebas.

19. Métodos relacionados

20. Referencias técnicas

Contrato: OpGateway.xml

Definiciones utilizadas:

• ecommerceCancelacion.

• cCancelacionReq.

• ecommerceCancelacionResponse.

• cCancelacionResp.

• OpHeader.

• SOAPAction de ecommerceCancelacion.

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 cancelación, correlación, vigencia y efectos financieros.