Integración con Azul - Pasarela de Pagos

Guía Completa de Configuración y Uso

Digimart se integra con Azul (Servicios Digitales Popular) para procesar pagos con tarjetas de crédito y débito en República Dominicana. La integración incluye dos métodos: Página de Pago (formulario hospedado por Azul) y Web Service API (cobros directos vía API con tokens de tarjeta).

Con esta integración puedes: generar links de pago desde facturas, registrar tarjetas de clientes para cobros futuros, procesar cobros recurrentes con tokens, realizar reembolsos y anulaciones, y consultar el historial de transacciones por cliente.

Requisitos Previos

Antes de comenzar la configuración, necesitas obtener de Azul los siguientes elementos. Debes solicitarlos contactando a solucionesecommerce@azul.com.do o a tu ejecutivo asignado.

• Merchant ID: Número de identificación del comercio asignado por Azul (ej: 39038540035).
• Llave Privada de Página de Pago: Cadena larga usada para generar el AuthHash en transacciones de Página de Pago. Es diferente a las claves de Web Service.
• AuthKey1 y AuthKey2 de Web Service: Claves de autenticación para la API de Web Service (cobros con token, reembolsos, anulaciones).
• Certificado Digital (.pem): Certificado SSL requerido para la conexión con el Web Service API de Azul.
• Llave Privada del Certificado (.pem): Llave privada asociada al certificado digital.

Importante: Azul proporciona credenciales separadas para el ambiente de pruebas (Sandbox) y producción. Las credenciales de pruebas y producción nunca son iguales. Las URLs de prueba y producción también son diferentes.

Configuración Inicial

Para configurar Azul en Digimart, navega a Ajustes → Integraciones → Azul. La página de configuración tiene tres pestañas: Credenciales, Web Service y Transacciones.

Pestaña: Credenciales

En esta pestaña configuras los datos básicos del comercio y las claves de autenticación. Todos los campos se muestran en texto plano para facilitar la verificación.

Información del Comercio

• Merchant ID (MerchantID): El número de identificación del comercio asignado por Azul. Ejemplo: 39038540035.
• Nombre del Comercio (MerchantName): El nombre que se mostrará al cliente en la página de pago de Azul.
• Código de Moneda (CurrencyCode): La moneda de las transacciones. Opciones: $ (DOP - Pesos Dominicanos) o USD (Dólares).

Claves Web Service (API)

Estas claves se usan para transacciones directas vía API: cobros con token de tarjeta, reembolsos y anulaciones. Son proporcionadas por Azul junto con el certificado digital.

• AuthKey1 (Web Service): Primera clave de autenticación para el Web Service API.
• AuthKey2 (Web Service): Segunda clave de autenticación para el Web Service API.

Llave Privada - Página de Pago

Esta llave se usa exclusivamente para la integración con la Página de Pago de Azul (formulario de cobro con tarjeta que Azul hospeda). Es diferente a las claves de Web Service y debe solicitarse a Azul por separado. Es una cadena larga (100+ caracteres) que se usa para calcular el AuthHash HMAC-SHA512 de cada transacción.

Estado y Ambiente

• Activar Azul: Switch para habilitar o deshabilitar Azul como método de pago en todo el sistema.
• Ambiente: Puedes alternar entre Sandbox (pruebas) y Producción (live). Al cambiar de ambiente, asegúrate de actualizar las credenciales correspondientes.

Probar Configuración

El botón "Probar Configuración" verifica que todos los campos estén completos y genera hashes de prueba. El modal de resultados muestra el estado de cada componente: Merchant ID, nombre, ambiente, claves de Web Service (AuthKey1/AuthKey2), llave de Página de Pago, y hashes generados. Si la configuración es parcial (ej: tienes Web Service pero no Página de Pago), se muestra una advertencia amarilla.

Pestaña: Web Service

En esta pestaña configuras los parámetros específicos del Web Service API y gestionas los certificados digitales.

