¶ BTG Pactual — Migração V1 para V2
⚠️ A V1 foi descontinuada em maio/2026. Todos os provedores que utilizam a integração V1 devem realizar a migração para a V2 para continuar emitindo boletos normalmente.
A migração não exige criar um novo aplicativo no BTG do zero — o aplicativo existente será atualizado com os novos escopos e configurações exigidos pela V2. No HubSoft, basta atualizar a versão na integração, limpar o código anterior e gerar uma nova autorização.
¶ Sumário
- Atualizar o aplicativo no painel BTG
- Atualizar a integração no HubSoft
- Gerar novo Authorization Code
- Testar a integração
¶ Atualizar o aplicativo no painel BTG
Acesse o painel de desenvolvedor BTG em console.developers.empresas.btgpactual.com, localize o aplicativo existente e clique em ⋯ (três pontos) > Detalhes:
Clique em Editar Aplicativo:
¶ Dados do aplicativo
Na etapa Dados do aplicativo, adicione o campo que não existia na V1:
- E-mail para notificações: e-mail responsável pela integração
Os demais campos (nome, tipo, descrição, modelo de integração) já estão preenchidos, não é necessário alterá-los. Clique em Continuar.
¶ Escopos
Na etapa Escopos, a V2 exige escopos diferentes da V1. Adicione os novos:
- Banking: Cobrança —
brn:btg:empresas:banking:collections - Banking: Cobrança (leitura) —
brn:btg:empresas:banking:collections.readonly
Clique em Continuar.
¶ Descrição da Operação
A V2 exige o preenchimento de um novo campo que não existia na V1. Preencha os dados da sua empresa:
- Atuação
- Segmento
- Volume financeiro
Clique em Continuar.
¶ Resumo e confirmação
Revise o Resumo e confirme que os escopos de collections estão presentes. Clique em Continuar, confirme a mensagem solicitada e clique em Confirmar:
¶ Atualizar o webhook
Ainda no painel do BTG, acesse a aba Webhooks. O webhook existente está configurado com o evento bank-splits.paid (V1). Para a V2, é necessário adicionar o evento collections.paid.
Identifique o Webhook da sua empresa, e clique em Detalhes:
Ao acessar a edição do webhook, verá que existe apenas o evento legado, clique em Selecionar Evento:
Expanda a seção Cobranças, selecione collections.paid e clique em Adicionar eventos:
Clique em Adicionar Webhook para salvar:
¶ Verificar credenciais
Após salvar as alterações, o BTG pode gerar um novo client_id e client_secret. Acesse Detalhes > aba Chaves e confira se os valores foram alterados:
Se os valores forem diferentes dos que estão cadastrados no HubSoft, copie os novos — eles serão necessários na próxima etapa.
Por fim, aguarde o status da versão mais recente do aplicativo ficar como Ativo antes de prosseguir:
¶ Atualizar a integração no HubSoft
Realize essa atualização somente quando a versão mais recente da aplicação no BTG estiver com o status Ativo.
Caso ainda esteja em processamento, é necessário aguardar antes de realizar a virada para a V2 na HubSoft, evitando a interrupção da integração que está funcionando atualmente.
No HubSoft, acesse Menu lateral > Configuração > Integrações > Pagamento e abra a integração BTG Pactual existente para edição.
Atualize os seguintes campos:
| Parâmetro | Valor anterior (V1) | Valor correto (V2) |
|---|---|---|
versao |
(não preenchido) | v2 |
client_id |
Valor anterior | Novo valor, se alterado pelo BTG |
client_secret |
Valor anterior | Novo valor, se alterado pelo BTG |
Os demais parâmetros (id_conta, transmite_baixa, boleto_pix, etc.) permanecem iguais.
Clique em Salvar.
¶ Gerar novo Authorization Code
Realize essa atualização somente quando a versão mais recente da aplicação no BTG estiver com o status Ativo.
Caso ainda esteja em processamento, é necessário aguardar antes de realizar a virada para a V2 na HubSoft, evitando a interrupção da integração que está funcionando atualmente.
O Authorization Code gerado na V1 não é compatível com a V2 e precisa ser refeito.
Ainda na integração, acesse Ações e localize o parâmetro code e remova o mesmo, removendo o vínculo anterior. Em seguida, 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 a tela de sucesso. O novo código já está vinculado à integração — pode fechar essa aba:
¶ Testar a integração
Com o novo Authorization Code vinculado, acesse Ações > Testar Integração para confirmar que a migração foi concluída com sucesso:
Autenticação retornando sucesso — migração concluída!
✅ Pronto! A integração está operando na V2. Os boletos continuarão sendo emitidos normalmente pelo HubSoft.
