Infografía con las tres formas de cobrar en línea con Azul y los datos clave para integrar su Página de Pagos
Volver al blog
Tecnología

Azul: link de pago, Página de Pagos o API en tu web

Las 3 formas de cobrar en línea con Azul y cómo integrar su Página de Pagos: AuthHash HMAC-SHA512, moneda, pruebas y cómo validar cada pago.

8 min de lectura
1,626 palabras

Azul, la plataforma de pagos de Servicios Digitales Popular (filial del Grupo Popular), te da tres formas de cobrar con tarjeta en línea: el link de pagos, que se crea desde la App AZUL o la Terminal Virtual sin programar nada; la Página de Pagos, a la que tu web manda al cliente para que pague en un sitio de Azul con 3-D Secure; y la integración vía API, donde tu servidor envía los datos de la tarjeta. Para vender en tu propia web, la Página de Pagos suele ser el punto medio: el importe lo pone tu sistema y la tarjeta nunca pasa por tu servidor.

Abajo, cuándo conviene cada una según la documentación de Azul, y la guía de la Página de Pagos con lo que aprendimos al integrarla para un cliente de turismo.

Las tres formas de cobrar en línea con Azul

OpciónCómo funcionaQuién captura la tarjetaTe conviene si…
Link de pagosCreas el enlace en la App AZUL o en la Terminal Virtual y lo mandas por WhatsApp, redes, correo o SMS. También se puede crear por API.AzulVendes por chat o cobras importes sueltos y no tienes tienda en línea.
Página de PagosTu web envía al cliente, con un formulario firmado, a la página de Azul. Azul cobra, hace el 3-D Secure y lo devuelve a tus URLs con el resultado.AzulTienes web o sistema propio y quieres que el importe y la confirmación salgan de ahí.
Integración vía APITu servidor llama a Azul (SOAP, JSON o formulario HTTP) con los datos de la compra y de la tarjeta, por VPN o con un certificado que emite Azul.TúQuieres un checkout totalmente tuyo, en web o app, y puedes cumplir PCI DSS.

La diferencia de fondo es la tarjeta. Con la API la capturas tú, y Azul exige el cuestionario de autoevaluación D de PCI y validar con su equipo el proveedor de hosting y las IP de origen antes de salir a producción. Con la Página de Pagos la tarjeta se escribe en el sitio de Azul y tu servidor no la toca, aunque el manual recuerda que todo afiliado debe cumplir PCI DSS.

Cómo funciona la Página de Pagos

Es un formulario HTML con campos ocultos que el navegador del cliente, no tu servidor, envía por POST a Azul. Lo esencial:

  • Importes sin punto ni coma: los dos últimos dígitos son los centavos. 1000 son 10.00. El ITBIS va igual, y 000 si la venta está exenta.
  • Tres URLs de retorno: ApprovedUrl, DeclinedUrl y CancelUrl. Las dos primeras reciben el resultado en el querystring; la de cancelación no recibe parámetros.
  • ShowTransactionResult=0 manda al cliente directo a tus URLs, sin la pantalla de resultado de Azul.
  • AuthHash: la firma que demuestra que nadie tocó el formulario. Aquí está el primer tropiezo.

El AuthHash es HMAC-SHA512, no SHA-512 plano

La firma de la petición se calcula con 16 campos concatenados sin separador y en este orden: MerchantId, MerchantName, MerchantType, CurrencyCode, OrderNumber, Amount, ITBIS, ApprovedUrl, DeclinedUrl, CancelUrl, UseCustomField1, CustomField1Label, CustomField1Value, UseCustomField2, CustomField2Label y CustomField2Value. Al final se añade el AuthKey, una clave que Azul entrega en la afiliación y que nunca viaja en el POST.

La respuesta trae su propio hash con 9 campos más el AuthKey: OrderNumber, Amount, AuthorizationCode, DateTime, ResponseCode, IsoCode, ResponseMessage, ErrorDescription y RRN. El ITBIS viaja en la respuesta pero no entra en el hash, y el AzulOrderId tampoco.

El texto del portal de desarrolladores y el manual en PDF de 2023 dicen «HMAC SHA512». Pero las imágenes de código del portal usan SHA512Managed en C# y hash('sha512') en PHP, que son SHA-512 plano. Nuestra primera versión siguió esas imágenes y Azul la rechazó con INVALID_AUTH:AuthHash. Probamos cinco variantes contra la página real de Azul y solo una pasó: HMAC-SHA512 con el AuthKey como clave y, además, concatenado al final del mensaje. Es lo que muestran los ejemplos del PDF (HMACSHA512 en C#, hash_hmac en PHP).

