ecommerceReversa

El método ecommerceReversa permite solicitar la reversa de un cargo mediante comercio electrónico, utilizando el servicio web OpGateway de OEL.

Esta operación forma parte de las funcionalidades disponibles para gestionar transacciones previamente procesadas por el Gateway.

Una reversa es una operación distinta de una cancelación o devolución. Su utilización depende del estado de la transacción original y de las reglas del procesamiento correspondiente.

Descripción oficial del WSDL

Procesa la Reversa de un cargo mediante Comercio Electronico.

Características principales

• Permite solicitar una reversa de cargo.

• Utiliza el modelo de solicitud cReversaReq.

• Devuelve un objeto de tipo cReversaResp.

• Recibe información para identificar la operación relacionada.

• No requiere volver a incluir los datos de la tarjeta dentro de la estructura de solicitud.

• Dispone de mecanismos de autenticación mediante las credenciales del comercio.

Consideración importante

El WSDL confirma la existencia de la operación, pero no establece sus reglas financieras.

En particular, no especifica:

• Los estados de transacción elegibles.

• Si únicamente aplica a transacciones recientes.

• Si puede ejecutarse sobre operaciones liquidadas.

• Si admite reversas parciales.

• Si puede solicitarse más de una reversa sobre una misma operación.

• El tiempo máximo disponible para solicitarla.

• Los efectos financieros exactos de una reversa satisfactoria.

Estas condiciones deben confirmarse con OEL.

2. Casos de uso

Las reversas suelen contemplarse en sistemas de procesamiento de pagos cuando es necesario gestionar una operación anterior que requiere ser revertida.

Los siguientes escenarios son ejemplos conceptuales de situaciones que podrían requerir una reversa.

Importante: estos escenarios no representan una confirmación de que OEL permita reversas en todos los casos descritos.

La elegibilidad debe determinarse mediante las reglas operativas correspondientes.

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 diferentes ambientes se documentarán en la sección Ambientes.

3.3. SOAPAction

https://servidorseguro.operacionesenlinea.com/ecommerceReversa

3.4. Elementos SOAP

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

Esto permite omitir dichos elementos 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 parámetros son opcionales según el XSD, el contrato no confirma que puedan omitirse funcionalmente.

4.2. Credenciales del comercio

La solicitud contiene:

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

El procedimiento consiste en:

1. Solicitar un token mediante ecommerceSessionID.

2. Recibir el token en el campo sessionId.

3. Incorporarlo como valor de contrasena.

4. Invocar ecommerceReversa.

Ejemplo:

<comercioId>12345</comercioId>
<contrasena>TOKEN_UN_SOLO_USO_REVERSA</contrasena>

Importante: no debe reutilizarse el token de la operación original.

Cuando se utilice este mecanismo, cada solicitud de reversa debe emplear un token nuevo.

La utilización de un token temporal no confirma que sea seguro exponer las claves del encabezado OpHeader en un navegador.

5. Parámetros de solicitud (Request)

El método utiliza el modelo cReversaReq.

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

Interpretación de obligatoriedad

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

• minOccurs="0": campo opcional según el XSD.

La obligatoriedad estructural no equivale necesariamente a la obligatoriedad funcional.

Aunque transaccionId y codigoAprobacion son opcionales estructuralmente, el Gateway necesita contar con información suficiente para identificar la operación relacionada.

El contrato no define qué combinación de identificadores resulta obligatoria.

Diferencia respecto de otros métodos

A diferencia de cCancelacionReq y cDevolucionReq, la estructura cReversaReq no contiene el parámetro firma.

Este campo no debe incluirse en la solicitud de reversa.

6. Descripción detallada de los parámetros

6.1. comercioId

Identificador numérico del comercio que solicita la reversa.

Tipo: int
Obligatorio en XSD: Sí

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

6.2. contrasena

Credencial utilizada para autenticar la solicitud.

Tipo: string
Obligatorio en XSD: No

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

6.3. modo

Parámetro de modo de operación.

Tipo: string
Obligatorio en XSD: No

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

6.4. monto

Importe relacionado con la reversa 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 debe coincidir con el importe original.

• Si se permiten reversas parciales.

• Si se permiten múltiples reversas.

Estas condiciones deberán confirmarse con OEL.

6.5. transaccionId

