Guia de Integração | BTG Pactual

---

1. Introdução

A integração com APIs Bancárias para a emissão de cobranças representa um avanço estratégico para empresas que buscam automatizar e otimizar sua gestão financeira. Ao conectar diretamente o SGP às instituições bancárias, elimina-se a necessidade de processos manuais, como geração de arquivos de remessa e importação de retornos, reduzindo significativamente erros operacionais e retrabalhos.

Entre os principais benefícios dessa integração destacam-se:

• Automatização do processo de cobrança: o boleto é emitido e registrado automaticamente no banco a partir do SGP, garantindo maior agilidade e conformidade com as regras bancárias.

• Redução de erros e inconsistências: a comunicação direta evita falhas comuns em processos manuais, como duplicidade de boletos ou divergências de valores.

• Maior segurança e confiabilidade: os dados são transmitidos de forma padronizada e segura, minimizando riscos de fraudes ou informações incorretas.

• Controle centralizado: todas as informações financeiras ficam concentradas no SGP, facilitando o acompanhamento de recebimentos e inadimplência.

• Agilidade na tomada de decisão: relatórios atualizados permitem uma visão clara da saúde financeira da empresa.

Assim, a integração bancária não apenas simplifica o processo de cobrança, mas também proporciona maior eficiência operacional, segurança e controle estratégico sobre o fluxo de caixa da organização.

Antes de iniciar o processo, consulte nossa FAQ – Atenção à Segurança da sua Integração! para garantir uma implementação mais segura e eficiente.

2. Dados necessários para integrar ao SGP

Nesta etapa, será realizado o cadastro do portador, etapa fundamental para a correta emissão dos boletos.

Requisitos obrigatórios:

• Número da agência;

• Número da conta com dígito;

• Número da Carteira (Se diferente de 50);

Atenção: Os dados cadastrados serão utilizados diretamente na geração dos boletos. Isso significa que informações como nosso número, código de barras e linha digitável dependem totalmente da configuração realizada neste cadastro.

3. Integração do Portador

Mesmo sendo uma integração via API, os dados da conta são necessários para a emissão dos boletos.

Na guia Dados Bancários configure os campos abaixo com os dados fornecido pelo banco:

Em seguida, na guia Relacionamentos da Empresa selecione:

Confirme essas informações com o cliente para evitar rejeição de boletos por dados incorretos.

Por fim, devemos configurar os Juros e Multa, acessando a guia Juros, Multas, Descontos e Taxas

O BTG aceita apenas as opções:

Para uma melhor compreensão, recomendamos a leitura da nossa documentação de Configuração de Juros e Multa

4. Ponto de Recebimento (Caixa)

O ponto de recebimento é o local onde os pagamentos de boletos serão registrados. 

5. Cadastro do Gateway de Boletos

Nesta etapa da documentação, abordaremos a integração da API bancária do BTG Pactual, incluindo as APIs de Boleto, Boleto + PIX e PIX Avulso.

Para realizar essa integração, serão necessários alguns dados e arquivos, como:

• Account ID

O Account ID é formado pela junção de quatro dados da Conta, separados por traço (-), seguindo a estrutura abaixo:

CNPJ - Código do Banco - Código do Tipo de Conta - Número da Conta (com dois zeros à esquerda)

Exemplo: 12345678000199-208-50-001234567

• Client ID 

• Client Secret

• Chave PIX (Em integrações com PIX)
  

As demais credenciais são exclusivamente geradas na plataforma do BTG Pactual

Com os dados em mãos, podemos integrar o Gateway ao SGP para emissão de boletos.

Clique no botão Cadastrar e preencha da seguinte forma:

6. Cadastro do Gateway de Boleto + PIX Avulso

O caminho de acesso é o mesmo do cadastro de Gateway de Boleto, apenas devemos ajustas os dados preenchidos.

Atenção: A integração com o BTG Pactual não oferece suporte à emissão de boletos híbridos. Atualmente, a geração de boleto e PIX é realizada separadamente, dentro do mesmo gateway, como cobranças avulsas.

Clique no botão Cadastrar e preencha da seguinte forma:

7. Cadastro do Gateway de PIX

O caminho de acesso é o mesmo do cadastro de Gateway de Boleto, apenas devemos ajustas os dados preenchidos.

Esse modelo de integração é apenas para emissão de QRCode PIX, caso queira uma integração de Boleto + PIX, usar o processo da seção anterior!

1. Nome da Integração : Insira  "BTG Pactual" no campo correspondente.
2. Adicione uma Descrição ;

3. Configuração de Credenciais :

   • No campo  Token, insira o Account ID conforme orientado na Coleta de credenciais.

   • No campo  Usuário , insira o Client ID coletado anteriormente.

   • No campo Senha , insira o Client Secret . coletado anteriormente

4. Habilite a opção "Pagamentos via PIX" marcando a checkbox correspondente
5. Selecione o portador do BTG Pactual que foi previamente integrado.
6. Inseria a URL de Notificação no padrão a seguir:

   URL_SGP/api/btgpactual/IDGATEWAY/notificacao/

7. Para facilitar a resolução de problemas, marque a checkbox Debug .
   

8. Salve as alterações para concluir a integração.

Imagem de Referência (API PIX)

8. Autorizando Integração

Esse processo será realizado após a integração, quando a aplicação criada for aprovada pelo BTG.

• No Menu Principal, acesse Financeiro (❶), depois vá em Cadastros (❷) e, em seguida, clique em Gateway de Pagamento (❸).

1. Após a finalização do cadastro, utilizar o botão da chave para autorizar a API para uso:
2. Ao clicar na chave será direcionado a tela de login do BTG.
3. Após realizar o login devemos verificar se os escopos estão corretos e continuar. (Open Id, Boletos, Pix Cobrança)
4. Na próxima etapa devemos selecionar a empresa correta e continuar.
5. Dando tudo certo, no canto superior esquerdo se exibido a mensagem Update Ok
   • Também deve ser preenchido automaticamente o campo Parâmetros JSON do Gateway
6. Com isso o processo de autorização está concluído, basta gerar um boleto de teste para validar.

9. Informações Adicionais

Para essa integração existem dois tipos de PIX o Pix Cob e Pix CobV :

• Pix Cob : Gera um QR Code para pagamento imediato, sem data de vencimento. Ideal para pagamentos instantâneos e avulsos. Nessa modalidade, no SGP esse PIX expira no dia do vencimento do boleto.
  • Sendo possivel usar o parâmetro abaixo para gerar um novo pix atualizado após expirar.

    forcar_atualizacao_pix=1

• Pix CobV (Cobrança com Vencimento)  : Permite definir uma data de vencimento e aplicar juros, multas e descontos. Usado para cobranças recorrentes, como boletos. Nessa modalidade, no SGP o PIX acompanha o "vencimento" do boleto atualizando Multa e Juros diários. Pode ser habilitado com o uso do seguinte parâmetro:

  pixvencimento=1

Para usar os parâmetros acima é preciso verificar com o banco quais escopos estão ativos para a sua conta.