La codificación también cuenta. El manual admite UTF-8 o Unicode en la petición, pero la respuesta la firma desde una cadena Unicode, que en sus ejemplos es UTF-16LE (Encoding.Unicode en C#). Para verificarla tienes que reproducir esos mismos bytes. En Node queda así:

import { createHmac } from 'node:crypto'

// orden: los 16 campos de la petición o los 9 de la respuesta
const cadena = orden.map((k) => campos[k] ?? '').join('') + authKey
const authHash = createHmac('sha512', authKey)
  .update(Buffer.from(cadena, 'utf16le'))
  .digest('hex')

Al verificar el retorno, compara en tiempo constante y sin distinguir mayúsculas.

La moneda: cobras en la de tu afiliación

Según el manual, cada comercio transacciona con una sola moneda, y el valor de CurrencyCode lo da Azul junto con tus credenciales. En nuestra integración, con una afiliación en pesos, es $.

El DCC (conversión dinámica de monedas) no cambia eso. Es para el tarjetahabiente extranjero: la Página de Pagos le ofrece pagar en la moneda de su tarjeta, pero el comercio recibe los fondos en su moneda de facturación, elija lo que elija el cliente, y hay que pedir que lo activen. Azul no convierte por ti.

Así que, si vendes en US$ con una afiliación en pesos, conviertes tú. Para el cliente de turismo lo resolvimos así:

  • Los precios se muestran en US$ y el cobro va en RD$, con la tasa de venta del Banco Central (ver la tasa del dólar del Banco Central), convertida a centavos exactos.
  • La tasa queda fijada en el enlace de pago firmado: lo que ve el cliente es lo que se cobra, aunque la tasa cambie entre una página y otra.
  • Si la tasa nueva se aleja demasiado de la última buena, se descarta. Si no hay ninguna tasa fiable, no se arma el cobro.

Para cobrar directamente en dólares necesitarías una afiliación en esa moneda; la documentación de la API de Azul advierte que operar en moneda extranjera requiere permiso de la DGII y del Banco Central.

Dominio, pruebas y certificación

El dominio de retorno. Las tres URLs tienen que estar en el dominio registrado para tu MerchantId, con SSL; un subdominio distinto también falla. Si no, la página responde INVALID_BASEDOMAIN. Si cambias de dominio, el manual dice que hay que pedir el cambio a tu oficial de negocios de Azul.

La certificación. Azul te da acceso a un ambiente de pruebas con las mismas funciones que producción. Sus técnicos verifican tu mensajería y solo entonces se crean los accesos de producción. Las credenciales y las URLs de prueba nunca son las de producción.

Las tarjetas de prueba. Azul publica estas para su ambiente de pruebas, con cualquier CVV de 3 dígitos (recomienda 999):

Escenario de 3-D SecureTarjeta
Sin fricción, con 3DSMethod4265 8800 0000 0007
Sin fricción, sin 3DSMethod4147 4630 1111 0117
Desafío, con 3DSMethod4005 5200 0000 0129
Desafío, sin 3DSMethod4147 4630 1111 0059

Simulan la autenticación, no garantizan la aprobación. Para la certificación preparamos estos casos: aprobada sin fricción, aprobada con desafío, rechazada, cancelada, enlace ya pagado y retorno manipulado.

Cómo dar por bueno un pago sin fiarte del navegador

El resultado vuelve por el navegador, así que cualquiera puede copiar una URL de retorno, editarla o reenviarla. Nuestro servidor solo aprueba un pago si se cumple todo esto:

  1. El hash de la respuesta es válido. Como firma OrderNumber y Amount, un retorno capturado no sirve para otro pedido ni para otro importe.
  2. El IsoCode es 00.
  3. El pedido existe: lo emitimos nosotros.
  4. La transacción de Azul no se usó antes para otro pedido.
  5. El importe devuelto coincide con el emitido.

Si falla una sola, el pago no se aprueba. Un rechazo solo se guarda si su hash es válido, y una cancelación, que no trae datos, se muestra pero no cambia nada.

La otra mitad es que el importe nunca lo manda el cliente. El servidor calcula el precio con su propia tabla y lo mete en un enlace firmado con HMAC-SHA256, con un secreto distinto del AuthKey y con caducidad. La página de pago reabre ese enlace en el servidor, rechaza los que estén alterados, caducados o ya pagados, y solo entonces arma y firma el formulario de Azul.

¿Y si vendes desde Odoo?

Odoo 17 no trae proveedor de pago para Azul: no aparece entre los proveedores de su documentación ni entre los 21 módulos de pago (payment_*) de su código. En su portal de desarrolladores, Azul lista Odoo entre los plugins, pero sin documento: pide escribir a su área de afiliación. Hoy, cobrar con Azul desde Odoo pasa por un módulo a medida o por lo que te ofrezca Azul.

Si vendes por WhatsApp o cobras pocas veces al mes, el link de pagos de la App AZUL te basta y no necesitas programar nada. Si quieres que tu web o tu Odoo calculen el importe, cobren con Azul y confirmen el pago solos, eso es lo que hacemos en integraciones: Escríbenos y lo vemos con tu caso.

Fuentes

FAQ

Preguntas Frecuentes

Tres: el link de pagos, que se crea desde la App AZUL o la Terminal Virtual; la Página de Pagos, donde el cliente paga en un sitio de Azul con 3-D Secure; y la integración vía API, donde tu servidor envía los datos de la tarjeta.

Con HMAC-SHA512 y el AuthKey como clave, sobre los campos concatenados en el orden de Azul más el AuthKey al final, en UTF-16LE. Con SHA-512 plano, Azul rechazó nuestra petición con INVALID_AUTH:AuthHash.

No. El DCC le ofrece al tarjetahabiente extranjero pagar en la moneda de su tarjeta, pero el comercio recibe los fondos en su moneda de facturación. Si vendes en US$ con una afiliación en pesos, conviertes tú.

Que una URL de retorno no está en el dominio registrado para tu MerchantId, no tiene SSL o está mal formada. Un subdominio distinto también falla, y el cambio se pide al oficial de negocios de Azul.

No. Azul no aparece entre los proveedores de pago de Odoo 17, así que hace falta un módulo a medida o lo que te ofrezca Azul.

Agenda 30 minutos

Comenzar Ahora

Artículos Relacionados

¿Listo para transformar tu negocio?

Agenda una consulta gratuita con nuestro equipo de expertos.

Agenda una llamada

Sin compromiso · Te respondemos en menos de 24 h

¿Aún lo estás evaluando?

Déjanos tus datos y un especialista te contacta en menos de 24 h. Sin compromiso.

O escríbenos por WhatsApp