ecommerceDevolucion

Devolución Total o Parcial de un Cargo de Comercio Electrónico

El método ecommerceDevolucion permite solicitar la devolución total o parcial de un cargo procesado mediante comercio electrónico, utilizando el servicio web OpGateway de OEL.

Esta operación permite al comercio gestionar la devolución de un importe relacionado con una transacción anterior.

A diferencia de una cancelación, la devolución constituye una operación específica de reintegro, cuyo procesamiento está sujeto a las condiciones operativas aplicables.

Descripción oficial del WSDL

Procesa la Devolución de un Cargo Total o Parcial mediante Comercio Electronico.

Características principales

  • Permite solicitar devoluciones totales.

  • Permite solicitar devoluciones parciales.

  • Utiliza una estructura de solicitud específica: cDevolucionReq.

  • Devuelve una respuesta de tipo cDevolucionResp.

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

  • Puede utilizar el mecanismo de autenticación mediante token temporal de un solo uso.

Consideración importante

Aunque el WSDL confirma que el método contempla devoluciones totales y parciales, no especifica:

  • Si pueden realizarse múltiples devoluciones parciales sobre una misma venta.

  • El importe máximo acumulado permitido.

  • El plazo disponible para solicitar una devolución.

  • Los estados de transacción elegibles.

  • El tiempo necesario para que el tarjetahabiente reciba los fondos.

  • Si existen restricciones particulares por banco, adquirente o tipo de tarjeta.

Estas condiciones deberán confirmarse con OEL.


2. Casos de uso

El método puede utilizarse en situaciones donde el comercio necesita devolver al comprador la totalidad o una parte del importe de una transacción.

Escenario

Tipo de devolución

Descripción

Cancelación de una compra

Total

Devolver el importe completo de una operación.

Producto no disponible

Parcial

Devolver el importe correspondiente a un producto que no será entregado.

Ajuste comercial

Parcial

Devolver una diferencia de importe.

Servicio no prestado

Total o parcial

Devolver el importe correspondiente al servicio no proporcionado.

Devolución de mercancía

Total o parcial

Gestionar el reintegro relacionado con productos devueltos.

Corrección de un cobro

Total o parcial

Solicitar la devolución del importe que corresponda.

Los escenarios anteriores son ejemplos ilustrativos.

La disponibilidad real de cada modalidad depende de las reglas de procesamiento de OEL.


3. Especificaciones técnicas

Propiedad

Valor

Servicio web

OpGateway

Método

ecommerceDevolucion

Tipo de operación

Devolución total o parcial

Protocolo

SOAP 1.1 / SOAP 1.2

Transporte

HTTPS

Estilo SOAP

Document/literal

Tipo Request

cDevolucionReq

Tipo Response

cDevolucionResp

Parámetros Request

12

Parámetros Response

15

Encabezado SOAP

OpHeader

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/ecommerceDevolucion

3.4. Elementos SOAP

Elemento

Nombre

Operación de solicitud

ecommerceDevolucion

Contenedor de entrada

request

Operación de respuesta

ecommerceDevolucionResponse

Contenedor de resultado

ecommerceDevolucionResult

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

Esta opcionalidad estructural no significa que el servicio pueda procesar una devolución sin los datos funcionalmente necesarios.


4. Autenticación

La operación utiliza el esquema de autenticación definido para OpGateway.

4.1. Encabezado SOAP OpHeader

Parámetro

Tipo XSD

minOccurs

Descripción

OpKey1

string

0

Primera clave del encabezado SOAP.

OpKey2

string

0

Segunda clave del encabezado SOAP.

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 en el XSD, el contrato no confirma que puedan omitirse durante el procesamiento real.

4.2. Credenciales del comercio

La solicitud contiene:

  • comercioId: identificador del comercio.

  • contrasena: credencial de autenticación.

4.3. Autenticación mediante ecommerceSessionID

El campo contrasena puede recibir un token temporal generado mediante ecommerceSessionID.

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

Flujo de autenticación:

  1. El comercio solicita un token mediante ecommerceSessionID.

  2. El Gateway devuelve el token en sessionId.

  3. El integrador coloca el token en contrasena.

  4. Se invoca ecommerceDevolucion.

Ejemplo:

<comercioId>12345</comercioId>
<contrasena>TOKEN_UN_SOLO_USO_DEVOLUCION</contrasena>

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

Cada nueva operación debe utilizar un token nuevo cuando se emplee este mecanismo.

El token temporal no demuestra que OpKey1 y OpKey2 puedan exponerse públicamente.


5. Parámetros de solicitud (Request)

El método utiliza el modelo cDevolucionReq.

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

#

Parámetro

Tipo XSD

minOccurs

Descripción

1

comercioId

int

1

Identificador del comercio.

2

contrasena

string

0

Contraseña permanente o token temporal.

3

modo

string

0

Modo de operación.

4

monto

decimal

1

Importe de la devolución solicitada.

5

transaccionId

string

0

Identificador de transacción.

6

codigoAprobacion

string

0

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

7

referencia

string

0

Referencia comercial o administrativa.

8

firma

string

0

Dato de firma cuyo significado debe confirmarse.

9

dirIp

string

0

Dirección IP relacionada con la solicitud.

10

deviceId

string

0

Identificador de dispositivo.

11

subcomercio

string

0

Dato relacionado con el subcomercio.

12

version

string

0

Parámetro de versión.

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 debe disponer de información suficiente para relacionar la devolución con la operación correspondiente.

El contrato no especifica qué combinación de identificadores es obligatoria.


6. Descripción detallada de los parámetros

6.1. comercioId

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

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 que representa el modo de operación.

Tipo: string
Obligatorio en XSD: No

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

6.4. monto

Importe que se solicita devolver.

Tipo: decimal
Obligatorio en XSD: Sí

Ejemplo:

<monto>450.00</monto>

El parámetro permite expresar el importe de la devolución.

La descripción oficial del método confirma que pueden solicitarse devoluciones totales o parciales.

Ejemplo conceptual: devolución total

Una venta original tiene un importe de $1,250.00 MXN.

El comercio solicita devolver el importe completo:

<monto>1250.00</monto>

Ejemplo conceptual: devolución parcial

Una venta original tiene un importe de $1,250.00 MXN.

El comercio solicita devolver únicamente $450.00 MXN:

<monto>450.00</monto>

Los importes son ilustrativos y la moneda se utiliza únicamente como ejemplo.

El WSDL no incluye un parámetro de moneda ni confirma límites operativos.

6.5. transaccionId

Identificador de transacción.

Tipo: string
Obligatorio en XSD: No

Es un dato potencialmente relevante para relacionar la devolución con la venta original.

El WSDL no especifica:

  • Si debe enviarse el identificador original.

  • Si debe generarse uno nuevo.

  • Si corresponde a un identificador interno del comercio.

  • 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 puede aparecer en la respuesta de ecommerceVenta.

No obstante, el WSDL no confirma que sea obligatorio ni suficiente para identificar la venta que se desea devolver.

6.7. referencia

Referencia comercial o administrativa.

Tipo: string
Obligatorio en XSD: No

Puede utilizarse para relacionar la devolución con un pedido o registro interno.

El WSDL no establece su 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.

  • Su formato.

  • Su longitud.

  • El procedimiento para obtenerlo.

  • Si representa una firma criptográfica.

  • Si corresponde a una firma del tarjetahabiente.

  • Los escenarios donde resulta obligatorio.

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 corresponde 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 representa una solicitud de devolución parcial.

Se utiliza una venta original ficticia de $1,250.00 y una devolución solicitada de $450.00.

Los identificadores son ilustrativos.

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

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

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

    </ecommerceDevolucion>
  </soap:Body>

</soap:Envelope>

7.3. Consideraciones

  1. Todos los valores son ficticios.

  2. La solicitud representa una devolución parcial ilustrativa.

  3. El token debe ser nuevo y de un solo uso.

  4. Los identificadores incluidos ilustran una posible correlación con la venta original.

  5. El WSDL no confirma que esos identificadores sean suficientes para procesar una devolución real.

  6. Se omite firma porque no existe una regla verificada para construirla.

  7. Se omiten los demás parámetros opcionales cuyo uso no está definido.

  8. El orden de los elementos corresponde a cDevolucionReq.

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