Identificador de transacción.

Tipo: string
Obligatorio en XSD: No

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

El WSDL no establece:

• Si debe enviarse el identificador original.

• Si debe generarse uno nuevo.

• Si representa una llave de idempotencia.

• Si por sí solo permite localizar la transacción.

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 puede aparecer en las respuestas de otras operaciones de comercio electrónico.

Sin embargo, el WSDL no confirma que sea obligatorio ni suficiente para identificar el cargo original.

6.7. referencia

Referencia comercial o administrativa.

Tipo: string
Obligatorio en XSD: No

Puede utilizarse para relacionar la reversa con un pedido, servicio o registro interno.

El WSDL no establece su longitud ni formato.

6.8. 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.9. deviceId

Identificador de dispositivo.

Tipo: string
Obligatorio en XSD: No

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

6.10. subcomercio

Dato relacionado con un subcomercio.

Tipo: string
Obligatorio en XSD: No

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

6.11. 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 reversa.

Los identificadores son ficticios y se utilizan únicamente para ilustrar una posible 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/ecommerceReversa"

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

      <request>
        <comercioId>12345</comercioId>
        <contrasena>TOKEN_UN_SOLO_USO_REVERSA</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>

    </ecommerceReversa>
  </soap:Body>

</soap:Envelope>

7.3. Consideraciones

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.

4. El ejemplo no confirma que esos valores sean suficientes para procesar una reversa real.

5. No se incluye firma, porque no forma parte de cReversaReq.

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

7. El orden de los elementos corresponde al modelo cReversaReq.

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

8. Parámetros de respuesta (Response)

El método devuelve el elemento ecommerceReversaResult, de tipo cReversaResp.

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 operación original o a uno asignado a la reversa.

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 zona horaria.

8.5. monto

Importe reportado por el Gateway.

Se recomienda compararlo con el importe solicitado y con los registros de la operación original.

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 contrato.

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 reversa 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

El siguiente XML representa una respuesta ilustrativa.

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

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

      <ecommerceReversaResult>
        <comercioId>12345</comercioId>
        <terminalId>TERMINAL-DEMO</terminalId>
        <transaccionId>VENTA-DEMO-000001</transaccionId>
        <fechaTransaccion>2026-10-23</fechaTransaccion>
        <horaTransaccion>14:30:00</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>
      </ecommerceReversaResult>

    </ecommerceReversaResponse>
  </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 formato de fecha y hora mostrado no está confirmado por el WSDL.

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

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

10. Flujo de reversa

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 reversa.

Etapa 2. Verificar su estado

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

Etapa 3. Recuperar identificadores

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

Etapa 4. Verificar operaciones anteriores

Se revisa si existe una reversa u otra operación relacionada que pudiera afectar la solicitud.

Etapa 5. Preparar autenticación

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

Etapa 6. Construir la solicitud

La aplicación prepara cReversaReq.

Etapa 7. Invocar ecommerceReversa

Se envía la solicitud SOAP al Gateway.

Etapa 8. Interpretar la respuesta

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

Etapa 9. Actualizar el registro comercial

El sistema registra el resultado confirmado o indeterminado.

Etapa 10. Conciliar

Se realiza el seguimiento correspondiente mediante los mecanismos disponibles.

Diagrama conceptual

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

Este flujo representa una recomendación de integración.

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.

Por su parte, ecommerceReversa permite solicitar una reversa de cargo.

Información potencialmente relacionada

La respuesta de ecommerceVenta puede incluir:

• comercioId.

• transaccionId.

• monto.

• codigoAprobacion.

• referenciaTransaccionBancaria.

La solicitud de ecommerceReversa incluye:

• comercioId.

• monto.

• transaccionId.

• codigoAprobacion.

• referencia.

Estos campos proporcionan posibles elementos de correlación.

Sin embargo, el WSDL no define cuáles son obligatorios para localizar la transacción original.

Recomendación

El integrador debe conservar los identificadores devueltos por ecommerceVenta y confirmar con OEL cuáles deben utilizarse para solicitar una reversa.

12. Diferencias respecto de ecommerceCancelacion

Ambos métodos permiten solicitar operaciones relacionadas con cargos anteriores, pero representan acciones distintas.

Diferencia fundamental