• Store (wsStore): Identificador de tienda proporcionado por Azul para el Web Service.
• Channel (wsChannel): Canal de transacción. Por defecto: EC (E-Commerce).
• PosInputMode (wsPosInputMode): Modo de entrada. Por defecto: E-Commerce.
• Certificado Digital: Sube el certificado (.pem) proporcionado por Azul. Puedes subir el certificado y la llave privada juntos o por separado.
• Generar CSR: Si necesitas generar un nuevo Certificate Signing Request para solicitar un certificado a Azul, puedes hacerlo desde aquí.

Funcionalidades Principales

1. Links de Pago desde Facturas

Desde la vista de detalle de una factura, puedes generar un link de pago con Azul. El flujo es el siguiente:

1. Abre la factura y ve a la sección "Links de Pago".
2. Haz clic en "Crear Link de Pago" y selecciona Azul como proveedor.
3. Se genera un link único que puedes copiar y compartir con el cliente por WhatsApp, correo o cualquier medio.
4. El cliente abre el link, ve el monto y detalle de la factura, y hace clic en "Pagar con Tarjeta".
5. Es redirigido a la Página de Pago de Azul donde ingresa los datos de su tarjeta de forma segura.
6. Al completar el pago, Azul redirige de vuelta a Digimart y el pago se registra automáticamente.
7. La tarjeta del cliente se guarda automáticamente como método de pago (token DataVault) para cobros futuros.

Nota: Los links de pago utilizan la Llave Privada de Página de Pago para generar el AuthHash. Si esta llave no está configurada, no se podrán crear links de pago.

2. Registro de Tarjetas (Tokenización)

Puedes registrar la tarjeta de un cliente sin cobrarle, para utilizarla en cobros futuros. El flujo es:

1. Ve a la ficha del cliente en Clientes → [Nombre del Cliente].
2. Selecciona la pestaña "Tarjetas".
3. Haz clic en "Agregar Tarjeta". Se genera un link de registro y se copia automáticamente al portapapeles.
4. Envía el link al cliente. Al abrirlo, verá una página donde puede registrar su tarjeta.
5. Se realiza un cobro mínimo de DOP 1.00 (requerido por Azul) que se anula automáticamente después de capturar el token.
6. La tarjeta queda registrada como método de pago del cliente con su token DataVault, marca, número enmascarado y Merchant ID.

Importante: Los datos de la tarjeta nunca pasan por los servidores de Digimart. Azul es quien captura la información y devuelve un token seguro (DataVault) que se almacena en Digimart para cobros futuros.

3. Cobros con Tarjeta Registrada

Una vez que un cliente tiene una tarjeta registrada, puedes cobrarle directamente desde Digimart sin que el cliente tenga que ingresar sus datos nuevamente.

1. Ve a la ficha del cliente → pestaña "Tarjetas".
2. En la tabla de métodos de pago, haz clic en "Cobrar" junto a la tarjeta deseada.
3. Se abre un modal donde ingresas el Monto (DOP) y el ITBIS (DOP). Los montos se ingresan en pesos (ej: 500.00 para quinientos pesos).
4. Haz clic en "Cobrar" para procesar el pago vía Web Service API.
5. El resultado aparece en la tabla de transacciones del cliente.

Requisitos: Para cobrar con token necesitas tener configurados: AuthKey1 y AuthKey2 de Web Service, el certificado digital, y los parámetros de Web Service (Store, Channel).

4. Historial de Transacciones por Cliente

Debajo de la tabla de métodos de pago en la pestaña "Tarjetas" del cliente, se muestra la tabla "Transacciones Azul" con todas las transacciones procesadas para ese cliente.

La tabla incluye: fecha y hora, tipo de transacción (Venta, Reembolso, Anulación), monto, tarjeta utilizada (marca y número enmascarado), estado (Aprobada, Rechazada, Error, Anulada, Reembolsada), detalle del error (si aplica), y número de referencia (RRN).

Para transacciones con error o rechazadas, puedes ver el detalle del error en la columna "Detalle" o pasando el mouse sobre el estado.

5. Reembolsos y Anulaciones

Desde la pestaña de Transacciones en la configuración de Azul, puedes gestionar reembolsos y anulaciones de transacciones previamente procesadas.