8. Parámetros de respuesta (Response)

El método devuelve el elemento ecommerceDevolucionResult, de tipo cDevolucionResp.

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

#

Parámetro

Tipo XSD

minOccurs

Descripción

1

comercioId

int

1

Identificador del comercio.

2

terminalId

string

0

Identificador de terminal reportado por el servicio.

3

transaccionId

string

0

Identificador de transacción.

4

fechaTransaccion

string

0

Fecha de la operación.

5

horaTransaccion

string

0

Hora de la operación.

6

monto

decimal

1

Importe reportado.

7

referencia

string

0

Referencia de la operación.

8

numeroControl

string

0

Número de control relacionado con el procesamiento.

9

codigoRespuesta

int

1

Código funcional de respuesta.

10

procReturnMsg

string

0

Mensaje del procesamiento.

11

ccErrorCode

int

1

Código complementario de resultado o error.

12

ccReturnMsg

string

0

Mensaje complementario del Gateway.

13

codigoAprobacion

string

0

Código de aprobación, cuando corresponda.

14

afiliacion

string

0

Dato de afiliación reportado por el servicio.

15

afiliacionEmpresa

string

0

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

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 para 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 devolución.

8.4. fechaTransaccion y horaTransaccion

Fecha y hora reportadas por el Gateway.

Ambos campos son de tipo string.

El WSDL no define su formato ni la zona horaria.

8.5. monto

Importe reportado por el servicio.

Se recomienda compararlo con el importe solicitado y con el saldo susceptible de devolución.

8.6. referencia

Referencia devuelta por el Gateway.

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.

Debe interpretarse mediante el catálogo oficial de OEL.

8.9. procReturnMsg

Mensaje relacionado con el procesamiento.

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.

Su presencia no debe interpretarse por sí sola como confirmación de una devolució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

El siguiente XML representa una respuesta ilustrativa correspondiente a una solicitud de devolución parcial de $450.00.

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

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

      <ecommerceDevolucionResult>
        <comercioId>12345</comercioId>
        <terminalId>TERMINAL-DEMO</terminalId>
        <transaccionId>VENTA-DEMO-000001</transaccionId>
        <fechaTransaccion>2026-10-23</fechaTransaccion>
        <horaTransaccion>14:30:00</horaTransaccion>
        <monto>450.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-002</codigoAprobacion>
        <afiliacion>AFILIACION-DEMO</afiliacion>
        <afiliacionEmpresa>EMPRESA-DEMO</afiliacionEmpresa>
      </ecommerceDevolucionResult>

    </ecommerceDevolucionResponse>
  </soap:Body>

</soap:Envelope>

Consideraciones

  • Todos los datos son ilustrativos.

  • 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 devolución debe considerarse confirmada únicamente cuando los códigos y reglas oficiales así lo indiquen.


10. Flujo de devolución

El siguiente flujo representa una propuesta de integración.

Etapa 1. Identificar la venta original

El sistema del comercio localiza la operación sobre la cual se desea solicitar una devolución.

Etapa 2. Verificar elegibilidad

El integrador determina si la transacción es elegible para devolución conforme a las reglas operativas aplicables.

Etapa 3. Determinar el importe

El comercio establece si corresponde una devolución total o parcial.

Etapa 4. Verificar devoluciones anteriores

Cuando corresponda, se revisan las devoluciones previamente relacionadas con la venta.

Esta validación permite reducir el riesgo de solicitar importes superiores a los permitidos.

Etapa 5. Recuperar identificadores

Se obtienen los datos necesarios para relacionar la devolución con la operación original.

Etapa 6. Preparar autenticación

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

Etapa 7. Construir la solicitud

La aplicación prepara cDevolucionReq.

Etapa 8. Invocar ecommerceDevolucion

Se envía la solicitud SOAP al Gateway.

Etapa 9. Interpretar la respuesta

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

Etapa 10. Actualizar los registros

El sistema registra el resultado confirmado o indeterminado.

Etapa 11. Conciliar

Se realiza el seguimiento correspondiente mediante los mecanismos disponibles.

Diagrama conceptual

SISTEMA DEL COMERCIO
        |
        v
Identificar venta original
        |
        v
Verificar elegibilidad
        |
        +---- No elegible
        |         |
        |         v
        |   Gestionar alternativa
        |
        v
Determinar importe a devolver
        |
        v
Verificar devoluciones anteriores
        |
        v
Recuperar identificadores
        |
        v
Obtener token nuevo (si aplica)
        |
        v
ecommerceDevolucion
        |
        v
Evaluar respuesta funcional
        |
        +---- Resultado indeterminado
        |             |
        |             v
        |       Verificar / conciliar
        |
        v
Registrar devolución confirmada
        |
        v
Seguimiento financiero

Este diagrama representa una secuencia recomendada para el integrador.

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


11. Devoluciones totales y parciales

El WSDL confirma expresamente que ecommerceDevolucion contempla ambas modalidades.

11.1. Devolución total

Una devolución total solicita reintegrar el importe completo de la operación original.

Ejemplo conceptual:

Concepto

Importe

Venta original

$1,250.00

Devolución solicitada

$1,250.00

Importe neto después de la devolución

$0.00

Este resultado es un ejemplo contable simplificado y supone que la devolución fue efectivamente procesada.

11.2. Devolución parcial

Una devolución parcial solicita reintegrar únicamente una parte del importe original.

Ejemplo conceptual:

Concepto

Importe

Venta original

$1,250.00

Devolución solicitada

$450.00

Importe neto después de la devolución

$800.00

Este resultado también supone que la devolución fue confirmada.

11.3. Múltiples devoluciones parciales

El WSDL no confirma si pueden realizarse múltiples devoluciones parciales sobre una misma venta.

Por tanto, el siguiente escenario debe considerarse una posibilidad pendiente de validación, no una funcionalidad confirmada:

Operación

Importe

Acumulado

Venta original

$1,250.00

—

Primera devolución

$300.00

$300.00

Segunda devolución

$450.00

$750.00

Tercera devolución

$500.00

$1,250.00

La aceptación de este comportamiento depende de las reglas de OEL.

11.4. Control del importe disponible

Como recomendación de diseño, el sistema del comercio puede mantener un control interno del importe potencialmente disponible para devolución.

Fórmula conceptual:

Importe disponible para devolución
    =
Importe original
    -
Total de devoluciones confirmadas

Esta fórmula es una regla contable simplificada.

No sustituye las validaciones del Gateway ni contempla ajustes, comisiones, propinas u otras condiciones que pudieran aplicar.


12. Relación con ecommerceVenta

El método ecommerceVenta permite solicitar una venta directa.

El método ecommerceDevolucion permite solicitar la devolución total o parcial de un cargo.

Información potencialmente relacionada

La respuesta de ecommerceVenta puede incluir:

  • comercioId.

  • transaccionId.

  • monto.

  • codigoAprobacion.

  • referenciaTransaccionBancaria.

La solicitud de ecommerceDevolucion incluye:

  • comercioId.

  • monto.

  • transaccionId.

  • codigoAprobacion.

  • referencia.

Estos campos ofrecen posibles elementos para correlacionar ambas operaciones.

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

Recomendación

Conservar los identificadores devueltos por ecommerceVenta y confirmar con OEL cuáles deben utilizarse en la solicitud de devolución.


13. Diferencias respecto de ecommerceCancelacion

Aunque ambos métodos comparten una estructura de campos equivalente, representan operaciones distintas.

Característica

ecommerceCancelacion

ecommerceDevolucion

Finalidad declarada

Cancelación de un cargo

Devolución de un cargo

Tipo Request

cCancelacionReq

cDevolucionReq

Parámetros Request

12

12

Tipo Response

cCancelacionResp

cDevolucionResp

Parámetros Response

15

15

Operación total

Sujeto a reglas operativas

Contemplada expresamente

Operación parcial

No especificada en el WSDL

Contemplada expresamente

SOAPAction

Específica de cancelación

Específica de devolución

Diferencia fundamental

