¶ BTG Pactual
A integração com o BTG Pactual permite que o HubSoft se comunique com o banco via API para realizar operações de cobrança bancária. Com ela, é possível:
- Emitir boletos bancários
- Alterar vencimento de boletos
- Cancelar boletos
- Verificar e receber confirmações de pagamento
⚠️ Atenção — V1 Descontinuada
A versão V1 da integração foi descontinuada a partir de maio/2026. Todas as novas credenciais devem ser geradas utilizando a V2. Se o seu provedor ainda utiliza a V1, consulte o Guia de Migração V1 → V2 antes de prosseguir.
¶ Sumário
- Integração V2 (atual)
- Funcionalidades adicionais
- Integração V1 (legado)
- 🔄 Migrando da V1 para a V2
- Perguntas frequentes
¶ Integração V2 (atual)
¶ Gerar credenciais no painel BTG
Caso ainda não possua conta, abra sua conta BTG Pactual antes de prosseguir.
Com a conta aberta, libere o acesso ao painel de desenvolvedor para o seu usuário e acesse: console.developers.empresas.btgpactual.com.
Criando o aplicativo:
Acesse Aplicativos > Aplicativos:
Certifique-se de que o ambiente está definido como Produção e clique em Criar Aplicativo:
Na etapa Dados do aplicativo, preencha os campos obrigatórios:
| Campo | Valor |
|---|---|
| Nome do aplicativo | Nome de sua preferência |
| Tipo | Confidencial |
| Descrição do aplicativo | Descrição de sua preferência |
| Modelo de integração | First party |
| E-mail para notificações | E-mail responsável |
Na etapa Escopos utilizados, selecione exatamente os seguintes escopos:
- Perfil do usuário —
openid - Banking: Cobrança —
brn:btg:empresas:banking:collectionsebrn:btg:empresas:banking:collections.readonly
⚠️ Atenção com os escopos de Banking: existem dois escopos com nomes parecidos no painel. O correto para esta integração é o que contém
collectionsno identificador. Confirme antes de continuar.
Na etapa Descrição da Operação, preencha os dados da sua empresa (Atuação, Segmento e Volume financeiro):
Em Resumo, confirme que os escopos de collections estão presentes e clique em Continuar para salvar o aplicativo:
Coletando as credenciais:
Com o aplicativo criado, acesse Aplicativos > ⋯ (três pontos) > Detalhes:
Clique na aba Chaves e copie o Client ID e o Client Secret. Esses valores serão necessários na próxima etapa:
¶ Cadastrar integração no HubSoft
No HubSoft, acesse Menu lateral > Configuração > Integrações > Pagamento:
Clique em Adicionar:
Selecione BTG Pactual como Gateway de Pagamento e preencha os parâmetros obrigatórios:
| Parâmetro | Descrição |
|---|---|
versao |
v2 |
client_id |
Client ID coletado no painel BTG |
client_secret |
Client Secret coletado no painel BTG |
id_conta |
ID da conta no formato CNPJ-CODIGOBANCO-AGENCIA-CONTA (código do banco BTG: 208). Exemplo: 29507487000185-208-50-005568035 |
Clique em Salvar. Após salvar, o sistema irá gerar uma Callback URL — copie-a, pois será necessária nas próximas etapas:
¶ Configurar URL de redirecionamento e webhook
Volte ao painel do BTG, acesse o aplicativo criado e clique em Detalhes:
Clique em Editar Aplicativo:
URL de redirecionamento:
No campo URLs de redirecionamento, cole a Callback URL copiada do HubSoft. Avance pelas etapas de Escopos clicando em Continuar:
No Resumo, verifique se a URL de redirecionamento aparece corretamente, clique em Continuar, confirme a mensagem solicitada e clique em Confirmar:
Webhook:
Ainda no painel do BTG, acesse a aba Webhooks e clique em Adicionar Webhook:
Cole a Callback URL do HubSoft, adicione uma descrição e clique em Adicionar Eventos:
Expanda a seção Cobranças, selecione o evento collections.paid e clique em Adicionar eventos:
Clique em Adicionar Webhook para salvar:
¶ Gerar Authorization Code
O BTG utiliza um fluxo de autenticação OAuth que exige uma autorização manual no banco para liberar a emissão de boletos. Antes de iniciar, verifique no painel BTG se o status da versão mais recente do aplicativo está como Ativo:
⚠️ Atenção: Após editar versões do aplicativo no BTG, o
client_ide oclient_secretpodem ser alterados automaticamente. Confira se os valores cadastrados no HubSoft ainda são os mesmos exibidos no painel antes de prosseguir.
Com o status Ativo confirmado, no HubSoft acesse a integração e clique em Ações > Gerar Authorization Code:
Você será redirecionado para a tela de login do BTG. Faça login com seu CPF e senha:
Selecione todos os checkboxes exibidos para autorizar o acesso da API à sua conta:
Ao confirmar, você será redirecionado para uma tela de sucesso informando que o código foi gerado e vinculado à integração. Pode fechar essa aba:
¶ Testar a integração
Com o Authorization Code vinculado, acesse no HubSoft Menu lateral > Configuração > Integrações > Integração de Pagamento > Ações > Testar Integração:
Se a autenticação retornar sucesso, a integração está configurada corretamente:
¶ Configurar Forma de Cobrança
A Forma de Cobrança vincula a integração BTG aos clientes do provedor.
Acesse Menu lateral > Configuração > Financeiro > Forma de Cobrança:
Clique em Adicionar uma Forma de Cobrança, selecione BTG Pactual como banco e escolha a integração recém-criada:
Na aba Configuração, preencha os demais dados conforme sua operação e salve:
✅ Pronto! Sua integração com o BTG Pactual está configurada. Você já pode emitir boletos pelo HubSoft de forma integrada ao banco.
¶ Funcionalidades adicionais
¶ Boleto + Pix
É possível emitir um Boleto com QR Code Pix embutido. Para ativar, adicione o parâmetro boleto_pix com o valor true na integração.
Com essa modalidade ativada, ao registrar um boleto, o sistema gera automaticamente um QR Code Pix com os mesmos dados, permitindo que o cliente pague pelo código de barras ou pelo Pix — em um único documento.
Requisito: é necessário ter uma chave Pix cadastrada na conta BTG para habilitar essa funcionalidade.
¶ Webhook
O webhook é responsável por notificar o HubSoft automaticamente quando um boleto é pago no BTG. Ele foi configurado na etapa 3. Configurar URL de redirecionamento e webhook.
Com o webhook ativo, assim que o pagamento for registrado no sistema do BTG, o HubSoft recebe a notificação e realiza a baixa do título.
Recomendação: mesmo com o webhook configurado, mantenha a Rotina de Verifica Cobrança Gateway ativa no HubSoft. Ela garante que nenhum boleto fique sem baixa em caso de falha na entrega do webhook.
¶ Integração V1 (legado)
⚠️ A V1 foi descontinuada em maio/2026.
Se o seu provedor já utiliza a integração V1, é necessário migrar para a V2 para continuar emitindo boletos normalmente. O processo não exige recriar tudo do zero — o aplicativo existente no BTG é aproveitado e apenas alguns ajustes são necessários.
Preparamos um guia completo com o passo a passo da migração. Clique abaixo para acessar:
As instruções abaixo são mantidas apenas como referência para provedores que ainda não concluíram a migração. Para novas integrações, utilize exclusivamente a V2.
¶ 1. Gerar credenciais no painel BTG
O processo de criação do aplicativo segue os mesmos passos iniciais da V2 (acessar o painel, definir ambiente como Produção e clicar em Criar Aplicativo). A diferença está nos Dados do aplicativo e nos Escopos.
Em Dados do aplicativo, preencha:
| Campo | Valor |
|---|---|
| Nome do aplicativo | Nome de sua preferência |
| Tipo | Confidencial |
| Descrição do aplicativo | Descrição de sua preferência |
| Modelo de integração | First party |
Em Escopos utilizados, selecione:
- Perfil do usuário
- Banking: Boleto Cobrança
Revise o Resumo e salve:
Com o aplicativo criado, acesse ⋯ > Detalhes > aba Chaves e copie o Client ID e o Client Secret.
¶ 2. Cadastrar integração no HubSoft
Acesse Menu lateral > Configuração > Integrações > Pagamento > Adicionar, selecione BTG Pactual e preencha os parâmetros:
| Parâmetro | Descrição |
|---|---|
client_id |
Client ID coletado no painel BTG |
client_secret |
Client Secret coletado no painel BTG |
id_conta |
No formato CNPJ-CODIGOBANCO-AGENCIA-CONTA. Código do banco: 208. Exemplo: 29507487000185-208-50-005568035 |
Clique em Salvar:
Copie a Callback URL gerada.
¶ 3. Configurar URL de redirecionamento e webhook
No painel BTG, edite o aplicativo criado e adicione a Callback URL no campo URLs de redirecionamento. O processo é idêntico ao da V2.
Para o webhook, o processo também é idêntico, com a diferença no evento: selecione bank-splits.paid (em vez de collections.paid):
¶ 4. Gerar Authorization Code e testar
O processo é idêntico ao da V2:
- Confirme que o status do aplicativo está Ativo no painel BTG.
- No HubSoft, acesse Ações > Gerar Authorization Code, faça login no BTG e autorize o acesso.
- Teste em Ações > Testar Integração.
¶ 5. Configurar Forma de Cobrança
Idêntico ao processo da V2: acesse Configuração > Financeiro > Forma de Cobrança, adicione uma nova forma com BTG Pactual e preencha as configurações.
¶ Migrando V1 para a V2
⚠️ A V1 foi descontinuada em maio/2026.
Se o seu provedor já utiliza a integração V1, é necessário migrar para a V2 para continuar emitindo boletos normalmente. O processo não exige recriar tudo do zero — o aplicativo existente no BTG é aproveitado e apenas alguns ajustes são necessários.
Preparamos um guia completo com o passo a passo da migração. Clique abaixo para acessar:
As instruções abaixo são mantidas apenas como referência para provedores que ainda não concluíram a migração. Para novas integrações, utilize exclusivamente a V2.
¶ Perguntas frequentes
A integração transmite baixas automáticas para o BTG?
Sim. Para ativar, certifique-se de que o parâmetro transmite_baixa está definido como true na integração. Com isso, recebimentos na empresa, descontos totais e outros eventos de baixa serão transmitidos automaticamente ao BTG. Se o parâmetro não estiver preenchido, as baixas não são transmitidas.
Por que o boleto do cliente não registrou via API?
Erros de registro costumam estar relacionados a dados cadastrais do cliente ou a problemas de comunicação com o gateway. Por serem situações específicas, recomendamos acionar o suporte HubSoft para que possamos identificar a causa e auxiliar na resolução com agilidade.
