ecommercePreAutorizacion

1. Descripción general

El método ecommercePreAutorizacion permite solicitar la preautorización de un cargo a una tarjeta de crédito o débito mediante el servicio de comercio electrónico de OpGateway.

Esta operación está destinada a integraciones en las que el comercio necesita solicitar una autorización inicial antes de ejecutar una operación posterior relacionada con el pago.

A diferencia de ecommerceVenta, que solicita una venta directa, ecommercePreAutorizacion forma parte de un esquema de procesamiento en etapas.

El WSDL también define los métodos ecommercePostAutorizacion y ecommercePreCancelacion, que permiten solicitar operaciones posteriores relacionadas con el ciclo de preautorización.

Consideración importante

Una respuesta satisfactoria de preautorización no debe interpretarse automáticamente como una venta finalizada, una liquidación bancaria o una transferencia definitiva de fondos.

2. Casos de uso

La preautorización puede resultar útil en modelos comerciales que requieren separar la autorización inicial del procesamiento posterior de un pago.

Algunos escenarios ilustrativos son:

Estos ejemplos describen posibles usos de una preautorización. No implican que todos estos modelos comerciales estén habilitados automáticamente en OEL, ni que el procesador admita cualquier política de captura o ajuste de importes.

La disponibilidad depende de las condiciones comerciales, bancarias y técnicas aplicables.

3. Especificaciones técnicas

3.1. Namespace

3.2. Endpoint definido en el WSDL

La dirección corresponde al servicio publicado en el contrato. Los ambientes y sus configuraciones se documentarán en el apartado correspondiente.

3.3. SOAPAction

3.4. Elementos SOAP

4. Autenticación

La operación utiliza los mecanismos de autenticación definidos para OpGateway.

4.1. Encabezado SOAP OpHeader

El encabezado contiene:

Ejemplo:

<soap:Header>
  <OpHeader xmlns="https://servidorseguro.operacionesenlinea.com/">
    <OpKey1>CLAVE_1_ASIGNADA</OpKey1>
    <OpKey2>CLAVE_2_ASIGNADA</OpKey2>
  </OpHeader>

4.2. Credenciales del comercio

El cuerpo de la solicitud utiliza:

• comercioId: identificador del comercio.

• contrasena: contraseña permanente o token temporal.

4.3. Autenticación con token temporal

Cuando la preautorización se ejecuta desde un navegador, puede utilizarse un token generado previamente mediante ecommerceSessionID.

El token:

1. Se obtiene mediante una solicitud autenticada con las credenciales permanentes del comercio.

2. Se devuelve en el campo sessionId.

3. Se utiliza como valor del campo contrasena en ecommercePreAutorizacion.

4. Es de un solo uso.

Ejemplo:

<comercioId>12345</comercioId>
<contrasena>TOKEN_UN_SOLO_USO_XYZ123</contrasena>

El nombre del campo permanece como contrasena.

5. Parámetros de solicitud (Request)

La operación utiliza el modelo cTCReq, compartido con ecommerceVenta.

Los siguientes 22 parámetros se presentan en el orden exacto definido por el WSDL.

6. Descripción de los parámetros principales

6.1. comercioId

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

El valor debe corresponder a un comercio autorizado para utilizar el servicio.

6.2. contrasena

Credencial utilizada para autenticar la solicitud.

Puede contener la contraseña permanente del comercio o un token temporal obtenido mediante ecommerceSessionID.

Para integraciones desde navegador se recomienda utilizar el token temporal, evitando exponer la contraseña permanente.

6.3. modo

Parámetro de modo de operación.

6.4. monto

Importe de la preautorización solicitada.

Ejemplo:

<monto>1250.00</monto>

La postautorización posterior le permite efectuar una captura parcial, superior o diferente del importe inicialmente solicitado.

6.5. propina

Importe de propina relacionado con la operación.

Ejemplo con valor explícito:

<propina>0.00</propina>

6.6. transaccionId

Identificador de la transacción proporcionado por el integrador.

Se recomienda asignar un identificador único a cada operación lógica de preautorización.

Ejemplo:

<transaccionId>PREAUTH-DEMO-000001</transaccionId>

6.7. referencia

