Pagamento em Lote QRCodePix (Copia e Cola) via API PagBB
Objetivo
Este artigo apresenta a configuração e o uso da API BB Pagamento em Lote Pix (PagBB) V1.2.1, integração do BankPlus com o Banco do Brasil dedicada a pagamentos em lote por QRCodePix (Copia e Cola) — utilizada para quitação de boletos, guias (FGTS, tributos) e demais cobranças que disponibilizam a string Pix Copia e Cola.
Essa API é uma integração independente da API de pagamentos já existente no BankPlus (BB Pagamento Online V1.0). Ela possui servidor e contrato próprios, e é acionada exclusivamente para lançamentos do tipo QRCodePix. Os demais tipos de pagamento (demais chaves Pix, TED, boletos e tributos) continuam sendo processados pela API já existente, sem qualquer alteração.
⚠ | Atenção |
Particularidades desta API:
Para melhor visualização das imagens, clique sobre elas. |
Pré-requisitos
- Chamado de solicitação da aplicação: abertura de chamado no atendimento do BankPlus solicitando a criação da aplicação específica para a API PagBB.
- Certificado digital A1 válido do cliente, vinculado ao CNPJ do convênio de pagamentos.
- Número do contrato / convênio de Pagamentos em Lote do cliente junto ao Banco do Brasil, com o tipo de chave Copia e Cola habilitado no convênio.
- Credenciais de integração (Cliente ID, Chave Secreta e Chave de Aplicação), disponibilizadas pela Invent após a criação da aplicação.
A habilitação do tipo de chave Copia e Cola é definida por contrato junto ao Banco do Brasil. Recomenda-se confirmar essa habilitação com o banco antes de iniciar os pagamentos.
Configuração do contrato bancário
Acesse Administração > Contratos Bancários de Pagamento, selecione (ou crie) o contrato do Banco do Brasil e abra a aba API. Caso o cliente já utilize a API v1.0, crie um contrato secundário para esta API, conforme indicado na caixa de Atenção. Marque a opção Pagamento online via API.
Em Versão da API, selecione 001_PGBB_V1.2 - BB Pagamento em Lote Pix (PagBB) V1.2.1:
Versão da API: 001_PGBB_V1.2 - BB Pagamento em Lote Pix (PagBB) V1.2.1.
Em Tipo de Ambiente, selecione Teste ou Produção, conforme o ambiente do cliente:
Tipo de Ambiente: 1 - Teste ou 2 - Produção.
Preencha as credenciais fornecidas pela Invent:
- Cliente ID e Chave Secreta: credenciais da aplicação, utilizadas na autenticação OAuth2.
- Chave de Aplicação: corresponde à APP-KEY da aplicação.
- URL para Token e URL de Pagamento Pix em Lote: endereços do Banco do Brasil, trazidos conforme o ambiente selecionado.
Campos Cliente ID, Chave Secreta e Chave de Aplicação (APP-KEY) a preencher.
Em Certificado Digital, selecione o certificado A1 do cliente vinculado ao convênio:
Certificado Digital: selecione o certificado A1 correspondente (não deixar como "Não informada").
Teste de comunicação
Com a configuração preenchida, clique em Testar Comunicação. Em caso de sucesso, o sistema realiza a autenticação com o Banco do Brasil e exibe o token gerado com sua respectiva validade. Confirme a geração do token antes de prosseguir para o envio de pagamentos.
Contrato preenchido (credenciais mascaradas) e certificado selecionado — botão "Testar Comunicação".
Realizando o pagamento QRCodePix (Copia e Cola)
Na tela Administração de Pagamentos, o lançamento do tipo QRCodePix ficará disponível para os contratos do Banco do Brasil configurados com esta API. A captura da string Copia e Cola é feita da mesma forma já utilizada no fluxo de pagamento.
- Selecione o(s) título(s) a pagar e informe a string Copia e Cola do QRCodePix.
- Envie o pagamento pela opção de envio online por API.
- Ao ser aceito pelo banco, o lote é incluído e cada lançamento recebe um protocolo próprio.
Envio agrupado (vários pagamentos em um lote) pela Ordem de Pagamento
Além do envio individual pela tela de Administração de Pagamentos, é possível agrupar vários pagamentos QRCodePix em um único lote pela tela de Ordem de Pagamento Eletrônico. Pela tela de Previsões, cada pagamento gera um lote (100 pagamentos = 100 lotes); pela Ordem de Pagamento, os pagamentos selecionados são consolidados em um único lote com vários lançamentos, enviado, liberado e liquidado de uma só vez.
Caminho: Administração de Pagamentos → aba Previsões / Pagamentos → Ordem de Pagamento Eletrônico. Todos os pagamentos agrupados devem usar o mesmo contrato bancário de débito.
1. Agrupar as previsões em um único lote
Clique em Novo → Inclusão Pagamento Online; na Seleção de Previsões, selecione os pagamentos QRCodePix que deseja enviar juntos. Todos os selecionados serão consolidados em um único lote.
Seleção de múltiplas previsões (QRCodePix) para compor um único lote.
Previsões selecionadas agrupadas — total consolidado do lote.
2. Gerar a Ordem de Pagamento (remessa)
Gere a Ordem de Pagamento com as previsões selecionadas. A ordem é criada com status "Aberto" e um arquivo de remessa associado.
Ordem de Pagamento gerada com status "Aberto", contendo os lançamentos agrupados.
3. Processar / enviar a Ordem
Processe a Ordem de Pagamento. Após o envio, o status passa para "Processado" e a ordem é movida para a aba "Processadas".
Ordem processada — status "Processado" com data/hora de processamento.
4. Conferir o recebimento do lote no banco
No portal do banco (PagBB Digital), o lote é recebido com a situação "Aguardando liberação", já consolidando todos os lançamentos enviados.
Lote recebido no banco com situação "Aguardando liberação" e vários lançamentos.
5. Liberar o lote no banco
Realize a liberação do lote. A situação passa para "Liberado", autorizando o processamento dos pagamentos.
Lote com situação "Liberado" após a liberação.
6. Liquidação / baixa no add-on
Após o pagamento pelo banco, a Consulta de pagamento online por API atualiza as previsões no BankPlus para situação "Liquidado", habilitando a baixa automática do título no SAP.
Comportamento conhecido — ocorrência 422/3024
Mensagem: [422 - 3024 - Liberação permitida apenas para estado de lote igual a Pendente ou Pendente de Liberação. Aguarde alguns instantes e tente novamente].
Não é falha. Ocorre quando a liberação é acionada após o lote já estar agendado no banco — a liberação só é aceita enquanto o lote está em "Pendente" / "Pendente de Liberação". Quando a liberação válida já ocorreu, o lote segue normalmente para Liberado → Liquidado.
Ocorrência 422/3024 registrada no histórico — comportamento esperado (lote já agendado).
Observações
- O agrupamento consolida vários lançamentos em um único lote; a liberação do lote inteiro é feita em uma única ação no banco.
- Caso um lançamento do lote seja rejeitado pelo banco na inclusão, verifique o motivo apresentado na mensagem do pagamento antes de reenviar.
- Para dúvidas sobre habilitação de convênio, alçadas de liberação ou credenciais, abra chamado no atendimento do BankPlus.
Liberação do pagamento e tratamento do retorno 3031
Na API PagBB, o pagamento ocorre em duas etapas: inclusão do lote e liberação do lote. O banco leva alguns instantes entre a inclusão e o lote ficar disponível para liberação. Quando a liberação é solicitada antes de o banco concluir o processamento, o retorno é 3031 — "Lote não encontrado nas bases do banco".
Para esse cenário, o BankPlus passou a:
- Ao receber o 3031 após a inclusão, não travar o lote: os pagamentos ficam na situação "Aguardando Liberação", com mensagem orientando a liberar em alguns instantes.
- Disponibilizar a ação "Liberar Pagamento", que consulta o lote no banco e só dispara a liberação quando o estado está "Aguardando liberação do lote". Dando certo, o pagamento passa para "Agendado"; se o lote ainda não estiver disponível, permanece em "Aguardando Liberação" para nova tentativa.
A ação "Liberar Pagamento" está disponível no menu API Online da Administração de Pagamento. São aceitos apenas pagamentos em "Aguardando Liberação" e com protocolo; pagamentos do mesmo lote são liberados em uma única requisição.
"Liberar Pagamento" no menu API Online da Administração de Pagamento:
Não é permitido cancelar um boleto que esteja em "Aguardando Liberação". A Ordem de Pagamento avisa quantos boletos estão aguardando liberação no banco.
Acompanhamento dos estados
A consulta reflete a situação de cada lançamento na tela de acompanhamento, conforme o estado retornado pelo Banco do Brasil:
Estado no Banco do Brasil | Situação no BankPlus |
Aguardando liberação do lote | Aguardando Liberação |
Processando / Aguardando saldo / Aguardando banco recebedor / Agendado | Agendado |
Pago | Liquidado (habilita a baixa automática no SAP) |
Rejeitado | Rejeitado |
Cancelado | Cancelado |
Pix Devolvido Total / Parcial | Estorno |
Quando o lançamento é liquidado (situação Pago), a baixa automática do título é realizada no SAP. Em caso de devolução, o valor, a data e o motivo são apresentados na mensagem do pagamento.
Observações
- Esta API atende exclusivamente lançamentos do tipo QRCodePix (Copia e Cola). Qualquer outro tipo de pagamento enviado a ela é bloqueado com mensagem específica — os demais tipos devem ser processados pelo contrato configurado com a API v1.0.
- A leitura/OCR de imagem de QR Code não é contemplada; a string Copia e Cola é informada manualmente pelo usuário.
- Para dúvidas sobre habilitação de convênio, alçadas de liberação ou credenciais, abra chamado no atendimento do BankPlus.