Conectar pasarela: Asaas y Mercado Pago

Visión general

Antes de cobrar a alguien, necesitas conectar una pasarela de pago. ConversaLabs admite Asaas y Mercado Pago. Cada conexión guarda las credenciales de la pasarela, define el entorno (producción o prueba) y registra un webhook — el canal por el que la pasarela avisa a la plataforma cuando un cobro se paga, vence o se reembolsa.

Puedes tener más de una conexión (por ejemplo, un Asaas de producción y un Mercado Pago para otro flujo). Cada cobro se crea en una conexión específica.

Requisitos previos

Módulo Pagos habilitado y permiso de administrador.
Una cuenta en la pasarela elegida:
- Asaas: una clave de API (API Key) del panel de Asaas.
- Mercado Pago: un Access Token y Client Secret de tus credenciales de aplicación.
Definir el entorno: producción (cobros reales) o sandbox (pruebas).

Paso a paso

Abre la configuración de Pagos y elige agregar una nueva conexión.
Selecciona la pasarela: Asaas o Mercado Pago.
Ingresa las credenciales:
- Asaas: pega la API Key.
- Mercado Pago: pega el Access Token (y el secreto de firma usado para validar el webhook).
Elige el entorno: producción o sandbox.
Guarda. La plataforma valida las credenciales con la pasarela.
Configura el webhook: la plataforma genera la URL de notificación y el secreto de verificación. En muchos casos el registro es automático; cuando no lo sea, copia la URL indicada y regístrala en el panel de la pasarela.
Haz una prueba en sandbox (un cobro PIX, por ejemplo) y confirma que el estado cambia solo cuando se simula el pago.

Configuración y opciones

Entorno: producción o sandbox por conexión. No mezcles credenciales de entornos distintos.
Webhook: la URL es única por conexión y la pasarela autentica cada notificación:
- Asaas envía un token propio en el encabezado de la solicitud, comparado de forma segura con el que la plataforma guardó.
- Mercado Pago firma cada notificación; la plataforma valida la firma antes de procesar.

Métodos admitidos por pasarela:

Capacidad	Asaas	Mercado Pago
PIX	Sí	Sí
Boleto	Sí	Sí
Tarjeta (checkout alojado)	Sí	Sí
Cuotas	Sí	Sí
Suscripciones	Sí	Sí
Planes reutilizables	—	Sí
Reembolso parcial	Sí	Sí

Casos de uso

Un operador que ya usa Asaas conecta la clave y empieza a cobrar por WhatsApp sin cambiar de sistema.
Una empresa que vende en América Latina conecta Mercado Pago.
Un equipo que quiere probar antes de cobrar de verdad usa el entorno sandbox primero.

Consejos, límites y buenas prácticas

Trata las credenciales como secreto: se almacenan cifradas y nunca vuelven a mostrarse en pantalla después de guardarlas.
Usa sandbox para validar todo el flujo antes de pasar a producción.
La autenticación de Asaas usa un encabezado access_token (no Authorization: Bearer).
Mercado Pago notifica solo el identificador del pago; la plataforma consulta la pasarela para leer el estado completo — esto es normal.

Solución de problemas

Credenciales inválidas: verifica que copiaste la clave/token correctos y que el entorno coincide con el de la pasarela (un token de prueba solo funciona en sandbox).
El estado no se actualiza: el webhook no está llegando. Confirma que la URL esté registrada en la pasarela y que el secreto de verificación coincida.
Notificación rechazada (401): la firma/token del webhook no coincide — vuelve a registrar el webhook.