OpDevolucion

El método OpDevolucion permite solicitar la devolución de un importe asociado a una operación de cargo previamente procesada mediante el Gateway de Pagos de OEL.

Este método está orientado a operaciones en las que el comercio necesita devolver al tarjetahabiente un importe relacionado con una transacción anterior, de acuerdo con las condiciones y reglas establecidas por el procesador de pagos.

Para realizar la solicitud, el comercio debe proporcionar sus credenciales de autenticación, el importe de la devolución y la información necesaria para identificar la operación correspondiente.

A diferencia de OpVenta, este método no requiere transmitir nuevamente los datos sensibles de la tarjeta ni la información EMV obtenida durante la operación original.

Importante: las devoluciones están sujetas a las reglas del procesador de pagos y las instituciones financieras participantes. La devolución puede ser total o parcial. El tiempo necesario para que el importe sea reflejado en la cuenta del tarjetahabiente varia dependiendo del emisor de la tarjeta, el plazo comun es entre 24 y 72 horas.

Información del servicio

Autenticación

La operación requiere autenticación mediante la cabecera SOAP OpHeader, utilizando las credenciales asignadas al comercio por OEL.

Adicionalmente, el cuerpo de la solicitud debe incluir los parámetros comercioId y contrasena, utilizados para identificar al comercio que solicita la devolución.

Las credenciales deben mantenerse protegidas y no incorporarse en repositorios públicos, registros de diagnóstico ni ejemplos de documentación.

Parámetros de solicitud (Request)

El método recibe un objeto request de tipo cDevolucionReq, compuesto por 12 parámetros.

Consideraciones sobre los parámetros

transaccionId

Permite identificar la transacción dentro del sistema del comercio.

Para realizar una devolución es necesario establecer la relación con el cargo correspondiente. Se debe utilizar el mismo identificador de la venta original a la cual se va a aplicar la devolución.

codigoAprobacion

Representa el código de aprobación bancaria asociado a una operación. Este parámetro es obligatorio y corresponde al código de aprobación de la operación original.

monto

Representa el importe que el comercio solicita devolver. Se permite aplicar devoluciones por el importe total o por importe inferior al cargo original, no se permite realizar múltiples devoluciones sobre una misma operación.

firma

Debe recabarse la firma manuscrita del tarjetahabiente y ser enviada mediante este campo.

Ejemplo XML Request — SOAP 1.1

El siguiente ejemplo ilustra una solicitud de devolución utilizando valores ficticios y simbólicos.

No representa una transacción ejecutable sin credenciales válidas y los identificadores correspondientes a una operación real.

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

  <soap:Header>
    <OpHeader>
      <OpKey1>CLAVE_1_ASIGNADA</OpKey1>
      <OpKey2>CLAVE_2_ASIGNADA</OpKey2>
    </OpHeader>
  </soap:Header>

  <soap:Body>
    <OpDevolucion>
      <request>
        <comercioId>12345</comercioId>
        <contrasena>CLAVE_COMERCIO</contrasena>
        <modo>P</modo>
        <monto>250.00</monto>
        <transaccionId>ID_TRANSACCION</transaccionId>
        <codigoAprobacion>123456</codigoAprobacion>
        <referencia>DEVOL000001</referencia>
        <firma>FIRMA_SEGUN_ESPECIFICACION_OEL</firma>
        <dirIp>192.0.2.10</dirIp>
        <deviceId>12345678</deviceId>
        <subcomercio>SUBCOMERCIO_ID</subcomercio>
        <version>VERSION_SDK</version>
      </request>
    </OpDevolucion>

Los valores son exclusivamente ilustrativos. El campo firma contiene un marcador simbólico y no representa una firma válida. El importe de 250.00 es solo un ejemplo.

Para enviar la solicitud mediante SOAP 1.1, utiliza las siguientes cabeceras HTTP:

Parámetros de respuesta (Response)

El servicio devuelve un mensaje SOAP que contiene el elemento OpDevolucionResponse y, dentro de él, el objeto OpDevolucionResult, de tipo cDevolucionResp.

La respuesta está compuesta por 15 parámetros.

Identificación y resultado de la operación

Información de afiliación

Ejemplo XML Response — Devolución aprobada

El siguiente ejemplo representa una respuesta ficticia de una solicitud de devolución aprobada.

La estructura corresponde al contrato SOAP. Los códigos y mensajes utilizados son ilustrativos y requieren validación mediante respuestas reales del servicio.

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

  <soap:Body>
    <OpDevolucionResponse>
      <OpDevolucionResult>
        <comercioId>12345</comercioId>
        <terminalId>12345678</terminalId>
        <transaccionId>ID_TRANSACCION</transaccionId>
        <fechaTransaccion>10/16/26</fechaTransaccion>
        <horaTransaccion>10:30:00</horaTransaccion>
        <monto>250.00</monto>
        <referencia>DEVOL000001</referencia>
        <numeroControl>CTRL000001</numeroControl>
        <codigoRespuesta>0</codigoRespuesta>
        <procReturnMsg>00</procReturnMsg>
        <ccErrorCode>0</ccErrorCode>
        <ccReturnMsg>APROBADA</ccReturnMsg>
        <codigoAprobacion>123456</codigoAprobacion>
        <afiliacion>AFILIACION_ID</afiliacion>
        <afiliacionEmpresa>EMPRESA_ID</afiliacionEmpresa>
      </OpDevolucionResult>
    </OpDevolucionResponse>

Códigos de respuesta

Se establecen los siguientes valores para codigoRespuesta en el método OpDevolucion:

El servicio también puede devolver información del procesador mediante procReturnMsg, ccErrorCode y ccReturnMsg.

Consideraciones técnicas

• Operación original: la solicitud debe identificar correctamente el cargo asociado a la devolución.

• Importe: verificar que el monto solicitado cumpla con las condiciones establecidas por el procesador de pagos.

• Devoluciones parciales: Se permite devolver el total o una parte del importe original y no pueden realizarse múltiples devoluciones sobre la misma transacción.

• Código de aprobación: conservar el código devuelto durante la autorización original.

• Seguridad: proteger las credenciales de autenticación y transmitir las solicitudes exclusivamente mediante HTTPS.

• Datos sensibles: este método no requiere reenviar el PAN, Track 2 ni los datos EMV de la tarjeta.

• Control de duplicados: ante una respuesta indeterminada, verificar el estado de la operación antes de intentar nuevamente la devolución.

• Conciliación: conservar los identificadores, fechas, importes y resultados necesarios para la trazabilidad y conciliación de las operaciones.

• Acreditación: una devolución aceptada por el servicio no implica necesariamente que el importe ya se encuentre disponible en la cuenta del tarjetahabiente.

Relación con otros métodos