Primeros Pasos

Antes de integrar cualquier servicio de OEL, es importante identificar el tipo de operación que deseas implementar: pagos presenciales, pagos en línea, Link de Pago, 3D Secure, tokenización, suscripciones o servicios para aliados.

Cada integración utiliza credenciales, endpoints y métodos específicos. Esta guía te ayudará a seleccionar el camino correcto, preparar tu ambiente de desarrollo y validar tus primeras transacciones antes de pasar a producción.

Ver ambientes Consultar referencia API

Antes de comenzar

El primer paso es identificar qué necesitas integrar. Esto determinará el protocolo, credenciales, endpoints y métodos que deberás utilizar.

Si aún no sabes qué integración necesitas, comienza por identificar si tu operación es presencial, en línea o administrativa.

Conceptos Básicos

Estos conceptos aparecen de forma recurrente en las distintas integraciones de OEL. Comprenderlos desde el inicio facilitará el desarrollo y la solución de errores.

OpKey1 / OpKey2

Llaves utilizadas en cabeceras SOAP para autenticar el consumo de servicios.

Aliado

Entidad que puede afiliar comercios, consultar información operativa y administrar servicios relacionados con comercios integrados.

Comercio

Entidad que procesa pagos a través de OEL. Cada comercio cuenta con credenciales propias y configuración transaccional.

comercioId

Identificador único asignado al comercio. Se utiliza para autenticar y asociar operaciones al comercio correspondiente.

contrasena

Clave asignada al comercio para operar con el Gateway de Pagos.

claveAliado

Identificador asignado al aliado para operar dentro del servicio OpAliados.

transaccionId

Identificador único de la operación generado por el sistema del comercio. Normalmente corresponde al número de pedido, orden o venta.

referencia

Campo libre que permite enviar una referencia adicional para conciliación o trazabilidad interna.

monto

Importe total de la operación. Debe enviarse sin signos de pesos, sin comas y con dos decimales cuando aplique.

codigoRespuesta

Campo de respuesta que indica el resultado general de la operación. En los documentos de integración se maneja, por ejemplo, 0 para aprobada y 1 para rechazada. OEL - eCommerce

codigoAprobacion

Código de autorización bancaria cuando la operación fue aprobada.

token

Referencia segura asociada a una tarjeta o cliente, utilizada para operaciones posteriores sin capturar nuevamente los datos completos de la tarjeta.

Credenciales de integración

Dependiendo del servicio que vayas a integrar, recibirás un conjunto de credenciales para ambiente de desarrollo y, posteriormente, credenciales distintas para ambiente productivo.

Credenciales para Gateway SOAP

Las operaciones SOAP requieren autenticación mediante cabeceras OpHeader con OpKey1 y OpKey2; además, el comercio se identifica mediante comercioId y contrasena.

Credenciales para REST API

Para REST API se utilizan credenciales como parte de los Headers HTTP.

Credenciales para Link de Pago

Para Link de Pago se utiliza autenticación basada en Tokens mediante JWT Access Token y JWT Refresh Token.

Credenciales para OpAliados

Para servicios administrativos de aliados se utilizan:

El servicio OpAliados permite realizar afiliación de comercios, actualización de tasas y generación de reportes mediante SOAP 1.1/1.2 sobre HTTPS. OEL - Servicios Aliados

Ambientes

OEL opera con ambientes separados para pruebas y producción. Nunca debes utilizar credenciales productivas durante el desarrollo inicial ni enviar datos reales de tarjeta en ambientes no autorizados.

Ambiente de desarrollo

Utiliza este ambiente para:

• Realizar pruebas técnicas.

• Validar estructura de request.

• Confirmar credenciales.

• Probar respuestas aprobadas y rechazadas.

• Ajustar manejo de errores.

• Validar cancelaciones, devoluciones y consultas.

• Preparar el proceso de certificación.

Ambiente productivo

Utiliza este ambiente únicamente cuando:

• La integración haya sido validada.

• El comercio esté habilitado.

• Las credenciales productivas hayan sido entregadas.

• El flujo de operación haya sido certificado.

• El sistema esté listo para procesar transacciones reales.

Flujo recomendado de integración

Aunque cada producto tiene particularidades, la mayoría de las integraciones siguen un flujo similar.

Paso 1: Selecciona el producto

Define si vas a integrar:

• Pagos presenciales

• eCommerce SOAP

• eCommerce REST

• 3D Secure

• Link de Pago

• Tokenización

