ecommerceVenta

1. Descripción

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

Está diseñado para integraciones que necesitan procesar pagos originados desde sitios web, tiendas virtuales y aplicaciones conectadas al Gateway de OEL.

La solicitud permite proporcionar información del comercio, monto, identificadores de la operación, datos de la tarjeta y parámetros complementarios relacionados con modalidades de pago y autenticación 3D Secure.

Como respuesta, el servicio devuelve información de la transacción, importe, códigos funcionales, mensajes del procesamiento y, cuando corresponda, datos de aprobación y referencia bancaria.

Importante: ecommerceVenta solicita la autorización de un cargo. La confirmación de una venta debe basarse en la interpretación de los códigos funcionales oficiales y no únicamente en la recepción de una respuesta HTTP satisfactoria.

2. Información técnica del servicio

Endpoint declarado en el WSDL

La configuración de ambientes y los endpoints habilitados se documentarán posteriormente en el apartado Ambientes.

SOAPAction

Estructura del mensaje

La operación recibe:

<ecommerceVenta xmlns="https://servidorseguro.operacionesenlinea.com/">
  <request>
    <!-- Campos de cTCReq -->
  </request>
</ecommerceVenta>

Y devuelve:

<ecommerceVentaResponse xmlns="https://servidorseguro.operacionesenlinea.com/">
  <ecommerceVentaResult>
    <!-- Campos de cTCResp -->
  </ecommerceVentaResult>
</ecommerceVentaResponse>

3. Autenticación

La operación contempla dos componentes de autenticación:

1. Encabezado SOAP OpHeader.

2. Credenciales del comercio incluidas en el objeto request.

3.1. Encabezado SOAP

El WSDL define el encabezado OpHeader con los siguientes campos:

Ejemplo:

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

3.2. Credenciales del comercio

La solicitud contiene los campos:

3.3. Autenticación mediante ecommerceSessionID

Para integraciones que realizan la operación desde un navegador, se puede utilizar un token temporal generado previamente mediante ecommerceSessionID.

El token se devuelve en el campo sessionId de dicho método y se utiliza como valor de contrasena en ecommerceVenta.

Ejemplo con contraseña permanente:

<comercioId>12345</comercioId>
<contrasena>CONTRASENA_PERMANENTE</contrasena>

Ejemplo con token temporal:

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

No cambia el nombre del campo XML. El token reemplaza directamente el valor de contrasena.

Regla funcional confirmada: el token es de un solo uso. No debe reutilizarse para ejecutar otras operaciones.

1q

4. Parámetros de solicitud (Request)

El método utiliza el tipo cTCReq, compuesto por 22 parámetros.

Los campos se presentan en el orden exacto del WSDL.

5. Descripción detallada de los parámetros

5.1. Identificación del comercio

comercioId

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

• Tipo: int.

• Debe corresponder al comercio autorizado para utilizar el servicio.

contrasena

Credencial utilizada para autenticar al comercio.

Puede contener:

• La contraseña permanente asignada al comercio.

• Un token temporal de un solo uso generado mediante ecommerceSessionID.

5.2. Modo de operación

modo

Campo de tipo string destinado a indicar el modo de operación.

5.3. Información monetaria

monto

Importe de la operación.

• Tipo: decimal.

• No tiene restricciones de mínimo, máximo o número de decimales.

propina

Importe de propina relacionado con la operación.

• Tipo: decimal.

Ejemplo con importe explícito:

<propina>0.00</propina>

El valor de monto enviado será el que se cargue al tarjetahabiente, por lo tanto, debe incluir la propina.

5.4. Identificación de la transacción

transaccionId

Identificador proporcionado por el integrador para relacionar la operación con un pedido o transacción interna.

Se recomienda generar un identificador único por operación lógica y conservarlo para conciliación y seguimiento.

referencia

Campo complementario para asociar una referencia administrativa o comercial.

5.5. Datos de la tarjeta

tarjeta

Campo destinado a transmitir información de la tarjeta utilizada en la operación.

tipo

Campo relacionado con el tipo de tarjeta u operación.

mes y anio

Representan el mes y año de vencimiento de la tarjeta.

El año debe enviarse con dos dígitos.

digitos

Campo adicional de tipo string que sirve para enviar el CVV de la tarjeta.

titular

Nombre del titular de la tarjeta.

5.6. Información de origen

dirIp

Dirección IP relacionada con la operación.

5.7. Pagos diferidos