ecommerceDevolucion tiene una descripción contractual que contempla expresamente la devolución total o parcial.

En cambio, el WSDL no establece expresamente que ecommerceCancelacion admita cancelaciones parciales.

Esto no significa que las cancelaciones parciales sean necesariamente imposibles; significa que esa capacidad no está confirmada por el contrato disponible.

Selección del método

El integrador no debe seleccionar entre cancelación y devolución basándose únicamente en la preferencia comercial.

Debe considerar el estado real de la transacción y las reglas operativas de OEL.


14. Tiempo de procesamiento y disponibilidad de fondos

Una devolución puede involucrar distintas etapas de procesamiento.

Es importante distinguir entre:

  1. La recepción de la solicitud.

  2. La respuesta funcional del Gateway.

  3. El procesamiento financiero correspondiente.

  4. La actualización de los registros bancarios.

  5. La disponibilidad de los fondos para el tarjetahabiente.

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

Tampoco establece un plazo uniforme para la disponibilidad de fondos.

Recomendación de comunicación al comprador

El comercio no debería informar que el dinero ya está disponible en la cuenta del comprador basándose únicamente en el envío de la solicitud.

La comunicación debe corresponder al estado efectivamente confirmado.


15. Manejo de errores

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

Escenario

Tratamiento recomendado

Devolución confirmada como satisfactoria

Registrar el resultado y actualizar el estado comercial.

Devolución confirmada como rechazada

Registrar el rechazo sin descontar el importe como devuelto.

Venta original no localizada

Revisar los identificadores enviados.

Operación no elegible

Verificar el estado y las reglas aplicables.

Importe superior al permitido

Revisar el importe y las devoluciones anteriores.

Token inválido o consumido

Verificar el resultado del intento antes de generar una nueva operación.

Error de autenticación

Resolver el problema antes de continuar.

SOAP Fault

Registrar el error técnico y evaluar si pudo existir procesamiento.

Timeout

Mantener el resultado como indeterminado hasta verificarlo.

Respuesta incompleta

No inferir devolución satisfactoria.

Solicitud duplicada

Evitar reintentos automáticos hasta verificar el estado.

Los escenarios anteriores son recomendaciones de integración.

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


16. Prevención de devoluciones duplicadas

Una devolución puede tener consecuencias financieras.

Por ello, los reintentos deben controlarse cuidadosamente.

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

Recomendaciones

  1. Registrar cada solicitud de devolución.

  2. Relacionarla con la venta original.

  3. Conservar los identificadores enviados.

  4. Registrar el importe solicitado.

  5. Registrar los códigos y mensajes recibidos.

  6. Mantener el historial de devoluciones confirmadas.

  7. Distinguir entre resultados confirmados e indeterminados.

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

Manejo de timeout

Ante una interrupción de comunicación:

  • No asumir que la devolució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.


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 cDevolucionReq no incluye campos para número de tarjeta, fecha de vencimiento o código de seguridad.

Esto permite solicitar la devolución 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 de la devolución.

  • 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 devoluciones a usuarios y procesos autorizados.

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.7. Controles antifraude

Como recomendación de arquitectura, el comercio puede implementar:

  • Límites de importe por usuario.

  • Autorización adicional para devoluciones elevadas.

  • Registro de motivos de devolución.

  • Conciliación de importes.

  • Auditoría de solicitudes.

  • Alertas por devoluciones repetidas.

Estas medidas son recomendaciones para el integrador y no funcionalidades confirmadas del Gateway.


18. Restricciones y limitaciones conocidas

El WSDL no especifica:

  • Estados de transacción elegibles.

  • Plazos máximos para solicitar devoluciones.

  • Moneda.

  • Importes mínimos o máximos.

  • Número máximo de devoluciones parciales.

  • Importe máximo acumulado.

  • Reglas exactas de correlación con la venta 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 disponibilidad de fondos.

  • 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 devolución.

  2. Estados de transacción elegibles.

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

  4. Si pueden realizarse múltiples devoluciones parciales.

  5. Importe máximo acumulado permitido.

  6. Si el importe acumulado puede superar el de la venta original.

  7. Si monto debe expresarse en la misma moneda de la venta.

  8. Si debe utilizarse el mismo transaccionId.

  9. Si codigoAprobacion es obligatorio funcionalmente.

  10. Qué identificadores permiten localizar la venta 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. Plazos de disponibilidad de fondos.

  31. Diferencias operativas respecto de ecommerceCancelacion.

  32. Requisitos de certificación y pruebas.


20. Métodos relacionados

Método

Relación

ecommerceSessionID

Genera el token temporal de autenticación.

ecommerceVenta

Solicita una venta directa.

ecommercePreAutorizacion

Solicita una preautorización.

ecommercePostAutorizacion

Solicita una postautorización.

ecommercePreCancelacion

Solicita una precancelación.

ecommerceCancelacion

Solicita una cancelación de cargo.

ecommerceReversa

Solicita una reversa.


21. Referencias técnicas

Contrato: OpGateway.xml

Definiciones utilizadas:

  • ecommerceDevolucion.

  • cDevolucionReq.

  • ecommerceDevolucionResponse.

  • cDevolucionResp.

  • OpHeader.

  • SOAPAction de ecommerceDevolucion.

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; confirmada la funcionalidad de devolución total o parcial. Pendientes de confirmación las reglas de correlación, vigencia, devoluciones múltiples y efectos financieros.

El método ecommerceDevolucion permite solicitar la devolución total o parcial de un cargo procesado mediante comercio electrónico, utilizando el servicio web OpGateway de OEL.

Esta operación permite al comercio gestionar la devolución de un importe relacionado con una transacción anterior.

A diferencia de una cancelación, la devolución constituye una operación específica de reintegro, cuyo procesamiento está sujeto a las condiciones operativas aplicables.

Descripción oficial del WSDL

Procesa la Devolución de un Cargo Total o Parcial mediante Comercio Electronico.

Características principales

  • Permite solicitar devoluciones totales.

  • Permite solicitar devoluciones parciales.

  • Utiliza una estructura de solicitud específica: cDevolucionReq.

  • Devuelve una respuesta de tipo cDevolucionResp.

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

  • Puede utilizar el mecanismo de autenticación mediante token temporal de un solo uso.

Consideración importante

Aunque el WSDL confirma que el método contempla devoluciones totales y parciales, no especifica:

  • Si pueden realizarse múltiples devoluciones parciales sobre una misma venta.

  • El importe máximo acumulado permitido.

  • El plazo disponible para solicitar una devolución.

  • Los estados de transacción elegibles.

  • El tiempo necesario para que el tarjetahabiente reciba los fondos.

  • Si existen restricciones particulares por banco, adquirente o tipo de tarjeta.

Estas condiciones deberán confirmarse con OEL.


2. Casos de uso

El método puede utilizarse en situaciones donde el comercio necesita devolver al comprador la totalidad o una parte del importe de una transacción.

Escenario

Tipo de devolución

Descripción

Cancelación de una compra

Total

Devolver el importe completo de una operación.

Producto no disponible

Parcial

Devolver el importe correspondiente a un producto que no será entregado.

Ajuste comercial

Parcial

Devolver una diferencia de importe.

Servicio no prestado

Total o parcial

Devolver el importe correspondiente al servicio no proporcionado.

Devolución de mercancía

Total o parcial

Gestionar el reintegro relacionado con productos devueltos.

Corrección de un cobro

Total o parcial

Solicitar la devolución del importe que corresponda.

Los escenarios anteriores son ejemplos ilustrativos.

La disponibilidad real de cada modalidad depende de las reglas de procesamiento de OEL.


3. Especificaciones técnicas

Propiedad

Valor

Servicio web

OpGateway

Método

ecommerceDevolucion

Tipo de operación

Devolución total o parcial

Protocolo

SOAP 1.1 / SOAP 1.2

Transporte

HTTPS

Estilo SOAP

Document/literal

Tipo Request

cDevolucionReq

Tipo Response

cDevolucionResp

Parámetros Request

12

Parámetros Response

15

Encabezado SOAP

OpHeader

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/ecommerceDevolucion

3.4. Elementos SOAP

Elemento

Nombre

