## 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

1. Abre la configuración de **Pagos** y elige agregar una nueva conexión.
2. Selecciona la **pasarela**: Asaas o Mercado Pago.
3. Ingresa las **credenciales**:
   - Asaas: pega la **API Key**.
   - Mercado Pago: pega el **Access Token** (y el secreto de firma usado para validar el webhook).
4. Elige el **entorno**: producción o sandbox.
5. Guarda. La plataforma valida las credenciales con la pasarela.
6. 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.
7. 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

### Planes de cobro y talonario de pagos

Activa Pagos, conecta una pasarela compatible y revisa los datos del pagador. Las opciones dependen de la conexión, el método y el ciclo. Asaas ofrece cuotas nativas mensuales de boleto/Pix; otros ciclos usan recurrencia limitada cuando está disponible. Esta entrega no incorpora integraciones directas con nuevos bancos.


- **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.
- **Diagnóstico de la última conciliación**: la comprobación programada compara cobros y suscripciones
  con la pasarela para cubrir notificaciones perdidas. Si falla algún registro, la tarjeta de la
  conexión en **Configuración → Pagos → Conexiones** permanece roja con la cantidad total y hasta los
  tres primeros identificadores externos y motivos. Los demás registros siguen procesándose; las
  respuestas brutas, los datos del cliente y las credenciales nunca aparecen en este diagnóstico.
- **Protecciones de entrada**: son ajustes de la **conexión**, no de la importación, y también rigen
  lo que llega por webhook.
  - **Fecha de corte**: no entra nada anterior a ella. Es el freno que impide que un historial entero
    aparezca como si fuera de hoy.
  - **Adopción automática de cobros huérfanos**: desactivada de forma predeterminada. Un cobro que
    llega de la pasarela sin correspondencia local solo se adopta si lo permites; con "solo desde la
    fecha de corte", una fecha ausente o inválida hace que la operación falle de forma segura en lugar
    de adivinar.
  - Ambas están en **Importar historial → Ajustes de ingesta** y se guardan en la conexión, así que la
    próxima importación y el próximo webhook ya las respetan.
- **Métodos admitidos por pasarela**:

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

### Certificado de la conexión

Cuando la conexión requiera certificado, usa su área de certificado para cargar el archivo y los datos solicitados. Después, revisa titular, emisor, huella y vencimiento. La edición muestra metadatos; no devuelve clave, certificado ni contraseña. Los estados son ausente, válido, próximo a vencer y vencido. Renueva antes del plazo y revisa los metadatos; los avisos de vencimiento ayudan a planificarlo.

La fundación permite probar esta interfaz en un laboratorio con certificado ficticio. Esto no habilita un banco nuevo ni convierte un certificado de prueba en credencial de producción.

## 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.
- **La última conciliación tuvo fallos**: anota el identificador y el motivo mostrados en la tarjeta,
  valida la conexión y el entorno y confirma que el registro todavía existe en la pasarela. Un fallo
  permanece visible y nunca modifica silenciosamente el registro local. La siguiente comprobación
  sustituye el diagnóstico; la alerta desaparece solo después de una ejecución sin fallos.

## Ver también

- [Visión general de Pagos](/hc/ajuda/articles/payments-overview-es)
- [Crear un cobro y enviarlo en la conversación](/hc/ajuda/articles/payments-criar-cobranca-enviar-na-conversa-es)
- [Reembolsos, webhooks e informes](/hc/ajuda/articles/payments-reembolsos-webhooks-relatorios-es)

- [Planes de cobro y talonario de pagos](/hc/ajuda/articles/payments-planos-de-cobranca-es)

- [Página pública de cobro](/hc/ajuda/articles/payments-pagina-publica-de-cobranca-es)