• Anulación (Void): Cancela una transacción que aún no ha sido liquidada. Solo disponible dentro de los primeros 20 minutos después de la transacción.
• Reembolso (Refund): Devuelve el monto total o parcial de una transacción ya liquidada. El monto puede ser igual o menor al monto original.

Configuración Paso a Paso (Ambiente de Pruebas)

Sigue estos pasos para configurar y probar la integración con Azul en el ambiente Sandbox.

Paso 1: Obtener Credenciales de Prueba

Contacta a Azul (solucionesecommerce@azul.com.do) y solicita:

1. Credenciales de Página de Pago (Merchant ID + Llave Privada).
2. Credenciales de Web Service API (AuthKey1, AuthKey2, Store, Channel).
3. Certificado digital para el ambiente de pruebas.
4. Tarjetas de prueba para realizar transacciones de prueba.

Azul enviará las credenciales por correo. Las credenciales de Página de Pago y Web Service son diferentes. Asegúrate de solicitar ambas explícitamente.

Paso 2: Configurar en Digimart

1. Navega a Ajustes → Integraciones → Azul.
2. Ingresa el Merchant ID, Nombre del Comercio y Código de Moneda.
3. Ingresa las AuthKey1 y AuthKey2 de Web Service.
4. Ingresa la Llave Privada de Página de Pago.
5. Haz clic en "Guardar".
6. Ve a la pestaña "Web Service" e ingresa el Store, Channel y sube el certificado digital.
7. Activa Azul con el switch de Estado.
8. Haz clic en "Probar Configuración" para verificar que todo esté correcto.

Paso 3: Probar un Link de Pago

1. Crea una factura de prueba.
2. Desde la factura, genera un link de pago con Azul.
3. Abre el link en el navegador.
4. En la página de Azul, usa una tarjeta de prueba proporcionada por Azul.
5. Usa fecha de expiración futura (ej: 12/34) y cualquier CVV de 3 dígitos.
6. Verifica que el pago se registre exitosamente en la factura.

Paso 4: Probar Registro de Tarjeta

1. Ve a un cliente de prueba → pestaña "Tarjetas".
2. Haz clic en "Agregar Tarjeta" y copia el link generado.
3. Abre el link, completa con una tarjeta de prueba.
4. Verifica que la tarjeta aparezca registrada en la pestaña "Tarjetas" del cliente.
5. Prueba un cobro con la tarjeta registrada usando el botón "Cobrar".

Paso 5: Pasar a Producción

1. Solicita a Azul las credenciales de producción (Merchant ID, llaves, certificado).
2. Cambia el ambiente a Producción en la configuración de Azul.
3. Actualiza todas las credenciales con las de producción.
4. Sube el certificado digital de producción.
5. Verifica con "Probar Configuración" que todo esté correcto.
6. Realiza una transacción real de prueba con un monto pequeño.

Datos Técnicos

URLs de Azul

• Sandbox (Página de Pago): https://pruebas.azul.com.do/paymentpage/Default.aspx
• Producción (Página de Pago - Principal): https://pagos.azul.com.do/PaymentPage/Default.aspx
• Producción (Página de Pago - Alterno): https://contpagos.azul.com.do/PaymentPage/Default.aspx

Cálculo del AuthHash (Página de Pago)

El AuthHash se calcula concatenando los siguientes campos en este orden exacto, sin separadores, y aplicando HMAC-SHA512 con la Llave Privada como clave:

MerchantId + MerchantName + MerchantType + CurrencyCode + OrderNumber + Amount + ITBIS + ApprovedUrl + DeclinedUrl + CancelUrl + UseCustomField1 + CustomField1Label + CustomField1Value + UseCustomField2 + CustomField2Label + CustomField2Value + AuthKey

El campo Amount se envía en centavos sin separadores decimales (ej: 10000 = DOP 100.00). El campo ITBIS sigue el mismo formato (ej: 1800 = DOP 18.00, 000 = exento). Ambos campos deben tener mínimo 3 caracteres con padding de ceros a la izquierda.

DataVault (Tokenización)