ecommerceCancelacion y ecommerceReversa son métodos independientes.

Aunque sus estructuras son similares, no deben utilizarse indistintamente.

El WSDL no establece los criterios financieros exactos que determinan cuándo corresponde utilizar cada operación.

Estas condiciones deberán confirmarse con OEL.

13. Diferencias respecto de ecommerceDevolucion

El método ecommerceDevolucion contempla expresamente devoluciones totales o parciales.

En cambio, ecommerceReversa se describe únicamente como una operación de reversa de cargo.

Consideración importante

No debe suponerse que una reversa puede sustituir a una devolución.

Tampoco debe asumirse que una devolución y una reversa producen los mismos efectos financieros.

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

14. Reversas y resultados indeterminados

En una integración de pagos, una operación puede presentar un resultado indeterminado cuando existe una interrupción de comunicación.

Por ejemplo:

1. El comercio envía una solicitud de venta.

2. El Gateway recibe la solicitud.

3. Se interrumpe la comunicación antes de recibir la respuesta.

4. El comercio desconoce si la venta fue procesada.

En este escenario, no debe asumirse automáticamente que corresponde ejecutar ecommerceReversa.

Primero debe verificarse el estado de la operación original.

Recomendación

Ante resultados indeterminados:

• Conservar los identificadores enviados.

• Registrar la interrupción de comunicación.

• Verificar el estado mediante los mecanismos disponibles.

• Determinar si corresponde una reversa.

• Ejecutarla únicamente cuando exista una regla operativa que lo permita.

El WSDL no establece que ecommerceReversa sea un mecanismo automático para resolver todos los timeouts.

15. Manejo de errores

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

Los escenarios anteriores son recomendaciones de integración.

El WSDL no proporciona códigos específicos para cada uno.

16. Prevención de reversas duplicadas

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

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

Recomendaciones

1. Registrar cada intento de reversa.

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 reversa 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.

17. Consideraciones de seguridad

17.1. Credenciales permanentes

Las credenciales permanentes deben mantenerse protegidas en componentes seguros.

17.2. Tokens temporales

Cada operación que utilice ecommerceSessionID debe emplear un token nuevo.

No deben reutilizarse tokens consumidos.

17.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.

17.4. Datos de tarjeta

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

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

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

17.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.

17.6. Control de acceso

Se recomienda limitar la capacidad de solicitar reversas 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.

18. Restricciones y limitaciones conocidas

El WSDL no especifica:

• Estados de transacción elegibles.

• Plazos máximos para solicitar reversas.

• Moneda.

• Importes mínimos o máximos.

• Posibilidad de reversas parciales.

• Posibilidad de múltiples reversas.

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

• Obligatoriedad funcional de codigoAprobacion.

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

• Efectos financieros exactos.

• Condiciones de certificación.

Estas características deben confirmarse antes de considerarlas soportadas.

19. Aspectos pendientes de confirmación

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

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

2. Estados de transacción elegibles.

3. Plazo máximo para solicitar una reversa.

4. Si puede ejecutarse sobre una venta liquidada.

5. Si se permiten reversas parciales.

6. Si se permiten múltiples reversas.

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. Catálogo de valores de modo.

12. Significado de deviceId.

13. Reglas de subcomercio.

14. Significado de version.

15. Reglas de dirIp.

16. Moneda y límites de importe.

17. Catálogo de codigoRespuesta.

18. Catálogo de ccErrorCode.

19. Significado de numeroControl.

20. Significado de afiliacion.

21. Significado de afiliacionEmpresa.

22. Formato y zona horaria de fecha y hora.

23. Comportamiento ante solicitudes duplicadas.

24. Procedimiento ante timeout.

25. Vigencia y consumo del token temporal.

26. Manejo seguro de OpHeader desde navegador.

27. Políticas CORS aplicables.

28. Diferencias operativas respecto de ecommerceCancelacion.

29. Diferencias operativas respecto de ecommerceDevolucion.

30. Requisitos de certificación y pruebas.

20. Métodos relacionados

21. Referencias técnicas

Contrato: OpGateway.xml

Definiciones utilizadas:

• ecommerceReversa.

• cReversaReq.

• ecommerceReversaResponse.

• cReversaResp.

• OpHeader.

• SOAPAction de ecommerceReversa.

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