• Suscripciones

• Servicios para Aliados

Paso 2: Solicita credenciales de desarrollo

Antes de programar, asegúrate de contar con:

• Endpoint de desarrollo.

• Credenciales del comercio o aliado.

• Llaves de autenticación.

• Métodos habilitados.

• Documentación técnica correspondiente.

• Datos de prueba.

Paso 3: Configura tu ambiente local

Recomendaciones:

• Usa HTTPS siempre que aplique.

• Separa variables por ambiente.

• No escribas credenciales directamente en código fuente.

• Utiliza archivos .env o administrador seguro de secretos.

• Activa logs técnicos sin registrar datos sensibles.

• Define timeouts de comunicación.

• Prepara manejo de errores.

Paso 4: Ejecuta una primera operación

Comienza con una operación simple según tu integración:

Paso 5: Valida la respuesta

Revisa al menos:

• codigoRespuesta

• codigoAprobacion

• Mensaje del procesador

• Fecha y hora de transacción

• Monto procesado

• transaccionId

• Referencia bancaria

• Mensajes de error

• Estado final de la operación

Paso 6: Implementa operaciones complementarias

Una integración completa normalmente no termina con la venta. También deberás contemplar:

• Cancelaciones

• Devoluciones

• Reversas

• Consultas

• Reintentos controlados

• Envío de voucher

• Conciliación

• Reportes

• Manejo de operaciones pendientes

Paso 7: Prepara certificación

Antes de solicitar paso a producción valida:

• Operación aprobada.

• Operación rechazada.

• Timeout.

• Credenciales inválidas.

• Monto inválido.

• Transacción duplicada.

• Cancelación.

• Devolución.

• Consulta de operación.

• Registro correcto en logs.

• No almacenamiento de datos sensibles.

Paso 8: Solicita habilitación productiva

Una vez aprobadas las pruebas, podrás solicitar:

• Credenciales productivas.

• Endpoint productivo.

• Habilitación de comercio.

• Habilitación de métodos.

• Confirmación de parámetros.

• Ventana de salida a producción.

Seguridad

Toda integración de pagos debe proteger credenciales, datos sensibles, tokens y respuestas bancarias. Estas prácticas ayudan a reducir riesgos operativos y de cumplimiento.

Recomendaciones principales

1. No almacenes datos sensibles de tarjeta

No guardes PAN, CVV, Track2, EMV Tags ni información sensible de autenticación.

En el flujo de Tarjeta Presente se especifica que PAN, Track2 y EMV Tags son datos volátiles, no se almacenan y solo persisten durante el momento de la transacción. OEL - Tarjeta Presente

2. Usa canales seguros

Todas las comunicaciones deben realizarse sobre HTTPS / TLS.

La documentación de integración describe el uso de SOAP 1.1/1.2 sobre HTTPS con TLS 1.2+ para el Gateway. OEL - eCommerce

3. Protege tus credenciales

No expongas credenciales en:

• Código fuente.

• Repositorios.

• Consola del navegador.

• Logs.

• Mensajes de error visibles al usuario.

• Archivos compartidos.

4. Implementa idempotencia

Usa transaccionId como identificador único de operación para evitar duplicidad de cargos ante reintentos, errores de red o respuestas tardías.

5. Registra trazabilidad operativa

Guarda información útil para conciliación:

• Fecha y hora.

• Comercio.

• Monto.

• transaccionId.

• Código de respuesta.

• Código de aprobación.

• Método invocado.

• Resultado final.

6. Separa ambientes

Nunca mezcles credenciales de desarrollo y producción. Mantén endpoints, llaves y configuraciones separadas.

Manejo de errores

Durante las primeras pruebas es normal encontrar errores por credenciales, formato de campos, endpoints incorrectos o datos incompletos. La mayoría se pueden resolver validando los parámetros antes de enviar la operación.

Tabla de errores comunes

Checklist rápido

Antes de ejecutar tu primera operación, confirma lo siguiente:

Siguiente paso

Una vez que conoces los conceptos base, credenciales, ambientes y flujo recomendado, selecciona la documentación correspondiente a tu caso de uso.

Pagos presenciales

Integra terminales, SDK Android o comunicación SOAP con equipos propios.

Pagos en línea

Procesa pagos eCommerce mediante SOAP, REST API o 3D Secure.

Link de Pago

Genera y administra links de pago para cobros remotos.

Servicios para Aliados

Afiliación, saldos, cortes, comisiones y reportes para aliados.