DataVault es el servicio de Azul para almacenar tokens de tarjetas de forma segura. Digimart utiliza DataVault de la siguiente manera:

• Al crear links de pago, se incluye SaveToDataVault=1 para que Azul devuelva un token junto con el pago.
• Para registro de tarjetas sin cobro, se realiza un cobro mínimo de DOP 1.00 con SaveToDataVault=1, y luego se anula automáticamente (Void) el cobro.
• Los tokens se almacenan en la tabla payment_methods asociados al cliente, junto con la marca de tarjeta, número enmascarado, expiración y Merchant ID.
• Para cobros futuros, se usa el token via Web Service API (endpoint sale-token) sin necesidad de que el cliente vuelva a ingresar datos.

Solución de Problemas

Error: INVALID_AUTH:AuthHash

Este error indica que el hash calculado no coincide con lo que Azul espera. Posibles causas:

• Llave Privada incorrecta: Verifica que la Llave Privada de Página de Pago esté correcta. Es diferente a las AuthKeys de Web Service.
• Ambiente incorrecto: Las llaves de Sandbox no funcionan en Producción y viceversa.
• Espacios en la llave: Asegúrate de que la llave no tenga espacios al inicio o al final.
• Llave de Web Service en vez de Página de Pago: Las claves AuthKey1/AuthKey2 de Web Service NO sirven para la Página de Pago. Solicita a Azul la llave específica de Página de Pago.

Error: Registro de tarjeta siempre declinado

Si al intentar registrar una tarjeta la transacción es siempre rechazada, puede deberse a que el monto es 0. Azul requiere un monto mayor a cero para procesar transacciones con DataVault. Digimart utiliza un monto mínimo de DOP 1.00 que se anula automáticamente después de capturar el token.

Error: Certificado SSL

Si los cobros con token (Web Service) fallan con errores de SSL, verifica que: el certificado no esté expirado, el certificado corresponda al ambiente correcto (Sandbox/Producción), y que la llave privada corresponda al certificado subido.

Transacción rechazada sin razón clara

Verifica la columna "Detalle" en la tabla de transacciones del cliente. Los campos errorDescription y responseMessage proporcionan el detalle del rechazo. Códigos comunes: ISOCode 00 = Aprobada, ResponseCode ISO8583 = Procesada correctamente, ResponseCode Error = Error del procesador.

Tarjetas de Prueba (Sandbox)

En el ambiente de Sandbox, Azul proporciona tarjetas de prueba. Usa fecha de expiración futura (ej: 12/34) y cualquier CVV de 3 dígitos (4 para American Express). Las tarjetas de prueba específicas son proporcionadas por Azul al momento de entregar las credenciales.

Glosario

• Página de Pago (Payment Page): Formulario web hospedado por Azul donde el cliente ingresa los datos de su tarjeta. Digimart redirige al cliente a esta página y recibe la respuesta vía URL de retorno.
• Web Service API: API directa de Azul que permite procesar transacciones sin redirigir al cliente. Requiere certificado digital y se usa para cobros con token, reembolsos y anulaciones.
• DataVault: Servicio de Azul para almacenar tokens de tarjetas de forma segura. El token permite cobrar sin que el cliente ingrese datos nuevamente.
• AuthHash: Hash HMAC-SHA512 calculado a partir de los campos de la transacción y la llave privada. Garantiza la integridad de la transacción.
• Merchant ID: Número de identificación del comercio asignado por Azul.
• RRN (Reference Referral Number): Número de referencia único asignado por Azul a cada transacción procesada.
• AzulOrderId: Número de orden interno de Azul para cada transacción.
• Void (Anulación): Cancelación de una transacción antes de que sea liquidada. Disponible hasta 20 minutos después de la transacción.
• Refund (Reembolso): Devolución del monto de una transacción ya liquidada. Puede ser parcial o total.
• SaveToDataVault: Parámetro que indica a Azul que debe generar y devolver un token de la tarjeta utilizada en la transacción.
• Sandbox: Ambiente de pruebas de Azul con datos ficticios. No procesa pagos reales.
• ISOCode: Código de respuesta ISO 8583. El código 00 indica transacción aprobada.