La solicitud contiene tres campos asociados potencialmente a modalidades de pago diferido:

5.8. Autenticación 3D Secure

La solicitud contiene:

Estos campos están relacionados con información de autenticación 3D Secure.

De acuerdo con la terminología habitual del ecosistema de pagos:

• xid se relaciona con un identificador de autenticación.

• cavv se relaciona con un valor criptográfico de autenticación.

• eci representa un indicador de comercio electrónico.

• status_3d se relaciona con el resultado del proceso de autenticación.

No deben enviarse valores 3D Secure ficticios en transacciones reales. Cuando sean requeridos, deberán proceder de un proceso de autenticación válido.

El flujo completo se documentará en la sección independiente 3D Secure.

5.9. Subcomercio

subcomercio

Campo opcional de tipo string.

6. Ejemplo de solicitud SOAP 1.1

El siguiente ejemplo muestra una solicitud de venta utilizando un token temporal obtenido previamente mediante ecommerceSessionID.

Encabezados HTTP

Cuerpo SOAP

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

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

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

Notas sobre el ejemplo

1. Los identificadores, credenciales, importes y datos de tarjeta son ficticios.

2. El valor de contrasena representa un token temporal de un solo uso.

3. El ejemplo respeta el orden de los elementos incluidos según cTCReq.

4. Los campos opcionales omitidos pueden ser necesarios para una operación real, dependiendo de las reglas de OEL.

5. El ejemplo demuestra la estructura XML, pero no constituye una transacción ejecutable ni una prueba de certificación.

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

Uso de campos 3D Secure

Cuando se disponga de resultados válidos de autenticación 3D Secure, los campos correspondientes deberán incluirse en el orden definido por cTCReq, después de plan y antes de subcomercio:

<xid>VALOR_3DS_OBTENIDO</xid>
<cavv>VALOR_3DS_OBTENIDO</cavv>
<eci>VALOR_3DS_OBTENIDO</eci>
<status_3d>VALOR_3DS_OBTENIDO</status_3d>

Este fragmento es únicamente estructural. Los valores deben obtenerse del mecanismo de autenticación habilitado.

7. Parámetros de respuesta (Response)

El servicio devuelve un objeto ecommerceVentaResult de tipo cTCResp.

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

Interpretación de los campos

comercioId

Identifica el comercio asociado a la respuesta.

Se recomienda comprobar que coincida con el comercio que originó la solicitud.

transaccionId

Permite relacionar la respuesta con la transacción interna.

fechaTransaccion y horaTransaccion

Representan la fecha y hora de ejecución de la operación.

monto

Importe reportado por el servicio.

Se recomienda contrastarlo con el monto solicitado, considerando las reglas de propina y procesamiento que confirme OEL.

codigoRespuesta

Código funcional que debe interpretarse conforme al catálogo oficial.

procReturnMsg

Mensaje relacionado con el resultado del procesamiento.

ccErrorCode

Código complementario que puede aportar información adicional sobre el resultado.

ccReturnMsg

Mensaje adicional de respuesta del Gateway.

codigoAprobacion

Dato de aprobación devuelto cuando corresponda.

Su presencia o ausencia no debe utilizarse como único criterio para determinar el resultado.

referenciaTransaccionBancaria

Referencia relacionada con el procesamiento bancario.

Se recomienda conservarla para seguimiento y conciliación cuando se encuentre disponible.

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

Advertencia: todos los valores son ficticios.

Los valores 0 de codigoRespuesta y ccErrorCode son exclusivamente ilustrativos. No establecen que dichos códigos representen una operación aprobada.

La respuesta real puede omitir los campos declarados opcionales.

9. Flujo de procesamiento de una venta

Paso 1. Crear la operación comercial

El sistema del comercio registra el pedido o transacción que requiere pago.

Se recomienda asignar un identificador interno único y conservar el monto autorizado por el comprador.

Paso 2. Preparar la autenticación

Cuando se utilice el mecanismo de token temporal, el backend del comercio invoca ecommerceSessionID con sus credenciales permanentes.

El servicio devuelve sessionId.

Paso 3. Entregar el token temporal

El backend proporciona el token a la sesión de compra correspondiente, aplicando los controles de seguridad necesarios.

Paso 4. Preparar la solicitud de pago

La aplicación construye cTCReq con:

• Identificación del comercio.

• Token temporal en contrasena.

• Monto y propina.

• Identificadores comerciales.

• Datos de tarjeta.

• Parámetros adicionales que requiera el escenario.