Referencia comercial o administrativa asociada con la operación.

Tipo: string

Puede utilizarse para facilitar la relación entre la preautorización y los registros internos del comercio.

6.8. Datos de tarjeta

La solicitud incluye los siguientes campos:

6.9. dirIp

Dirección IP asociada con la operación.

Tipo: string

IP del origen de la transacción.

6.10. Diferimiento de pagos

Los parámetros diferimiento, numeroPagos y plan están presentes en la estructura compartida cTCReq.

Sin embargo, solo deben utilizarse en el caso de que se quiera aplicar alguna modalidad de financiamiento o pagos diferidos.

6.11. Información 3D Secure

Los campos xid, cavv, eci y status_3d permiten incorporar datos relacionados con autenticación 3D Secure.

El proceso completo se documentará en el apartado 3D Secure.

6.12. subcomercio

Campo de tipo string destinado a proporcionar información relacionada con un subcomercio.

7. Ejemplo de solicitud SOAP 1.1

El siguiente ejemplo representa una solicitud estructural de preautorización utilizando un token temporal de un solo uso.

Encabezados HTTP

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

Consideraciones del ejemplo

1. Todos los datos son ficticios.

2. El valor de contrasena representa un token obtenido previamente mediante ecommerceSessionID.

3. El ejemplo respeta el orden de los elementos incluidos conforme a cTCReq.

4. propina se envía explícitamente con valor 0.00.

5. tarjeta contiene un marcador ilustrativo, no un número de tarjeta válido.

6. 192.0.2.10 es una dirección IP reservada para documentación.

7. El ejemplo no es una solicitud lista para ejecutarse en un ambiente real.

Ejemplo de incorporación de 3D Secure

Cuando se requiera enviar resultados válidos de autenticación 3D Secure, los elementos deberán incorporarse en el orden definido por el WSDL:

<xid>VALOR_XID_OBTENIDO</xid>
<cavv>VALOR_CAVV_OBTENIDO</cavv>
<eci>VALOR_ECI_OBTENIDO</eci>
<status_3d>VALOR_ESTADO_3DS_OBTENIDO</status_3d>

Los valores reales deben proceder del mecanismo de autenticación correspondiente y no deben inventarse.

8. Parámetros de respuesta (Response)

El método devuelve un objeto ecommercePreAutorizacionResult de tipo cTCResp.

La respuesta contiene 11 campos, en el siguiente orden:

8.1. comercioId

Permite identificar el comercio al que corresponde la respuesta.

Se recomienda comprobar que coincida con el identificador enviado.

8.2. transaccionId

Identificador de la transacción devuelto por el servicio.

Es recomendable conservarlo para relacionar la preautorización con las operaciones posteriores.

8.3. fechaTransaccion y horaTransaccion

Campos de tipo string.

8.4. monto

Importe reportado en la respuesta.

El integrador debe comprobar su correspondencia con la solicitud y las reglas operativas aplicables.

8.5. codigoRespuesta

Código funcional de respuesta.

Su interpretación debe realizarse mediante el catálogo oficial de OEL.

8.6. procReturnMsg

Mensaje relacionado con el procesamiento de la operación.

8.7. ccErrorCode

Código complementario de resultado o error.

8.8. ccReturnMsg

Mensaje complementario devuelto por el Gateway.

8.9. codigoAprobacion

Código de aprobación cuando se encuentre disponible.

Su presencia puede ser relevante para el seguimiento de la preautorización y para operaciones posteriores.

8.10. referenciaTransaccionBancaria

Referencia bancaria asociada con la operación.

Se recomienda conservarla para trazabilidad y conciliación.

9. Ejemplo de respuesta SOAP 1.1

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

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

Notas

• La respuesta es ilustrativa.

• Los valores no representan una operación bancaria real.

• Los códigos 0 no deben interpretarse automáticamente como aprobación.

10. Flujo de una preautorización

El siguiente flujo representa una propuesta de integración basada en las operaciones disponibles.

Etapa 1. Preparación

El sistema del comercio crea una operación interna y determina el importe que desea preautorizar.

Se recomienda asignar un identificador único y registrar la referencia comercial.

Etapa 2. Autenticación