Operación de solicitud

ecommerceDevolucion

Contenedor de entrada

request

Operación de respuesta

ecommerceDevolucionResponse

Contenedor de resultado

ecommerceDevolucionResult

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

Esta opcionalidad estructural no significa que el servicio pueda procesar una devolución sin los datos funcionalmente necesarios.


4. Autenticación

La operación utiliza el esquema de autenticación definido para OpGateway.

4.1. Encabezado SOAP OpHeader

Parámetro

Tipo XSD

minOccurs

Descripción

OpKey1

string

0

Primera clave del encabezado SOAP.

OpKey2

string

0

Segunda clave del encabezado SOAP.

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 en el XSD, el contrato no confirma que puedan omitirse durante el procesamiento real.

4.2. Credenciales del comercio

La solicitud contiene:

  • comercioId: identificador del comercio.

  • contrasena: credencial de autenticación.

4.3. Autenticación mediante ecommerceSessionID

El campo contrasena puede recibir un token temporal generado mediante ecommerceSessionID.

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

Flujo de autenticación:

  1. El comercio solicita un token mediante ecommerceSessionID.

  2. El Gateway devuelve el token en sessionId.

  3. El integrador coloca el token en contrasena.

  4. Se invoca ecommerceDevolucion.

Ejemplo:

<comercioId>12345</comercioId>
<contrasena>TOKEN_UN_SOLO_USO_DEVOLUCION</contrasena>

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

Cada nueva operación debe utilizar un token nuevo cuando se emplee este mecanismo.

El token temporal no demuestra que OpKey1 y OpKey2 puedan exponerse públicamente.


5. Parámetros de solicitud (Request)

El método utiliza el modelo cDevolucionReq.

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

#

Parámetro

Tipo XSD

minOccurs

Descripción

1

comercioId

int

1

Identificador del comercio.

2

contrasena

string

0

Contraseña permanente o token temporal.

3

modo

string

0

Modo de operación.

4

monto

decimal

1

Importe de la devolución solicitada.

5

transaccionId

string

0

Identificador de transacción.

6

codigoAprobacion

string

0

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

7

referencia

string

0

Referencia comercial o administrativa.

8

firma

string

0

Dato de firma cuyo significado debe confirmarse.

9

dirIp

string

0

Dirección IP relacionada con la solicitud.

10

deviceId

string

0

Identificador de dispositivo.

11

subcomercio

string

0

Dato relacionado con el subcomercio.

12

version

string

0

Parámetro de versión.

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 debe disponer de información suficiente para relacionar la devolución con la operación correspondiente.

El contrato no especifica qué combinación de identificadores es obligatoria.


6. Descripción detallada de los parámetros

6.1. comercioId

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

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 que representa el modo de operación.

Tipo: string
Obligatorio en XSD: No

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

6.4. monto

Importe que se solicita devolver.

Tipo: decimal
Obligatorio en XSD: Sí

Ejemplo:

<monto>450.00</monto>

El parámetro permite expresar el importe de la devolución.

La descripción oficial del método confirma que pueden solicitarse devoluciones totales o parciales.

Ejemplo conceptual: devolución total

Una venta original tiene un importe de $1,250.00 MXN.

El comercio solicita devolver el importe completo:

<monto>1250.00</monto>

Ejemplo conceptual: devolución parcial

Una venta original tiene un importe de $1,250.00 MXN.

El comercio solicita devolver únicamente $450.00 MXN:

<monto>450.00</monto>

Los importes son ilustrativos y la moneda se utiliza únicamente como ejemplo.

El WSDL no incluye un parámetro de moneda ni confirma límites operativos.

6.5. transaccionId

Identificador de transacción.

Tipo: string
Obligatorio en XSD: No

Es un dato potencialmente relevante para relacionar la devolución con la venta original.

El WSDL no especifica:

  • Si debe enviarse el identificador original.

  • Si debe generarse uno nuevo.

  • Si corresponde a un identificador interno del comercio.

  • 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 puede aparecer en la respuesta de ecommerceVenta.

No obstante, el WSDL no confirma que sea obligatorio ni suficiente para identificar la venta que se desea devolver.

6.7. referencia

Referencia comercial o administrativa.

Tipo: string
Obligatorio en XSD: No

Puede utilizarse para relacionar la devolución con un pedido o registro interno.

El WSDL no establece su 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.

  • Su formato.

  • Su longitud.

  • El procedimiento para obtenerlo.

  • Si representa una firma criptográfica.

  • Si corresponde a una firma del tarjetahabiente.

  • Los escenarios donde resulta obligatorio.

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 corresponde 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 representa una solicitud de devolución parcial.

Se utiliza una venta original ficticia de $1,250.00 y una devolución solicitada de $450.00.

Los identificadores son ilustrativos.

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

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

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

    </ecommerceDevolucion>
  </soap:Body>

</soap:Envelope>

7.3. Consideraciones

  1. Todos los valores son ficticios.

  2. La solicitud representa una devolución parcial ilustrativa.

  3. El token debe ser nuevo y de un solo uso.

  4. Los identificadores incluidos ilustran una posible correlación con la venta original.

  5. El WSDL no confirma que esos identificadores sean suficientes para procesar una devolución real.

  6. Se omite firma porque no existe una regla verificada para construirla.

  7. Se omiten los demás parámetros opcionales cuyo uso no está definido.

  8. El orden de los elementos corresponde a cDevolucionReq.

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


8. Parámetros de respuesta (Response)

El método devuelve el elemento ecommerceDevolucionResult, de tipo cDevolucionResp.

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

#

Parámetro

Tipo XSD

minOccurs

Descripción

1

comercioId

int

1

Identificador del comercio.

2

terminalId

string

0

Identificador de terminal reportado por el servicio.

3

transaccionId

string

0

Identificador de transacción.

4

fechaTransaccion

string

0

Fecha de la operación.

5

horaTransaccion

string

0

Hora de la operación.

6

monto

decimal

1

Importe reportado.

7

referencia

string

0

Referencia de la operación.

8

numeroControl

string

0

Número de control relacionado con el procesamiento.

9

codigoRespuesta

int

1

Código funcional de respuesta.

10

procReturnMsg

string

0

Mensaje del procesamiento.

11

ccErrorCode

int

1

Código complementario de resultado o error.

12

ccReturnMsg

string

0

Mensaje complementario del Gateway.

13

codigoAprobacion

string

0

Código de aprobación, cuando corresponda.

14

afiliacion

string

0

Dato de afiliación reportado por el servicio.

15

afiliacionEmpresa

string

0

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

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 para 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 devolución.

8.4. fechaTransaccion y horaTransaccion

Fecha y hora reportadas por el Gateway.

Ambos campos son de tipo string.

El WSDL no define su formato ni la zona horaria.

8.5. monto

Importe reportado por el servicio.

Se recomienda compararlo con el importe solicitado y con el saldo susceptible de devolución.

8.6. referencia

Referencia devuelta por el Gateway.

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.

Debe interpretarse mediante el catálogo oficial de OEL.

8.9. procReturnMsg

Mensaje relacionado con el procesamiento.

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.

Su presencia no debe interpretarse por sí sola como confirmación de una devolució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

El siguiente XML representa una respuesta ilustrativa correspondiente a una solicitud de devolución parcial de $450.00.

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

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

      <ecommerceDevolucionResult>
        <comercioId>12345</comercioId>
        <terminalId>TERMINAL-DEMO</terminalId>
        <transaccionId>VENTA-DEMO-000001</transaccionId>
        <fechaTransaccion>2026-10-23</fechaTransaccion>
        <horaTransaccion>14:30:00</horaTransaccion>
        <monto>450.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-002</codigoAprobacion>
        <afiliacion>AFILIACION-DEMO</afiliacion>
        <afiliacionEmpresa>EMPRESA-DEMO</afiliacionEmpresa>
      </ecommerceDevolucionResult>

    </ecommerceDevolucionResponse>
  </soap:Body>

</soap:Envelope>

Consideraciones

  • Todos los datos son ilustrativos.

  • 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 devolución debe considerarse confirmada únicamente cuando los códigos y reglas oficiales así lo indiquen.


