Integración de Hubsoft con BTG Pactual

Acerca de BTG Pactual

BTG Pactual es un banco brasileño de inversiones, con sede en São Paulo. La plataforma BTG Pactual Empresas ofrece cuenta empresarial, tarjeta, anticipo de cuentas por cobrar y crédito para negocios. Para el proveedor, la cuenta empresarial de BTG funciona como banco de cobranza: las credenciales de integración se obtienen en el panel de desarrollador del propio banco.

Qué hace la integración

La integración utiliza la API de cobranza de BTG (versión V2) y la API de Pix Automático.

• Boleto bancario: emisión, cambio de fecha de vencimiento y cancelación de boletos bancarios desde Hubsoft.
• Boleto bancario con Pix: el registro del boleto bancario genera un código QR de Pix con los mismos datos. El suscriptor paga mediante el código de barras o Pix, en el mismo documento.
• Confirmación automática: BTG notifica a Hubsoft por webhook cuando se paga el boleto bancario y la factura queda liquidada. La rutina de verificación de cobros de Hubsoft comprueba los pagos si alguna notificación no llega.
• Confirmaciones transmitidas al banco: con la opción activa, los pagos recibidos en la empresa y los descuentos totales también se envían a BTG.
• Pix Automático: el suscriptor autoriza la recurrencia una sola vez y las mensualidades siguientes se debitan en la fecha acordada. La activación puede realizarse desde la Central del Suscriptor y la Aplicación del Cliente.

Qué necesitas

• Cuenta BTG Pactual Empresas y acceso al panel de desarrollador habilitado para tu usuario.
• Una aplicación creada en el panel de BTG, en producción, con los permisos de cobranza.
• Una clave Pix en la cuenta BTG, para el boleto bancario con Pix.
• Módulo Financiero de Hubsoft, incluido en la licencia.

Cómo activarlo

1. En el panel de desarrollador de BTG, crea la aplicación con los permisos de cobranza y copia el Client ID y el Client Secret.
2. En Hubsoft, en Configuración > Integraciones > Pago, agrega BTG Pactual en la versión v2, con las credenciales y el ID de la cuenta.
3. Copia la URL de callback que genera Hubsoft y regístrala en la aplicación de BTG como URL de redireccionamiento y como webhook del evento de boleto bancario pagado.
4. Con la aplicación activa en BTG, usa Acciones > Generar Authorization Code en Hubsoft y autoriza el acceso con el inicio de sesión del banco.
5. Prueba en Acciones > Probar integración y crea la forma de cobro de BTG en Configuración > Finanzas > Forma de cobro.
6. Para Pix Automático, agrega BTG en Configuración > Integraciones > PIX, con agencia, cuenta, monto mínimo de la recurrencia y política de reintentos, y vincúlalo a la forma de cobro.

El paso a paso con las pantallas está en la wiki de Hubsoft: boleto bancario BTG Pactual y Pix Automático BTG Pactual.

Limitaciones

• La versión V1 de la integración de boletos bancarios fue descontinuada en mayo de 2026. Quienes aún usan la V1 deben migrar a la V2, según la guía de migración.
• Con BTG, el Pix disponible es Pix Automático. El código QR de Pix individual viene junto con el boleto bancario, en la modalidad boleto bancario con Pix.
• Al editar la aplicación en el panel de BTG, el Client ID y el Client Secret pueden cambiar. Verifica los valores en Hubsoft después de cada modificación.
• Pix Automático no aplica descuento por pago antes del vencimiento: el monto autorizado es el monto total de la factura.

Preguntas frecuentes

¿Por qué necesito generar un Authorization Code?

BTG exige que el titular de la cuenta inicie sesión en el banco y autorice el acceso de la API. Sin esta autorización, Hubsoft no puede emitir boletos bancarios.

¿La integración envía las confirmaciones a BTG?

Sí, cuando la opción de transmitir confirmaciones está activa en la integración. Los pagos recibidos en la empresa y los descuentos totales se envían al banco.

¿El suscriptor debe autorizar Pix Automático todos los meses?

No. La autorización se realiza una vez en la aplicación bancaria del suscriptor y es válida para los cobros siguientes.

Ya uso la V1. ¿Debo crear todo de nuevo?

No. Se aprovecha la aplicación existente en BTG. Solo debes actualizar los permisos y el webhook en el panel, cambiar la versión en Hubsoft y generar un nuevo Authorization Code.

Revisado el 10/10/2026.