Si la operación se realizará desde un navegador, el backend obtiene un token mediante ecommerceSessionID.

Etapa 3. Construcción de la solicitud

La aplicación prepara el objeto cTCReq con los datos necesarios.

Etapa 4. Autenticación 3D Secure

Cuando corresponda, se ejecuta el proceso de autenticación definido para la integración y se incorporan sus resultados válidos.

Etapa 5. Envío

La aplicación invoca ecommercePreAutorizacion.

Etapa 6. Interpretación

El integrador recibe cTCResp y evalúa los códigos y mensajes conforme a los catálogos oficiales.

Etapa 7. Registro

Se conservan los identificadores, el importe y los datos de referencia necesarios para seguimiento.

Etapa 8. Operación posterior

Según las reglas aplicables y el resultado confirmado, el comercio podrá solicitar una operación posterior mediante un método como:

• ecommercePostAutorizacion.

• ecommercePreCancelacion.

11. Relación con ecommercePostAutorizacion

El método ecommercePostAutorizacion existe en el WSDL y está descrito como una operación de postautorización de un cargo mediante comercio electrónico.

Desde el punto de vista funcional, constituye una operación posterior potencialmente relacionada con una preautorización previa.

Estas reglas se documentarán y validarán al abordar ecommercePostAutorizacion.

Información recomendada para conservar

Tras recibir una preautorización, se recomienda almacenar de forma segura:

12. Relación con ecommercePreCancelacion

El WSDL también define ecommercePreCancelacion, descrito como un método para procesar la precancelación de un cargo mediante comercio electrónico.

Esta operación podría utilizarse en escenarios donde se necesite solicitar la cancelación de una preautorización previa.

13. Manejo de errores

El método puede producir respuestas funcionales o errores técnicos.

Escenarios recomendados

Catálogos de respuesta

El WSDL declara los campos:

• codigoRespuesta.

• ccErrorCode.

• procReturnMsg.

• ccReturnMsg.io98o

La implementación debe basarse en códigos oficiales, no en interpretaciones de ejemplo.

14. Prevención de preautorizaciones duplicadas

Una preautorización puede afectar temporalmente la disponibilidad de fondos o crédito del tarjetahabiente, dependiendo de las reglas del emisor y del procesador.

Por esta razón, es importante evitar solicitudes duplicadas.

Identificación de operaciones

Se recomienda asignar un transaccionId único y relacionarlo con el pedido o reserva del comercio.

Reintentos

El identificador de transaccionId debe ser unico por operación, en consecuencia, reenviar la misma solicitud no debe considerarse automáticamente seguro.

Resultado indeterminado

Ante un timeout:

1. Conservar el identificador de la operación.

2. Registrar que el resultado es desconocido.

3. Consultar o conciliar el estado mediante los mecanismos habilitados.

4. Evitar enviar una nueva preautorización hasta determinar el resultado de la anterior.

Un nuevo token de sesión no elimina el riesgo de duplicar una operación financiera.

15. Consideraciones de seguridad

15.1. Protección de credenciales

Las credenciales permanentes del comercio deben permanecer protegidas en el backend.

Para solicitudes desde navegador, utilizar el mecanismo de token temporal cuando corresponda.

15.2. Protección del token

El token de ecommerceSessionID debe tratarse como una credencial temporal.

No debe almacenarse en registros públicos ni reutilizarse.

15.3. Datos de tarjeta

La operación incluye campos que pueden transportar información sensible de tarjeta.

El integrador debe evaluar los controles PCI DSS aplicables a la arquitectura implementada.

15.4. Registros

Se recomienda conservar los identificadores, importes y resultados de la operación, evitando registrar contraseñas, tokens activos o datos sensibles de tarjeta.

15.5. Autenticación 3D Secure

Cuando corresponda, los datos 3D Secure deben provenir de un proceso válido de autenticación.

No deben fabricarse ni reutilizarse arbitrariamente valores de autenticación.

16. Diferencias respecto de ecommerceVenta

La diferencia principal no está en los campos del mensaje, sino en la operación que se solicita al Gateway y su finalidad funcional.

17. Métodos relacionados

Las diferencias entre cancelación, precancelación y reversa se documentarán en sus páginas individuales.