10. Flujo de devolución

El siguiente flujo representa una propuesta de integración.

Etapa 1. Identificar la venta original

El sistema del comercio localiza la operación sobre la cual se desea solicitar una devolución.

Etapa 2. Verificar elegibilidad

El integrador determina si la transacción es elegible para devolución conforme a las reglas operativas aplicables.

Etapa 3. Determinar el importe

El comercio establece si corresponde una devolución total o parcial.

Etapa 4. Verificar devoluciones anteriores

Cuando corresponda, se revisan las devoluciones previamente relacionadas con la venta.

Esta validación permite reducir el riesgo de solicitar importes superiores a los permitidos.

Etapa 5. Recuperar identificadores

Se obtienen los datos necesarios para relacionar la devolución con la operación original.

Etapa 6. Preparar autenticación

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

Etapa 7. Construir la solicitud

La aplicación prepara cDevolucionReq.

Etapa 8. Invocar ecommerceDevolucion

Se envía la solicitud SOAP al Gateway.

Etapa 9. Interpretar la respuesta

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

Etapa 10. Actualizar los registros

El sistema registra el resultado confirmado o indeterminado.

Etapa 11. Conciliar

Se realiza el seguimiento correspondiente mediante los mecanismos disponibles.

Diagrama conceptual

SISTEMA DEL COMERCIO
        |
        v
Identificar venta original
        |
        v
Verificar elegibilidad
        |
        +---- No elegible
        |         |
        |         v
        |   Gestionar alternativa
        |
        v
Determinar importe a devolver
        |
        v
Verificar devoluciones anteriores
        |
        v
Recuperar identificadores
        |
        v
Obtener token nuevo (si aplica)
        |
        v
ecommerceDevolucion
        |
        v
Evaluar respuesta funcional
        |
        +---- Resultado indeterminado
        |             |
        |             v
        |       Verificar / conciliar
        |
        v
Registrar devolución confirmada
        |
        v
Seguimiento financiero

Este diagrama representa una secuencia recomendada para el integrador.

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


11. Devoluciones totales y parciales

El WSDL confirma expresamente que ecommerceDevolucion contempla ambas modalidades.

11.1. Devolución total

Una devolución total solicita reintegrar el importe completo de la operación original.

Ejemplo conceptual:

Concepto

Importe

Venta original

$1,250.00

Devolución solicitada

$1,250.00

Importe neto después de la devolución

$0.00

Este resultado es un ejemplo contable simplificado y supone que la devolución fue efectivamente procesada.

11.2. Devolución parcial

Una devolución parcial solicita reintegrar únicamente una parte del importe original.

Ejemplo conceptual:

Concepto

Importe

Venta original

$1,250.00

Devolución solicitada

$450.00

Importe neto después de la devolución

$800.00

Este resultado también supone que la devolución fue confirmada.

11.3. Múltiples devoluciones parciales

El WSDL no confirma si pueden realizarse múltiples devoluciones parciales sobre una misma venta.

Por tanto, el siguiente escenario debe considerarse una posibilidad pendiente de validación, no una funcionalidad confirmada:

Operación

Importe

Acumulado

Venta original

$1,250.00

—

Primera devolución

$300.00

$300.00

Segunda devolución

$450.00

$750.00

Tercera devolución

$500.00

$1,250.00

La aceptación de este comportamiento depende de las reglas de OEL.

11.4. Control del importe disponible

Como recomendación de diseño, el sistema del comercio puede mantener un control interno del importe potencialmente disponible para devolución.

Fórmula conceptual:

Importe disponible para devolución
    =
Importe original
    -
Total de devoluciones confirmadas

Esta fórmula es una regla contable simplificada.

No sustituye las validaciones del Gateway ni contempla ajustes, comisiones, propinas u otras condiciones que pudieran aplicar.


12. Relación con ecommerceVenta

El método ecommerceVenta permite solicitar una venta directa.

El método ecommerceDevolucion permite solicitar la devolución total o parcial de un cargo.

Información potencialmente relacionada

La respuesta de ecommerceVenta puede incluir:

  • comercioId.

  • transaccionId.

  • monto.

  • codigoAprobacion.

  • referenciaTransaccionBancaria.

La solicitud de ecommerceDevolucion incluye:

  • comercioId.

  • monto.

  • transaccionId.

  • codigoAprobacion.

  • referencia.

Estos campos ofrecen posibles elementos para correlacionar ambas operaciones.

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

Recomendación

Conservar los identificadores devueltos por ecommerceVenta y confirmar con OEL cuáles deben utilizarse en la solicitud de devolución.


13. Diferencias respecto de ecommerceCancelacion

Aunque ambos métodos comparten una estructura de campos equivalente, representan operaciones distintas.

Característica

ecommerceCancelacion

ecommerceDevolucion

Finalidad declarada

Cancelación de un cargo

Devolución de un cargo

Tipo Request

cCancelacionReq

cDevolucionReq

Parámetros Request

12

12

Tipo Response

cCancelacionResp

cDevolucionResp

Parámetros Response

15

15

Operación total

Sujeto a reglas operativas

Contemplada expresamente

Operación parcial

No especificada en el WSDL

Contemplada expresamente

SOAPAction

Específica de cancelación

Específica de devolución

Diferencia fundamental

ecommerceDevolucion tiene una descripción contractual que contempla expresamente la devolución total o parcial.

En cambio, el WSDL no establece expresamente que ecommerceCancelacion admita cancelaciones parciales.

Esto no significa que las cancelaciones parciales sean necesariamente imposibles; significa que esa capacidad no está confirmada por el contrato disponible.

Selección del método

El integrador no debe seleccionar entre cancelación y devolución basándose únicamente en la preferencia comercial.

Debe considerar el estado real de la transacción y las reglas operativas de OEL.


14. Tiempo de procesamiento y disponibilidad de fondos

Una devolución puede involucrar distintas etapas de procesamiento.

Es importante distinguir entre:

  1. La recepción de la solicitud.

  2. La respuesta funcional del Gateway.

  3. El procesamiento financiero correspondiente.

  4. La actualización de los registros bancarios.

  5. La disponibilidad de los fondos para el tarjetahabiente.

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

Tampoco establece un plazo uniforme para la disponibilidad de fondos.

Recomendación de comunicación al comprador

El comercio no debería informar que el dinero ya está disponible en la cuenta del comprador basándose únicamente en el envío de la solicitud.

La comunicación debe corresponder al estado efectivamente confirmado.


15. Manejo de errores

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

Escenario

Tratamiento recomendado

Devolución confirmada como satisfactoria

Registrar el resultado y actualizar el estado comercial.

Devolución confirmada como rechazada

Registrar el rechazo sin descontar el importe como devuelto.

Venta original no localizada

Revisar los identificadores enviados.

Operación no elegible

Verificar el estado y las reglas aplicables.

Importe superior al permitido

Revisar el importe y las devoluciones anteriores.

Token inválido o consumido

Verificar el resultado del intento antes de generar una nueva operación.

Error de autenticación

Resolver el problema antes de continuar.

SOAP Fault

Registrar el error técnico y evaluar si pudo existir procesamiento.

Timeout

Mantener el resultado como indeterminado hasta verificarlo.

Respuesta incompleta

No inferir devolución satisfactoria.

Solicitud duplicada

Evitar reintentos automáticos hasta verificar el estado.

Los escenarios anteriores son recomendaciones de integración.

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


16. Prevención de devoluciones duplicadas

Una devolución puede tener consecuencias financieras.

Por ello, los reintentos deben controlarse cuidadosamente.

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

Recomendaciones

  1. Registrar cada solicitud de devolución.

  2. Relacionarla con la venta original.

  3. Conservar los identificadores enviados.

  4. Registrar el importe solicitado.

  5. Registrar los códigos y mensajes recibidos.

  6. Mantener el historial de devoluciones confirmadas.

  7. Distinguir entre resultados confirmados e indeterminados.

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

Manejo de timeout

Ante una interrupción de comunicación:

  • No asumir que la devolució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.


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 cDevolucionReq no incluye campos para número de tarjeta, fecha de vencimiento o código de seguridad.

