OpFirma

El método OpFirma permite enviar al Gateway de Pagos de OEL una solicitud relacionada con la firma de una transacción, proporcionando información del comercio, identificadores de la operación, importe, código de aprobación y el propio parámetro denominado firma.

La solicitud permite asociar el valor de firma con información de una transacción.

Información del servicio

Se recomienda utilizar TLS 1.2 o superior, conforme a los requisitos de seguridad aplicables a la integración.

Autenticación

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

Adicionalmente, el cuerpo de la solicitud contempla comercioId y contrasena.

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 cFirmaReq, compuesto por 10 parámetros.

Consideraciones sobre los parámetros

comercioId

Identifica al comercio que realiza la solicitud. Debe utilizarse el identificador asignado por OEL.

contrasena

Corresponde a la contraseña de autenticación del comercio.

Debe transmitirse mediante conexiones seguras y mantenerse protegida.

transaccionId

Permite identificar la transacción relacionada con la solicitud.

Se requiere utilizar exactamente el identificador de la operación original.

monto

Representa el importe asociado a la solicitud.

Este debe coincidir exactamente con el monto de la transacción original.

codigoAprobacion

Representa un código de aprobación bancaria asociado a la operación.

Es obligatorio para OpFirma y debe corresponder al código devuelto durante la autorización original.

referencia

Permite relacionar la solicitud con una referencia del sistema del comercio.

Debe conservarse la referencia de la transacción original.

firma

Es el parámetro distintivo de este método a traves del cual se envia la firma autografa.

El WSDL establece únicamente lo siguiente:

El servicio espera una cadena Base64 la cual corresponde a una firma manuscrita capturada en pantalla.

Ejemplo XML Request — SOAP 1.1

El siguiente ejemplo muestra la estructura de una solicitud OpFirma utilizando valores ficticios y simbólicos.

El campo firma contiene un marcador ilustrativo. No representa un formato válido confirmado por OEL.

<?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>
    <OpFirma>
      <request>
        <comercioId>12345</comercioId>
        <contrasena>CLAVE_COMERCIO</contrasena>
        <transaccionId>ID_TRANSACCION</transaccionId>
        <monto>500.00</monto>
        <codigoAprobacion>123456</codigoAprobacion>
        <referencia>VENTA000001</referencia>
        <firma>FIRMA_SIMBOLICA</firma>
        <deviceId>12345678</deviceId>
        <subcomercio>SUBCOMERCIO_ID</subcomercio>
        <version>VERSION_SDK</version>
      </request>
    </OpFirma>

Todos los valores son exclusivamente ilustrativos y no representan credenciales, identificadores o datos de firma reales.

Cabeceras HTTP

Para enviar la solicitud mediante SOAP 1.1:

Parámetros de respuesta (Response)

El servicio devuelve un mensaje SOAP que contiene el elemento OpFirmaResponse.

Dentro de este elemento se encuentra OpFirmaResult, de tipo cFirmaResp.

La respuesta contiene 7 parámetros.

Particularidades de la respuesta

A diferencia de otros métodos transaccionales del Gateway, OpFirma no devuelve:

• terminalId

• fechaTransaccion

• horaTransaccion

• monto

• referencia

• numeroControl

• afiliacion

• afiliacionEmpresa

Tampoco devuelve un campo denominado firma ni un identificador específico del registro de firma.

Esta diferencia resulta importante para el diseño de la integración, ya que el integrador no debe esperar recibir una copia de la firma enviada.

Ejemplo XML Response — Resultado ilustrativo

El siguiente ejemplo representa una respuesta ficticia con todos los campos definidos en cFirmaResp.

Los códigos y mensajes utilizados son ilustrativos. No constituyen un catálogo oficial de respuestas de OpFirma.

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

  <soap:Body>
    <OpFirmaResponse>
      <OpFirmaResult>
        <comercioId>12345</comercioId>
        <transaccionId>ID_TRANSACCION</transaccionId>
        <codigoAprobacion>123456</codigoAprobacion>
        <codigoRespuesta>0</codigoRespuesta>
        <procReturnMsg>00</procReturnMsg>
        <ccErrorCode>0</ccErrorCode>
        <ccReturnMsg>MENSAJE_SIMBOLICO</ccReturnMsg>
      </OpFirmaResult>
    </OpFirmaResponse>

Los valores utilizados son exclusivamente ilustrativos.

Códigos de respuesta

Se establecen los siguientes valores para codigoRespuesta en OpFirma:

Estos valores se presentan únicamente como referencia.

Una respuesta aprobada en el contexto de este método indica que la firma fue recibida, fue asociada a una transacción y fue almacenada.

Campos adicionales de resultado

Consideraciones técnicas

Relación con la transacción original

La solicitud contiene transaccionId, monto, codigoAprobacion y referencia.

Estos parámetros permiten relacionar la solicitud con información de una operación anterior.

Formato de la firma

El parámetro firma está definido como string.

Almacenamiento y protección

Dado que este parámetro corresponde a una firma del tarjetahabiente, el tratamiento de la información en todo momento considera los requisitos de privacidad, protección de datos y conservación de evidencias aplicables.

Idempotencia y reintentos

El WSDL no especifica si OpFirma es idempotente.

Ante una falla de comunicación, es necesario reenviar la firma.

Trazabilidad

Se recomienda conservar, conforme a las políticas de seguridad aplicables:

• El identificador de la transacción.

• La referencia de la operación.

• La fecha y hora local de la solicitud.

• El resultado devuelto por el Gateway.

• Los códigos de respuesta del procesador.

El contenido de firma no debe registrarse indiscriminadamente en bitácoras técnicas.

Seguridad

La integración debe utilizar HTTPS y proteger las credenciales de autenticación.

El método no requiere transmitir nuevamente PAN, Track 2 ni información EMV.

Relación con otros métodos

El WSDL no establece una secuencia obligatoria entre OpVenta y OpFirma.

Por lo tanto, no debe asumirse que OpFirma debe invocarse después de todas las ventas ni que constituye un requisito universal para completar una autorización.