Este manual tem como objetivo orientar sobre a configuração e o uso da integração de pagamento por cartão de crédito com a prestadora iPag (Sicoob), no modelo Checkout.
Introdução
Na integração iPag, o inscrito seleciona os débitos nos canais on-line do BRConselhos e é direcionado ao ambiente de pagamento da própria operadora para informar os dados do cartão. Após a aprovação, o iPag notifica o BRConselhos automaticamente e o sistema registra a transação e efetua a baixa dos títulos, sem intervenção manual.
Diferente das integrações por certificado digital, a comunicação é feita via API REST — não há certificado físico a instalar ou renovar.
Configuração
Cadastro da integração
Acesso: Interno > Parâmetros > Integrações > botão ‘Novo’.
Na aba Geral, informe:
- Tipo Integração: ‘Integração IPAG’
- Descrição: identificação livre do cadastro
- Ativo: habilita a integração
- Timeout (s): tempo limite de espera das chamadas à API
- Ambiente da Integração: ‘Homologação’ ou ‘Produção’
- Url: endereço base da API, conforme o ambiente
- Api Key: ClientID da conta, disponível no painel do iPag
- Api Token: token de acesso da conta, disponível no painel do iPag
- Email Notificação: e-mail para avisos da integração
- Certificado e Senha Certificado: não se aplicam ao iPag — a autenticação é por credenciais, sem certificado digital
A aba Itens relaciona os endereços (endpoints) da API do iPag utilizados pelo sistema — links de pagamento, consulta e cancelamento de transações e gestão dos webhooks. Os itens já vêm cadastrados com a integração e não exigem manutenção pelo usuário.
Concluído o preenchimento, utilize o botão Testar Conexão, na barra superior da tela, para validar as credenciais antes de ativar a integração.
Usuário do webhook
A confirmação de pagamento enviada pelo iPag é processada no BRConselhos por um usuário específico, cadastrado em Interno > Usuários > Novo > Nome/User “webhook_iPag”. Esse usuário deve ser criado manualmente, com permissão de inscrito — ele não é criado pela atualização de versão.
É esse usuário que aparece como responsável pelo agendamento de baixa e pelos movimentos gerados automaticamente, o que permite identificar com clareza o que foi baixado pela integração.
Parâmetros da prestadora de cartão
Acesso: Interno > Parâmetros > Financeiro > Parâmetro do módulo Financeiro > Integração Cartão > Geral > botão ‘Novo’.
Na aba Geral, informe:
- Descrição: identificação da prestadora
- Prestadora: ‘IPAG (Checkout)’
- Tipo de integração: ‘Web Service’
- Exercício: exercício em que a prestadora pode ser utilizada
- Ativo: ao ativar o iPag, as demais prestadoras ativas são automaticamente inativadas
- Integração: seleciona o cadastro criado em Interno > Parâmetros > Integrações — é este vínculo que informa ao sistema quais credenciais e URL utilizar
- Forma liquidação e Histórico movimento: alimentados pelos cadastros de Financeiro > Cadastros básicos > Formas liquidação e de históricos de movimento; são os valores que o sistema grava no movimento de baixa
- Usuário WebHook: usuário criado conforme o item anterior
- Locais: telas em que o pagamento com cartão fica disponível (Requerimento on-line, Impressão anuidades, Renegociação simplificada e Impressão taxas)
Na aba Tipo Lançamento, informe os tipos de lançamento que poderão ser pagos pela prestadora e, para cada um, a Qtd Mínima Parcelas, a Qtd Máxima Parcelas e o valor mínimo de parcela. Essas regras se sobrepõem às da integração e são o que limita as opções de parcelamento oferecidas no checkout.
Webhook de confirmação de pagamento
Pré-requisito: a notificação enviada pelo iPag não é recebida diretamente pelo BRConselhos. Quem recebe é a API de webhook do BRConselhos, uma aplicação instalada separadamente do sistema, que registra a notificação e a encaminha ao BRConselhos para a baixa — assim as confirmações continuam sendo recebidas mesmo que o sistema esteja momentaneamente indisponível, e processadas em seguida. A instalação dessa API é feita pela equipe técnica e é o endereço dela, acompanhado do token do cliente, que deve ser informado como URL de retorno no cadastro do webhook.
O webhook é o mecanismo pelo qual o iPag avisa o BRConselhos de que um pagamento foi concluído. O cadastro é feito no painel da conta do iPag, em Webhooks, informando:
- Descrição: identificação do webhook
- URL de retorno: endereço do serviço de recebimento de notificações do BRConselhos, acompanhado do token do cliente
- Método Http: POST
- Eventos: o evento de pagamento de link concluído com sucesso (PaymentLinkPaymentSucceeded)
Outras configurações
Caso necessário, cadastre a forma de liquidação a ser usada pela prestadora em Financeiro > Cadastros básicos > Formas liquidação. Ela ficará disponível para seleção no campo Forma liquidação da Integração Cartão.
Utilização
Pagamento pelo inscrito
Nas telas habilitadas no campo Locais (Requerimento on-line, Impressão anuidades, Renegociação simplificada e Impressão taxas), o inscrito seleciona um ou mais débitos e escolhe o pagamento com cartão de crédito. É possível pagar vários títulos em uma única transação — o sistema soma os valores selecionados.
O sistema então apresenta as formas de pagamento:
- Parcela única: pagamento à vista, com o desconto de pagamento antecipado aplicado, quando o título tiver desconto;
- Parcelado: o desconto de pagamento antecipado não é aplicado, e o número de parcelas é escolhido no checkout da operadora.
Ao avançar, o inscrito é direcionado ao ambiente de pagamento do iPag, já com os dados do comprador preenchidos a partir do cadastro da pessoa no BRConselhos (nome, e-mail, CPF/CNPJ e celular). O inscrito informa os dados do cartão, confere o resumo da compra e finaliza.
As opções do campo Parcelamento respeitam a parametrização da aba Tipo Lançamento: são ofertadas apenas as parcelas que atendem ao valor mínimo e ao limite de parcelas configurados. No pagamento à vista, a única opção apresentada é 1x.
Confirmação e baixa automática
Concluído o pagamento, o iPag notifica o BRConselhos e a transação é registrada em Financeiro > Transações Cartão, com o Tipo Transação Venda, o identificador da transação e as colunas Aprovada e Baixado no Sistema.
Na sequência, a baixa é encaminhada por meio de um agendamento, consultável em Interno > Agendamento tarefas/documentos, com o Serviço “Baixa de pagamento de cartao”. No agendamento constam:
- User: o usuário do webhook configurado na Integração Cartão;
- Propriedades: a transação de cartão e a prestadora que originaram a baixa;
- Avisos: o resultado do processamento, com a chave da transação (ex.: “Pagamento efetuado com sucesso chave: …”).
Concluída a baixa, o título fica quitado e o movimento é gravado no contas a receber com a Forma liquid. e o Histórico definidos na Integração Cartão, tendo o usuário do webhook como criador do registro. Quando o envio de e-mail está habilitado, o inscrito recebe a confirmação do pagamento.
Notificações repetidas do mesmo pagamento não geram baixa em duplicidade.
Transações pendentes de baixa
Acesso: Interno > Parâmetros > Financeiro > Integração Cartão > botão ‘Configurações IPAG’.
A tela lista as transações capturadas no iPag em um período (campos De e Até e botão Buscar), com filtro por ID, NSU, pedido, método ou situação. As informações exibidas — ID iPag, NSU, pedido, valor, método, situação e data da captura — vêm da consulta feita diretamente ao iPag.
É a rotina de conciliação para os casos em que a notificação do iPag não chegou ao BRConselhos: o botão Reenviar baixa, na linha da transação, solicita ao iPag o reenvio da notificação. Com isso o sistema roda novamente o agendamento de baixa, seguindo o mesmo processamento automático descrito acima.
Cancelamento e estorno
Para cancelar a venda por completo, acesse Financeiro > Transações Cartão, abra a transação e utilize o botão Cancelar Pagamentos iPag. O sistema lista os títulos baixados naquela transação; ao clicar em Cancelar e confirmar a mensagem, o cancelamento é enviado ao iPag.
Concluído o cancelamento, é gerado um novo registro em Transações Cartão com o Tipo Transação Cancelamento no Dia, e os títulos que constavam na venda retornam à situação A receber.
Para o estorno de um movimento específico, acesse Financeiro > Posição Financeira, selecione o título pago, abra a aba Movimentos e utilize a opção Estornar (botão direito). A operação exige Dupla Confirmação.
Validações e mensagens de retorno
- “Credenciais (ClientID/ClientSecret) do iPag não configuradas.” — exibida no Testar Conexão quando as credenciais não foram informadas no cadastro da integração.
- “Unauthorized” — exibida no Testar Conexão quando as credenciais informadas são inválidas.
- “Conexão bem-sucedida.” — comunicação com o iPag validada.
- “Confirma o cancelamento desta transação?” — confirmação exigida antes do cancelamento da venda.
- Pela tela Transações Cartão só é permitido o cancelamento total da venda; estornos parciais são feitos por Posição Financeira > Movimentos > Estornar.
- Quando o título tem desconto de pagamento antecipado e o inscrito opta pelo parcelamento, o desconto não é aplicado e o valor encaminhado ao checkout é o valor cheio.
- Quando o valor do débito não é suficiente para atender ao valor mínimo de parcela configurado, o parcelamento é bloqueado.
Considerações finais
A integração com o iPag mantém a experiência de pagamento já conhecida pelo inscrito e reduz o trabalho manual da tesouraria: a confirmação do pagamento e a baixa dos títulos passam a ocorrer de forma automática, com a rotina de reenvio disponível para tratar as exceções.