Esto permite solicitar la devolución 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 de la devolución.

  • 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 devoluciones a usuarios y procesos autorizados.

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.7. Controles antifraude

Como recomendación de arquitectura, el comercio puede implementar:

  • Límites de importe por usuario.

  • Autorización adicional para devoluciones elevadas.

  • Registro de motivos de devolución.

  • Conciliación de importes.

  • Auditoría de solicitudes.

  • Alertas por devoluciones repetidas.

Estas medidas son recomendaciones para el integrador y no funcionalidades confirmadas del Gateway.


18. Restricciones y limitaciones conocidas

El WSDL no especifica:

  • Estados de transacción elegibles.

  • Plazos máximos para solicitar devoluciones.

  • Moneda.

  • Importes mínimos o máximos.

  • Número máximo de devoluciones parciales.

  • Importe máximo acumulado.

  • Reglas exactas de correlación con la venta 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 disponibilidad de fondos.

  • 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 devolución.

  2. Estados de transacción elegibles.

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

  4. Si pueden realizarse múltiples devoluciones parciales.

  5. Importe máximo acumulado permitido.

  6. Si el importe acumulado puede superar el de la venta original.

  7. Si monto debe expresarse en la misma moneda de la venta.

  8. Si debe utilizarse el mismo transaccionId.

  9. Si codigoAprobacion es obligatorio funcionalmente.

  10. Qué identificadores permiten localizar la venta 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. Plazos de disponibilidad de fondos.

  31. Diferencias operativas respecto de ecommerceCancelacion.

  32. Requisitos de certificación y pruebas.


20. Métodos relacionados

Método

Relación

ecommerceSessionID

Genera el token temporal de autenticación.

ecommerceVenta

Solicita una venta directa.

ecommercePreAutorizacion

Solicita una preautorización.

ecommercePostAutorizacion

Solicita una postautorización.

ecommercePreCancelacion

Solicita una precancelación.

ecommerceCancelacion

Solicita una cancelación de cargo.

ecommerceReversa

Solicita una reversa.


21. Referencias técnicas

Contrato: OpGateway.xml

Definiciones utilizadas:

  • ecommerceDevolucion.

  • cDevolucionReq.

  • ecommerceDevolucionResponse.

  • cDevolucionResp.

  • OpHeader.

  • SOAPAction de ecommerceDevolucion.

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; confirmada la funcionalidad de devolución total o parcial. Pendientes de confirmación las reglas de correlación, vigencia, devoluciones múltiples y efectos financieros.

El método ecommerceDevolucion permite solicitar la devolución total o parcial de un cargo procesado mediante comercio electrónico, utilizando el servicio web OpGateway de OEL.

Esta operación permite al comercio gestionar la devolución de un importe relacionado con una transacción anterior.

A diferencia de una cancelación, la devolución constituye una operación específica de reintegro, cuyo procesamiento está sujeto a las condiciones operativas aplicables.

Descripción oficial del WSDL

Procesa la Devolución de un Cargo Total o Parcial mediante Comercio Electronico.

Características principales

  • Permite solicitar devoluciones totales.

  • Permite solicitar devoluciones parciales.

  • Utiliza una estructura de solicitud específica: cDevolucionReq.

  • Devuelve una respuesta de tipo cDevolucionResp.

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

  • Puede utilizar el mecanismo de autenticación mediante token temporal de un solo uso.

Consideración importante

Aunque el WSDL confirma que el método contempla devoluciones totales y parciales, no especifica:

  • Si pueden realizarse múltiples devoluciones parciales sobre una misma venta.

  • El importe máximo acumulado permitido.

  • El plazo disponible para solicitar una devolución.

  • Los estados de transacción elegibles.

  • El tiempo necesario para que el tarjetahabiente reciba los fondos.

  • Si existen restricciones particulares por banco, adquirente o tipo de tarjeta.

Estas condiciones deberán confirmarse con OEL.


2. Casos de uso

El método puede utilizarse en situaciones donde el comercio necesita devolver al comprador la totalidad o una parte del importe de una transacción.

Escenario

Tipo de devolución

Descripción

Cancelación de una compra

Total

Devolver el importe completo de una operación.

Producto no disponible

Parcial

Devolver el importe correspondiente a un producto que no será entregado.

Ajuste comercial

Parcial

Devolver una diferencia de importe.

Servicio no prestado

Total o parcial

Devolver el importe correspondiente al servicio no proporcionado.

Devolución de mercancía

Total o parcial

Gestionar el reintegro relacionado con productos devueltos.

Corrección de un cobro

Total o parcial

Solicitar la devolución del importe que corresponda.

Los escenarios anteriores son ejemplos ilustrativos.

La disponibilidad real de cada modalidad depende de las reglas de procesamiento de OEL.


3. Especificaciones técnicas

Propiedad

Valor

Servicio web

OpGateway

Método

ecommerceDevolucion

Tipo de operación

Devolución total o parcial

Protocolo

SOAP 1.1 / SOAP 1.2

Transporte

HTTPS

Estilo SOAP

Document/literal

Tipo Request

cDevolucionReq

Tipo Response

cDevolucionResp

Parámetros Request

12

Parámetros Response

15

Encabezado SOAP

OpHeader

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/ecommerceDevolucion

3.4. Elementos SOAP

Elemento

Nombre

Operación de solicitud

ecommerceDevolucion

Contenedor de entrada

request

Operación de respuesta

ecommerceDevolucionResponse

Contenedor de resultado

ecommerceDevolucionResult

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

Esta opcionalidad estructural no significa que el servicio pueda procesar una devolución sin los datos funcionalmente necesarios.


4. Autenticación

La operación utiliza el esquema de autenticación definido para OpGateway.

4.1. Encabezado SOAP OpHeader

Parámetro

Tipo XSD

minOccurs

Descripción

OpKey1

string

0

Primera clave del encabezado SOAP.

OpKey2

string

0

Segunda clave del encabezado SOAP.

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 en el XSD, el contrato no confirma que puedan omitirse durante el procesamiento real.

4.2. Credenciales del comercio

La solicitud contiene:

  • comercioId: identificador del comercio.

  • contrasena: credencial de autenticación.

4.3. Autenticación mediante ecommerceSessionID

El campo contrasena puede recibir un token temporal generado mediante ecommerceSessionID.

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

Flujo de autenticación:

  1. El comercio solicita un token mediante ecommerceSessionID.

  2. El Gateway devuelve el token en sessionId.

  3. El integrador coloca el token en contrasena.

  4. Se invoca ecommerceDevolucion.

Ejemplo:

<comercioId>12345</comercioId>
<contrasena>TOKEN_UN_SOLO_USO_DEVOLUCION</contrasena>

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

Cada nueva operación debe utilizar un token nuevo cuando se emplee este mecanismo.

El token temporal no demuestra que OpKey1 y OpKey2 puedan exponerse públicamente.


5. Parámetros de solicitud (Request)

El método utiliza el modelo cDevolucionReq.

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

#

Parámetro

Tipo XSD

minOccurs

Descripción

1

comercioId

int

1

Identificador del comercio.

2

contrasena

string

0

Contraseña permanente o token temporal.

3

modo

string

0

Modo de operación.

4

monto

decimal

1

Importe de la devolución solicitada.

5

transaccionId

string

0

Identificador de transacción.

6

codigoAprobacion

string

0

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

7

referencia

string

0

Referencia comercial o administrativa.

8

firma

string

0

Dato de firma cuyo significado debe confirmarse.

9

dirIp

string

0

Dirección IP relacionada con la solicitud.

10

deviceId

string

0

Identificador de dispositivo.

11

subcomercio

string

0

Dato relacionado con el subcomercio.

12

version

string

0

Parámetro de versión.

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 debe disponer de información suficiente para relacionar la devolución con la operación correspondiente.

El contrato no especifica qué combinación de identificadores es obligatoria.


6. Descripción detallada de los parámetros

6.1. comercioId

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

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 que representa el modo de operación.

Tipo: string
Obligatorio en XSD: No

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

6.4. monto

Importe que se solicita devolver.

Tipo: decimal
Obligatorio en XSD: Sí

Ejemplo:

<monto>450.00</monto>

