Inicio
Pagos Presenciales
Tokenización
Aliados
Ambientes
Referencia API
Recursos
ecommerceDevolucion
Devolución Total o Parcial de un Cargo de Comercio Electrónico
2
min read
2
2
min read
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 |
|
Método |
|
Tipo de operación | Devolución total o parcial |
Protocolo | SOAP 1.1 / SOAP 1.2 |
Transporte | HTTPS |
Estilo SOAP | Document/literal |
Tipo Request |
|
Tipo Response |
|
Parámetros Request | 12 |
Parámetros Response | 15 |
Encabezado SOAP |
|
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 |
|
Contenedor de entrada |
|
Operación de respuesta |
|
Contenedor de resultado |
|
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 |
|---|---|---|---|
|
| 0 | Primera clave del encabezado SOAP. |
|
| 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:
El comercio solicita un token mediante
ecommerceSessionID.El Gateway devuelve el token en
sessionId.El integrador coloca el token en
contrasena.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 |
|
| 1 | Identificador del comercio. |
2 |
|
| 0 | Contraseña permanente o token temporal. |
3 |
|
| 0 | Modo de operación. |
4 |
|
| 1 | Importe de la devolución solicitada. |
5 |
|
| 0 | Identificador de transacción. |
6 |
|
| 0 | Código de aprobación relacionado con la operación original. |
7 |
|
| 0 | Referencia comercial o administrativa. |
8 |
|
| 0 | Dato de firma cuyo significado debe confirmarse. |
9 |
|
| 0 | Dirección IP relacionada con la solicitud. |
10 |
|
| 0 | Identificador de dispositivo. |
11 |
|
| 0 | Dato relacionado con el subcomercio. |
12 |
|
| 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
Todos los valores son ficticios.
La solicitud representa una devolución parcial ilustrativa.
El token debe ser nuevo y de un solo uso.
Los identificadores incluidos ilustran una posible correlación con la venta original.
El WSDL no confirma que esos identificadores sean suficientes para procesar una devolución real.
Se omite
firmaporque no existe una regla verificada para construirla.Se omiten los demás parámetros opcionales cuyo uso no está definido.
El orden de los elementos corresponde a
cDevolucionReq.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 |
|
| 1 | Identificador del comercio. |
2 |
|
| 0 | Identificador de terminal reportado por el servicio. |
3 |
|
| 0 | Identificador de transacción. |
4 |
|
| 0 | Fecha de la operación. |
5 |
|
| 0 | Hora de la operación. |
6 |
|
| 1 | Importe reportado. |
7 |
|
| 0 | Referencia de la operación. |
8 |
|
| 0 | Número de control relacionado con el procesamiento. |
9 |
|
| 1 | Código funcional de respuesta. |
10 |
|
| 0 | Mensaje del procesamiento. |
11 |
|
| 1 | Código complementario de resultado o error. |
12 |
|
| 0 | Mensaje complementario del Gateway. |
13 |
|
| 0 | Código de aprobación, cuando corresponda. |
14 |
|
| 0 | Dato de afiliación reportado por el servicio. |
15 |
|
| 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
0no 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 financieroEste 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 confirmadasEsta 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 |
|
|
Parámetros Request | 12 | 12 |
Tipo Response |
|
|
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:
La recepción de la solicitud.
La respuesta funcional del Gateway.
El procesamiento financiero correspondiente.
La actualización de los registros bancarios.
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
Registrar cada solicitud de devolución.
Relacionarla con la venta original.
Conservar los identificadores enviados.
Registrar el importe solicitado.
Registrar los códigos y mensajes recibidos.
Mantener el historial de devoluciones confirmadas.
Distinguir entre resultados confirmados e indeterminados.
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:
Qué tipos de transacción admiten devolución.
Estados de transacción elegibles.
Plazo máximo para solicitar una devolución.
Si pueden realizarse múltiples devoluciones parciales.
Importe máximo acumulado permitido.
Si el importe acumulado puede superar el de la venta original.
Si
montodebe expresarse en la misma moneda de la venta.Si debe utilizarse el mismo
transaccionId.Si
codigoAprobaciones obligatorio funcionalmente.Qué identificadores permiten localizar la venta original.
Significado y formato de
firma.Si
firmadebe generarse mediante otro procedimiento.Catálogo de valores de
modo.Significado de
deviceId.Reglas de
subcomercio.Significado de
version.Reglas de
dirIp.Moneda y límites de importe.
Catálogo de
codigoRespuesta.Catálogo de
ccErrorCode.Significado de
numeroControl.Significado de
afiliacion.Significado de
afiliacionEmpresa.Formato y zona horaria de fecha y hora.
Comportamiento ante solicitudes duplicadas.
Procedimiento ante timeout.
Vigencia y consumo del token temporal.
Manejo seguro de
OpHeaderdesde navegador.Políticas CORS aplicables.
Plazos de disponibilidad de fondos.
Diferencias operativas respecto de
ecommerceCancelacion.Requisitos de certificación y pruebas.
20. Métodos relacionados
Método | Relación |
|---|---|
| Genera el token temporal de autenticación. |
| Solicita una venta directa. |
| Solicita una preautorización. |
| Solicita una postautorización. |
| Solicita una precancelación. |
| Solicita una cancelación de cargo. |
| 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 |
|
Método |
|
Tipo de operación | Devolución total o parcial |
Protocolo | SOAP 1.1 / SOAP 1.2 |
Transporte | HTTPS |
Estilo SOAP | Document/literal |
Tipo Request |
|
Tipo Response |
|
Parámetros Request | 12 |
Parámetros Response | 15 |
Encabezado SOAP |
|
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 |
|
Contenedor de entrada |
|
Operación de respuesta |
|
Contenedor de resultado |
|
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 |
|---|---|---|---|
|
| 0 | Primera clave del encabezado SOAP. |
|
| 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:
El comercio solicita un token mediante
ecommerceSessionID.El Gateway devuelve el token en
sessionId.El integrador coloca el token en
contrasena.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 |
|
| 1 | Identificador del comercio. |
2 |
|
| 0 | Contraseña permanente o token temporal. |
3 |
|
| 0 | Modo de operación. |
4 |
|
| 1 | Importe de la devolución solicitada. |
5 |
|
| 0 | Identificador de transacción. |
6 |
|
| 0 | Código de aprobación relacionado con la operación original. |
7 |
|
| 0 | Referencia comercial o administrativa. |
8 |
|
| 0 | Dato de firma cuyo significado debe confirmarse. |
9 |
|
| 0 | Dirección IP relacionada con la solicitud. |
10 |
|
| 0 | Identificador de dispositivo. |
11 |
|
| 0 | Dato relacionado con el subcomercio. |
12 |
|
| 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
Todos los valores son ficticios.
La solicitud representa una devolución parcial ilustrativa.
El token debe ser nuevo y de un solo uso.
Los identificadores incluidos ilustran una posible correlación con la venta original.
El WSDL no confirma que esos identificadores sean suficientes para procesar una devolución real.
Se omite
firmaporque no existe una regla verificada para construirla.Se omiten los demás parámetros opcionales cuyo uso no está definido.
El orden de los elementos corresponde a
cDevolucionReq.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 |
|
| 1 | Identificador del comercio. |
2 |
|
| 0 | Identificador de terminal reportado por el servicio. |
3 |
|
| 0 | Identificador de transacción. |
4 |
|
| 0 | Fecha de la operación. |
5 |
|
| 0 | Hora de la operación. |
6 |
|
| 1 | Importe reportado. |
7 |
|
| 0 | Referencia de la operación. |
8 |
|
| 0 | Número de control relacionado con el procesamiento. |
9 |
|
| 1 | Código funcional de respuesta. |
10 |
|
| 0 | Mensaje del procesamiento. |
11 |
|
| 1 | Código complementario de resultado o error. |
12 |
|
| 0 | Mensaje complementario del Gateway. |
13 |
|
| 0 | Código de aprobación, cuando corresponda. |
14 |
|
| 0 | Dato de afiliación reportado por el servicio. |
15 |
|
| 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
0no 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 financieroEste 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 confirmadasEsta 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 |
|
|
Parámetros Request | 12 | 12 |
Tipo Response |
|
|
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:
La recepción de la solicitud.
La respuesta funcional del Gateway.
El procesamiento financiero correspondiente.
La actualización de los registros bancarios.
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
Registrar cada solicitud de devolución.
Relacionarla con la venta original.
Conservar los identificadores enviados.
Registrar el importe solicitado.
Registrar los códigos y mensajes recibidos.
Mantener el historial de devoluciones confirmadas.
Distinguir entre resultados confirmados e indeterminados.
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:
Qué tipos de transacción admiten devolución.
Estados de transacción elegibles.
Plazo máximo para solicitar una devolución.
Si pueden realizarse múltiples devoluciones parciales.
Importe máximo acumulado permitido.
Si el importe acumulado puede superar el de la venta original.
Si
montodebe expresarse en la misma moneda de la venta.Si debe utilizarse el mismo
transaccionId.Si
codigoAprobaciones obligatorio funcionalmente.Qué identificadores permiten localizar la venta original.
Significado y formato de
firma.Si
firmadebe generarse mediante otro procedimiento.Catálogo de valores de
modo.Significado de
deviceId.Reglas de
subcomercio.Significado de
version.Reglas de
dirIp.Moneda y límites de importe.
Catálogo de
codigoRespuesta.Catálogo de
ccErrorCode.Significado de
numeroControl.Significado de
afiliacion.Significado de
afiliacionEmpresa.Formato y zona horaria de fecha y hora.
Comportamiento ante solicitudes duplicadas.
Procedimiento ante timeout.
Vigencia y consumo del token temporal.
Manejo seguro de
OpHeaderdesde navegador.Políticas CORS aplicables.
Plazos de disponibilidad de fondos.
Diferencias operativas respecto de
ecommerceCancelacion.Requisitos de certificación y pruebas.
20. Métodos relacionados
Método | Relación |
|---|---|
| Genera el token temporal de autenticación. |
| Solicita una venta directa. |
| Solicita una preautorización. |
| Solicita una postautorización. |
| Solicita una precancelación. |
| Solicita una cancelación de cargo. |
| 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 |
|
Método |
|
Tipo de operación | Devolución total o parcial |
Protocolo | SOAP 1.1 / SOAP 1.2 |
Transporte | HTTPS |
Estilo SOAP | Document/literal |
Tipo Request |
|
Tipo Response |
|
Parámetros Request | 12 |
Parámetros Response | 15 |
Encabezado SOAP |
|
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 |
|
Contenedor de entrada |
|
Operación de respuesta |
|
Contenedor de resultado |
|
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 |
|---|---|---|---|
|
| 0 | Primera clave del encabezado SOAP. |
|
| 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:
El comercio solicita un token mediante
ecommerceSessionID.El Gateway devuelve el token en
sessionId.El integrador coloca el token en
contrasena.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 |
|
| 1 | Identificador del comercio. |
2 |
|
| 0 | Contraseña permanente o token temporal. |
3 |
|
| 0 | Modo de operación. |
4 |
|
| 1 | Importe de la devolución solicitada. |
5 |
|
| 0 | Identificador de transacción. |
6 |
|
| 0 | Código de aprobación relacionado con la operación original. |
7 |
|
| 0 | Referencia comercial o administrativa. |
8 |
|
| 0 | Dato de firma cuyo significado debe confirmarse. |
9 |
|
| 0 | Dirección IP relacionada con la solicitud. |
10 |
|
| 0 | Identificador de dispositivo. |
11 |
|
| 0 | Dato relacionado con el subcomercio. |
12 |
|
| 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
Todos los valores son ficticios.
La solicitud representa una devolución parcial ilustrativa.
El token debe ser nuevo y de un solo uso.
Los identificadores incluidos ilustran una posible correlación con la venta original.
El WSDL no confirma que esos identificadores sean suficientes para procesar una devolución real.
Se omite
firmaporque no existe una regla verificada para construirla.Se omiten los demás parámetros opcionales cuyo uso no está definido.
El orden de los elementos corresponde a
cDevolucionReq.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 |
|
| 1 | Identificador del comercio. |
2 |
|
| 0 | Identificador de terminal reportado por el servicio. |
3 |
|
| 0 | Identificador de transacción. |
4 |
|
| 0 | Fecha de la operación. |
5 |
|
| 0 | Hora de la operación. |
6 |
|
| 1 | Importe reportado. |
7 |
|
| 0 | Referencia de la operación. |
8 |
|
| 0 | Número de control relacionado con el procesamiento. |
9 |
|
| 1 | Código funcional de respuesta. |
10 |
|
| 0 | Mensaje del procesamiento. |
11 |
|
| 1 | Código complementario de resultado o error. |
12 |
|
| 0 | Mensaje complementario del Gateway. |
13 |
|
| 0 | Código de aprobación, cuando corresponda. |
14 |
|
| 0 | Dato de afiliación reportado por el servicio. |
15 |
|
| 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
0no 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 financieroEste 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 confirmadasEsta 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 |
|
|
Parámetros Request | 12 | 12 |
Tipo Response |
|
|
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:
La recepción de la solicitud.
La respuesta funcional del Gateway.
El procesamiento financiero correspondiente.
La actualización de los registros bancarios.
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
Registrar cada solicitud de devolución.
Relacionarla con la venta original.
Conservar los identificadores enviados.
Registrar el importe solicitado.
Registrar los códigos y mensajes recibidos.
Mantener el historial de devoluciones confirmadas.
Distinguir entre resultados confirmados e indeterminados.
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:
Qué tipos de transacción admiten devolución.
Estados de transacción elegibles.
Plazo máximo para solicitar una devolución.
Si pueden realizarse múltiples devoluciones parciales.
Importe máximo acumulado permitido.
Si el importe acumulado puede superar el de la venta original.
Si
montodebe expresarse en la misma moneda de la venta.Si debe utilizarse el mismo
transaccionId.Si
codigoAprobaciones obligatorio funcionalmente.Qué identificadores permiten localizar la venta original.
Significado y formato de
firma.Si
firmadebe generarse mediante otro procedimiento.Catálogo de valores de
modo.Significado de
deviceId.Reglas de
subcomercio.Significado de
version.Reglas de
dirIp.Moneda y límites de importe.
Catálogo de
codigoRespuesta.Catálogo de
ccErrorCode.Significado de
numeroControl.Significado de
afiliacion.Significado de
afiliacionEmpresa.Formato y zona horaria de fecha y hora.
Comportamiento ante solicitudes duplicadas.
Procedimiento ante timeout.
Vigencia y consumo del token temporal.
Manejo seguro de
OpHeaderdesde navegador.Políticas CORS aplicables.
Plazos de disponibilidad de fondos.
Diferencias operativas respecto de
ecommerceCancelacion.Requisitos de certificación y pruebas.
20. Métodos relacionados
Método | Relación |
|---|---|
| Genera el token temporal de autenticación. |
| Solicita una venta directa. |
| Solicita una preautorización. |
| Solicita una postautorización. |
| Solicita una precancelación. |
| Solicita una cancelación de cargo. |
| 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.
© 2026 Derechos Reservados
© 2026 Derechos Reservados