Paso 5. Incorporar autenticación 3D Secure

Cuando la operación lo requiera, se deberán incorporar los valores resultantes del flujo 3D Secure correspondiente.

Paso 6. Invocar ecommerceVenta

La aplicación envía la solicitud SOAP a OpGateway.

Paso 7. Recibir el resultado

El Gateway devuelve la estructura cTCResp o, ante ciertos errores, puede producir una respuesta SOAP Fault.

Paso 8. Interpretar la operación

El integrador evalúa los códigos y mensajes devueltos conforme al catálogo oficial de OEL.

Paso 9. Actualizar el pedido

El sistema del comercio actualiza el estado del pedido según el resultado funcional confirmado.

No debe marcarse como pagado un pedido únicamente porque se recibió una respuesta HTTP 200 OK.

Paso 10. Registrar y conciliar

Se recomienda conservar los identificadores y referencias de la transacción para auditoría, seguimiento y conciliación.

10. Consideraciones sobre el token de un solo uso

Cuando ecommerceVenta utiliza un token generado por ecommerceSessionID, deben observarse las siguientes reglas:

Una operación por token

El token no debe reutilizarse para procesar varias ventas.

Protección de credenciales

La contraseña permanente debe permanecer protegida en el backend del comercio.

Nueva operación

Para solicitar una nueva venta, debe obtenerse un nuevo token.

Timeout

Si ocurre una interrupción de comunicación después de enviar la venta, no debe asumirse que el cargo fue rechazado.

La solicitud podría haber sido procesada aunque el navegador no haya recibido respuesta.

Reintentos

No debe enviarse nuevamente el mismo cargo sin verificar su estado.

La generación de un nuevo token no demuestra que la transacción anterior haya sido cancelada o rechazada.

11. Manejo de respuestas y errores

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

Escenarios de integración

Estados internos recomendados

El sistema integrador puede manejar estados internos como:

• PENDIENTE

• EN_PROCESO

• APROBADA

• RECHAZADA

• INDETERMINADA

Estos estados son una propuesta de modelado para la aplicación integradora, no valores publicados por el WSDL.

12. Prevención de cargos duplicados

Una venta es una operación financiera que requiere especial cuidado durante los reintentos.

Uso de transaccionId

Se recomienda asignar un transaccionId único a cada operación lógica de cobro.

Interrupciones de comunicación

Una interrupción puede producirse antes o después de que el Gateway reciba la solicitud.

Por ello, una respuesta ausente no equivale necesariamente a una transacción rechazada.

Recomendación

Ante un resultado indeterminado:

1. Conservar el identificador de la operación.

2. Registrar el intento y su información técnica no sensible.

3. Verificar el resultado mediante los mecanismos de conciliación disponibles.

4. Evitar generar un segundo cargo hasta determinar el estado del primero.

La disponibilidad de mecanismos de consulta complementarios deberá confirmarse con OEL.

13. Seguridad y protección de datos

Datos de tarjeta

El método ecommerceVenta contempla la transmisión de información de tarjeta mediante el campo tarjeta y otros parámetros relacionados.

Por ello, la arquitectura de integración debe evaluar su alcance PCI DSS.

Token de sesión

El token generado mediante ecommerceSessionID protege la contraseña permanente, pero no sustituye la tokenización de la tarjeta.

Son mecanismos distintos:

• El token de sesión sustituye una credencial de autenticación del comercio.

• Un token de tarjeta representa información de tarjeta mediante un mecanismo de tokenización específico.

Registros y auditoría

Se recomienda registrar:

• comercioId.

• transaccionId.

• referencia.

• Monto solicitado.

• Fecha y hora del intento.

• Resultado funcional.

• Código de aprobación, cuando exista.

• Referencia bancaria, cuando exista.

No deben registrarse contraseñas, tokens activos ni datos sensibles de tarjeta.

Solicitudes desde el navegador

Para integraciones directas desde el navegador deben confirmarse:

• Manejo de OpHeader.

• Controles de origen y autorización.

• Protección del token temporal.

• Requisitos PCI DSS de la integración.

• Restricciones de los métodos que pueden invocarse desde el cliente.

15. Métodos relacionados

El contrato incluye también ecommercePreCancelacion, que se documentará individualmente.

Las recomendaciones de arquitectura, prevención de duplicados, seguridad, conciliación y manejo de estados internos se identifican como prácticas propuestas para la integración, no como garantías contractuales de OEL.