El parámetro permite expresar el importe de la devolución.

La descripción oficial del método confirma que pueden solicitarse devoluciones totales o parciales.

Ejemplo conceptual: devolución total

Una venta original tiene un importe de $1,250.00 MXN.

El comercio solicita devolver el importe completo:

<monto>1250.00</monto>

Ejemplo conceptual: devolución parcial

Una venta original tiene un importe de $1,250.00 MXN.

El comercio solicita devolver únicamente $450.00 MXN:

<monto>450.00</monto>

Los importes son ilustrativos y la moneda se utiliza únicamente como ejemplo.

El WSDL no incluye un parámetro de moneda ni confirma límites operativos.

6.5. transaccionId

Identificador de transacción.

Tipo: string
Obligatorio en XSD: No

Es un dato potencialmente relevante para relacionar la devolución con la venta original.

El WSDL no especifica:

  • Si debe enviarse el identificador original.

  • Si debe generarse uno nuevo.

  • Si corresponde a un identificador interno del comercio.

  • 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 puede aparecer en la respuesta de ecommerceVenta.

No obstante, el WSDL no confirma que sea obligatorio ni suficiente para identificar la venta que se desea devolver.

6.7. referencia

Referencia comercial o administrativa.

Tipo: string
Obligatorio en XSD: No

Puede utilizarse para relacionar la devolución con un pedido o registro interno.

El WSDL no establece su 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.

  • Su formato.

  • Su longitud.

  • El procedimiento para obtenerlo.

  • Si representa una firma criptográfica.

  • Si corresponde a una firma del tarjetahabiente.

  • Los escenarios donde resulta obligatorio.

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 corresponde 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 representa una solicitud de devolución parcial.

Se utiliza una venta original ficticia de $1,250.00 y una devolución solicitada de $450.00.

Los identificadores son ilustrativos.

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

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

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

    </ecommerceDevolucion>
  </soap:Body>

</soap:Envelope>

7.3. Consideraciones

  1. Todos los valores son ficticios.

  2. La solicitud representa una devolución parcial ilustrativa.

  3. El token debe ser nuevo y de un solo uso.

  4. Los identificadores incluidos ilustran una posible correlación con la venta original.

  5. El WSDL no confirma que esos identificadores sean suficientes para procesar una devolución real.

  6. Se omite firma porque no existe una regla verificada para construirla.

  7. Se omiten los demás parámetros opcionales cuyo uso no está definido.

  8. El orden de los elementos corresponde a cDevolucionReq.

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


8. Parámetros de respuesta (Response)

El método devuelve el elemento ecommerceDevolucionResult, de tipo cDevolucionResp.

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

#

Parámetro

Tipo XSD

minOccurs

Descripción

1

comercioId

int

1

Identificador del comercio.

2

terminalId

string

0

Identificador de terminal reportado por el servicio.

3

transaccionId

string

0

Identificador de transacción.

4

fechaTransaccion

string

0

Fecha de la operación.

5

horaTransaccion

string

0

Hora de la operación.

6

monto

decimal

1

Importe reportado.

7

referencia

string

0

Referencia de la operación.

8

numeroControl

string

0

Número de control relacionado con el procesamiento.

9

codigoRespuesta

int

1

Código funcional de respuesta.

10

procReturnMsg

string

0

Mensaje del procesamiento.

11

ccErrorCode

int

1

Código complementario de resultado o error.

12

ccReturnMsg

string

0

Mensaje complementario del Gateway.

13

codigoAprobacion

string

0

Código de aprobación, cuando corresponda.

14

afiliacion

string

0

Dato de afiliación reportado por el servicio.

15

afiliacionEmpresa

string

0

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

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 para 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 devolución.

8.4. fechaTransaccion y horaTransaccion

Fecha y hora reportadas por el Gateway.

Ambos campos son de tipo string.

El WSDL no define su formato ni la zona horaria.

8.5. monto

Importe reportado por el servicio.

Se recomienda compararlo con el importe solicitado y con el saldo susceptible de devolución.

8.6. referencia

Referencia devuelta por el Gateway.

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.

Debe interpretarse mediante el catálogo oficial de OEL.

8.9. procReturnMsg

Mensaje relacionado con el procesamiento.

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.

Su presencia no debe interpretarse por sí sola como confirmación de una devolució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

El siguiente XML representa una respuesta ilustrativa correspondiente a una solicitud de devolución parcial de $450.00.

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

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

      <ecommerceDevolucionResult>
        <comercioId>12345</comercioId>
        <terminalId>TERMINAL-DEMO</terminalId>
        <transaccionId>VENTA-DEMO-000001</transaccionId>
        <fechaTransaccion>2026-10-23</fechaTransaccion>
        <horaTransaccion>14:30:00</horaTransaccion>
        <monto>450.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-002</codigoAprobacion>
        <afiliacion>AFILIACION-DEMO</afiliacion>
        <afiliacionEmpresa>EMPRESA-DEMO</afiliacionEmpresa>
      </ecommerceDevolucionResult>

    </ecommerceDevolucionResponse>
  </soap:Body>

</soap:Envelope>

Consideraciones

  • Todos los datos son ilustrativos.

  • 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 devolución debe considerarse confirmada únicamente cuando los códigos y reglas oficiales así lo indiquen.


10. Flujo de devolución

El siguiente flujo representa una propuesta de integración.

Etapa 1. Identificar la venta original

El sistema del comercio localiza la operación sobre la cual se desea solicitar una devolución.

Etapa 2. Verificar elegibilidad

El integrador determina si la transacción es elegible para devolución conforme a las reglas operativas aplicables.

Etapa 3. Determinar el importe

El comercio establece si corresponde una devolución total o parcial.

Etapa 4. Verificar devoluciones anteriores

Cuando corresponda, se revisan las devoluciones previamente relacionadas con la venta.

Esta validación permite reducir el riesgo de solicitar importes superiores a los permitidos.

Etapa 5. Recuperar identificadores

Se obtienen los datos necesarios para relacionar la devolución con la operación original.

Etapa 6. Preparar autenticación

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

Etapa 7. Construir la solicitud

La aplicación prepara cDevolucionReq.

Etapa 8. Invocar ecommerceDevolucion

Se envía la solicitud SOAP al Gateway.

Etapa 9. Interpretar la respuesta

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

Etapa 10. Actualizar los registros

El sistema registra el resultado confirmado o indeterminado.

Etapa 11. Conciliar

Se realiza el seguimiento correspondiente mediante los mecanismos disponibles.

Diagrama conceptual

SISTEMA DEL COMERCIO
        |
        v
Identificar venta original
        |
        v
Verificar elegibilidad
        |
        +---- No elegible
        |         |
        |         v
        |   Gestionar alternativa
        |
        v
Determinar importe a devolver
        |
        v
Verificar devoluciones anteriores
        |
        v
Recuperar identificadores
        |
        v
Obtener token nuevo (si aplica)
        |
        v
ecommerceDevolucion
        |
        v
Evaluar respuesta funcional
        |
        +---- Resultado indeterminado
        |             |
        |             v
        |       Verificar / conciliar
        |
        v
Registrar devolución confirmada
        |
        v
Seguimiento financiero

Este diagrama representa una secuencia recomendada para el integrador.

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


11. Devoluciones totales y parciales

El WSDL confirma expresamente que ecommerceDevolucion contempla ambas modalidades.

11.1. Devolución total

Una devolución total solicita reintegrar el importe completo de la operación original.

Ejemplo conceptual:

Concepto

Importe

Venta original

$1,250.00

Devolución solicitada

$1,250.00

Importe neto después de la devolución

$0.00

Este resultado es un ejemplo contable simplificado y supone que la devolución fue efectivamente procesada.

11.2. Devolución parcial

Una devolución parcial solicita reintegrar únicamente una parte del importe original.

Ejemplo conceptual:

Concepto

Importe

Venta original

$1,250.00

Devolución solicitada

$450.00

Importe neto después de la devolución

$800.00

Este resultado también supone que la devolución fue confirmada.

11.3. Múltiples devoluciones parciales

El WSDL no confirma si pueden realizarse múltiples devoluciones parciales sobre una misma venta.

Por tanto, el siguiente escenario debe considerarse una posibilidad pendiente de validación, no una funcionalidad confirmada:

Operación

Importe

Acumulado

Venta original

$1,250.00

—

Primera devolución

$300.00

$300.00

Segunda devolución

$450.00

$750.00

Tercera devolución

$500.00

$1,250.00

La aceptación de este comportamiento depende de las reglas de OEL.

11.4. Control del importe disponible

Como recomendación de diseño, el sistema del comercio puede mantener un control interno del importe potencialmente disponible para devolución.

Fórmula conceptual:

Importe disponible para devolución
    =
Importe original
    -
Total de devoluciones confirmadas

Esta fórmula es una regla contable simplificada.

No sustituye las validaciones del Gateway ni contempla ajustes, comisiones, propinas u otras condiciones que pudieran aplicar.


12. Relación con ecommerceVenta

El método ecommerceVenta permite solicitar una venta directa.

El método ecommerceDevolucion permite solicitar la devolución total o parcial de un cargo.

Información potencialmente relacionada

La respuesta de ecommerceVenta puede incluir:

  • comercioId.

  • transaccionId.

  • monto.

  • codigoAprobacion.

  • referenciaTransaccionBancaria.

La solicitud de ecommerceDevolucion incluye:

  • comercioId.

  • monto.

  • transaccionId.

  • codigoAprobacion.

  • referencia.

Estos campos ofrecen posibles elementos para correlacionar ambas operaciones.

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

Recomendación

Conservar los identificadores devueltos por ecommerceVenta y confirmar con OEL cuáles deben utilizarse en la solicitud de devolución.


13. Diferencias respecto de ecommerceCancelacion

Aunque ambos métodos comparten una estructura de campos equivalente, representan operaciones distintas.

Característica

ecommerceCancelacion

ecommerceDevolucion

Finalidad declarada

Cancelación de un cargo

Devolución de un cargo

Tipo Request

cCancelacionReq

cDevolucionReq

Parámetros Request

12

12

Tipo Response

cCancelacionResp

cDevolucionResp

Parámetros Response

15

15

Operación total

Sujeto a reglas operativas

Contemplada expresamente

Operación parcial

No especificada en el WSDL

Contemplada expresamente

SOAPAction

Específica de cancelación

Específica de devolución

Diferencia fundamental

ecommerceDevolucion tiene una descripción contractual que contempla expresamente la devolución total o parcial.

En cambio, el WSDL no establece expresamente que ecommerceCancelacion admita cancelaciones parciales.

Esto no significa que las cancelaciones parciales sean necesariamente imposibles; significa que esa capacidad no está confirmada por el contrato disponible.

Selección del método

El integrador no debe seleccionar entre cancelación y devolución basándose únicamente en la preferencia comercial.

Debe considerar el estado real de la transacción y las reglas operativas de OEL.


14. Tiempo de procesamiento y disponibilidad de fondos

Una devolución puede involucrar distintas etapas de procesamiento.

Es importante distinguir entre:

  1. La recepción de la solicitud.

  2. La respuesta funcional del Gateway.

  3. El procesamiento financiero correspondiente.

  4. La actualización de los registros bancarios.

  5. La disponibilidad de los fondos para el tarjetahabiente.

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

Tampoco establece un plazo uniforme para la disponibilidad de fondos.

Recomendación de comunicación al comprador

El comercio no debería informar que el dinero ya está disponible en la cuenta del comprador basándose únicamente en el envío de la solicitud.

La comunicación debe corresponder al estado efectivamente confirmado.


15. Manejo de errores

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

Escenario

Tratamiento recomendado

Devolución confirmada como satisfactoria

Registrar el resultado y actualizar el estado comercial.

Devolución confirmada como rechazada

Registrar el rechazo sin descontar el importe como devuelto.

Venta original no localizada

Revisar los identificadores enviados.

Operación no elegible

Verificar el estado y las reglas aplicables.

Importe superior al permitido

Revisar el importe y las devoluciones anteriores.

Token inválido o consumido

Verificar el resultado del intento antes de generar una nueva operación.

Error de autenticación

Resolver el problema antes de continuar.

SOAP Fault

Registrar el error técnico y evaluar si pudo existir procesamiento.

Timeout

Mantener el resultado como indeterminado hasta verificarlo.

Respuesta incompleta

No inferir devolución satisfactoria.

Solicitud duplicada

Evitar reintentos automáticos hasta verificar el estado.

Los escenarios anteriores son recomendaciones de integración.

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


16. Prevención de devoluciones duplicadas

Una devolución puede tener consecuencias financieras.

Por ello, los reintentos deben controlarse cuidadosamente.

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

Recomendaciones

  1. Registrar cada solicitud de devolución.

  2. Relacionarla con la venta original.

  3. Conservar los identificadores enviados.

  4. Registrar el importe solicitado.

  5. Registrar los códigos y mensajes recibidos.

  6. Mantener el historial de devoluciones confirmadas.

  7. Distinguir entre resultados confirmados e indeterminados.

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

Manejo de timeout

Ante una interrupción de comunicación:

  • No asumir que la devolució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.


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 cDevolucionReq no incluye campos para número de tarjeta, fecha de vencimiento o código de seguridad.

Esto permite solicitar la devolución 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 de la devolución.

  • 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 devoluciones a usuarios y procesos autorizados.

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.7. Controles antifraude

Como recomendación de arquitectura, el comercio puede implementar:

  • Límites de importe por usuario.

  • Autorización adicional para devoluciones elevadas.

  • Registro de motivos de devolución.

  • Conciliación de importes.

  • Auditoría de solicitudes.

  • Alertas por devoluciones repetidas.

Estas medidas son recomendaciones para el integrador y no funcionalidades confirmadas del Gateway.


18. Restricciones y limitaciones conocidas

El WSDL no especifica:

  • Estados de transacción elegibles.

  • Plazos máximos para solicitar devoluciones.

  • Moneda.

  • Importes mínimos o máximos.

  • Número máximo de devoluciones parciales.

  • Importe máximo acumulado.

  • Reglas exactas de correlación con la venta 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 disponibilidad de fondos.

  • 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 devolución.

  2. Estados de transacción elegibles.

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

  4. Si pueden realizarse múltiples devoluciones parciales.

  5. Importe máximo acumulado permitido.

  6. Si el importe acumulado puede superar el de la venta original.

  7. Si monto debe expresarse en la misma moneda de la venta.

  8. Si debe utilizarse el mismo transaccionId.

  9. Si codigoAprobacion es obligatorio funcionalmente.

  10. Qué identificadores permiten localizar la venta 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. Plazos de disponibilidad de fondos.

  31. Diferencias operativas respecto de ecommerceCancelacion.

  32. Requisitos de certificación y pruebas.


20. Métodos relacionados

Método

Relación

ecommerceSessionID

Genera el token temporal de autenticación.

ecommerceVenta

Solicita una venta directa.

ecommercePreAutorizacion

Solicita una preautorización.

ecommercePostAutorizacion

Solicita una postautorización.

ecommercePreCancelacion

Solicita una precancelación.

ecommerceCancelacion

Solicita una cancelación de cargo.

ecommerceReversa

Solicita una reversa.


21. Referencias técnicas

Contrato: OpGateway.xml

Definiciones utilizadas:

  • ecommerceDevolucion.

  • cDevolucionReq.

  • ecommerceDevolucionResponse.

  • cDevolucionResp.

  • OpHeader.

  • SOAPAction de ecommerceDevolucion.

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; confirmada la funcionalidad de devolución total o parcial. Pendientes de confirmación las reglas de correlación, vigencia, devoluciones múltiples y efectos financieros.

¿Listo para integrar?

Comienza en ambiente de desarrollo, valida tus primeras operaciones y prepara tu integración para certificación. Cuando el flujo este completo, podrás solicitar el paso a produccion.

¿Listo para integrar?

Comienza en ambiente de desarrollo, valida tus primeras operaciones y prepara tu integración para certificación. Cuando el flujo este completo, podrás solicitar el paso a produccion.

Create a free website with Framer, the website builder loved by startups, designers and agencies.