Cadastro de Cliente e Conta – Gateway Multi Bancos (Pix e Boleto)

1. Objetivo e escopo

Observação: Este processo inicia-se somente após a criação da melhoria
https://wiki.centrium.com.br/financeiro/pix-por-api-obtencao-de-credenciais-sicredi/

Este documento orienta o cadastro de cliente e contas no CentriumPag utilizando o Gateway Multi Bancos, nas duas modalidades :

• Boleto Multi Bancos
• Pix Multi Bancos

Ambos seguem o mesmo processo estrutural de integração, diferindo apenas nos dados bancários exigidos e nos identificadores de integração.

2. Visão geral da arquitetura

O cadastro acontece no Centrium Pag. https://centriumpag.azurewebsites.net/

O fluxo básico é: após receber os dados bancários e credenciais de conexão com o Banco. Cadastrar ou Encontrar o Cadastro do Cliente na trncliente. Cadastrar os dados em trnconta, que reúne dados bancários, credenciais de conexão com o gateway, certificado e taxas do Centrium Pag. A partir dessa conta são cadastrados os dados de integração (Company, Account e Convênio, dependendo do tipo), que são os identificadores usados na comunicação com o banco. Cada um desses blocos tem seu próprio status (ativo ou inativo) e suas próprias ações, independentes entre si, mas seguindo uma hierarquia de pertencimento ao anterior.

3. Pré-requisitos e checklist pré-cadastro

Antes de acessar o Centrium Pag para iniciar os cadastros, é preciso ter em mãos:

1. Dados bancários completos do banco em questão (ver seção 7, específica de cada banco).
2. Credenciais de acesso ao banco ou ao portal do desenvolvedor (ver seção 7).
3. Certificado, quando o banco exigir (ver seção 7).
4. Um usuário do pra configurar a conexão (centriumPag) Centrium Web.

Reunir tudo isso antes de começar evita cadastro parcial e retrabalho, principalmente porque as credenciais costumam depender de acesso a portais externos ao Centrium que nem sempre estão disponíveis no momento do cadastro.

4. Estrutura de dados na tela TrnCliente

O Cadastro do Cliente é bem simples. Devemos apenas nos atentar para o campo Email.

O Pix Multi Banco não permite cadastrar Company com o email duplicado e esse email é frequentemente utilizado para enviar comunicados a respeito de certificados. Como a Centrium quer monitorar essa comunicação nós sempre criamos um email pra cada cliente dentro do nosso [clienteempresa]@centrium.com.br. Essa cadastro pode ser solicitado ao Superviso de Desenvolvimento e o endereço e senha registrados na Abertura da Mudança. Ao receber os dados do email cadastrar um redirecionamento para cobranca-api@centrium.com.br

No caso do Boleto Multi Banco não existe o bloqueio do uso do mesmo email e podemos cadastrar direto o cobranca-api@centrium.com.br

5. Estrutura da tela TrnConta

A tela TrnConta concentra todas as informações necessárias para a integração entre o CentriumPag, a Integradora e o banco. Os campos são organizados em blocos independentes, cada um responsável por uma etapa da configuração da conta.

Valor Taxa Cobrada pelo Centrium (0,55)

Embora todos pertençam à mesma conta, alguns blocos possuem dependências entre si e devem ser cadastrados em uma ordem específica, descrita na seção 6. Passo a passo genérico.

5.1 Dados de identificação

Identificam a conta dentro do CentriumPag.

Campos:

• Gateway – Selecionar Boleto Multi Bancos ou Pix Multi Bancos.
• Nome da Conta – Identificação da conta no sistema.
• Cliente – Cliente ao qual a conta pertence.

---

5.2 Dados bancários

Contêm as informações bancárias necessárias para registrar a conta no banco.

Os campos variam conforme a instituição financeira e o tipo de integração. Consulte a seção 7. Especificidades por Banco para verificar quais informações são obrigatórias em cada caso.

---

5.3 Certificado

Utilizado pelos bancos que exigem autenticação por certificado digital.

Campos:

• Arquivo do certificado (.pfx, .p12, .cer ou .csr, conforme o banco);
• Senha;
• Data de validade;
• Indicador de publicação.

Importante: o certificado somente deve ser cadastrado após o Convênio estar criado, publicado e ativo. Consulte a sequência correta na seção 6. Passo a passo genérico.

---

5.4 Taxas

Define as taxas utilizadas pelo CentriumPag para aquela conta.

Campos:

• Tipo da taxa de desconto;
• Valor da taxa de desconto;
• Tipo de partilha do desconto entre Gateway e Centrium;
• Tipo da taxa Centrium;
• Valor da taxa Centrium.

Caso a conta utilize a configuração padrão, normalmente não é necessário alterar esses valores.

---

5.5 Dados de Conexão Gateway

Reúnem as credenciais utilizadas pelo CentriumPag para autenticação junto ao gateway e ao banco.

Dependendo da instituição financeira, apenas parte desses campos será utilizada.

Campos disponíveis:

• Banco – App Key;
• Banco – Client ID;
• Banco – Client Secret;
• Versão do Web Service;
• Beneficiário;
• Empresa;
• Estação;
• Contrato;
• Tipo Modalidade;
• Senha do Convênio;
• Cooperativa;
• Ambiente;
• Variação da Carteira;
• Chave Pix.

As informações necessárias para preenchimento variam conforme o banco e estão descritas na seção 6 Especificidades por Banco.

---

5.6 Blocos de integração

Representam os recursos cadastrados na Integradora para aquela conta.

Dependendo do banco e do gateway utilizado, poderão existir os seguintes blocos:

• Company Multi Bancos;
• Account Multi Bancos;
• Convênio Multi Bancos (Boleto).

Cada bloco possui:

• um identificador (ID);
• um status (Ativo ou Inativo);
• ações próprias de integração.

Enquanto o ID ainda não existe, o bloco apresenta apenas a ação Cadastrar.

Após o cadastro ser concluído e o ID ser retornado pela Integradora, passam a ficar disponíveis as ações:

• Consultar;
• Alterar;
• Inativar.

Cada ação realiza uma chamada independente para a API da Integradora. Dessa forma, caso ocorra falha em um dos blocos, basta corrigir e repetir apenas aquela operação, sem necessidade de refazer todo o cadastro da conta.

---

5.7 Configuração de Postback (exclusivo para Pix)

Define como o CentriumPag comunica ao Centrium Web do cliente que um Pix foi liquidado.

Campos:

• Host;
• Base URL;
• Usuário Centrium;
• Senha Centrium.

Após receber a confirmação de pagamento do banco, o CentriumPag utiliza essas informações para enviar o retorno ao ambiente do cliente.

O botão ao lado do campo de senha permite testar a comunicação com o Centrium Web.

Exemplo:

• Host: vaztpr6xyz.apps.centrium.inf.br
• Base URL: /APICentrium

---

5.8 WebHook (exclusivo para Pix)

Define o endereço que será registrado junto à Integradora para recebimento das notificações automáticas de pagamento.
Deverá ser “Configudado” após o cadastro Aconut na Integradora.

Campo:

• URL Postback Gateway

Exemplo:

https://centriumpag.azurewebsites.net/APICentriumPag/Post_TecnoSpeed_Pix

Ações disponíveis:

• Configurar – registra o webhook na Integradora;
• Info – consulta a configuração atualmente cadastrada;
• Desconfigurar – remove o webhook.

---

5.9 Client ID, Client Secret e Token (exclusivo para Pix)

Após o cadastro da Company, a Integradora envia ao e-mail do cliente o Client ID e o Client Secret gerados para aquela conta.

Esses dados devem ser informados nesta tela antes do cadastro da Account, pois são utilizados para autenticação na API Pix.

Campos:

• Client ID (enviado por email);
• Client Secret (enviado por email);
• Token;
• Escopo do Token;
• Validade.

Depois de informar as credenciais, utilize a ação Atualizar Token para validar a autenticação.

A validação é considerada bem-sucedida quando um novo Token é obtido e o campo Validade é atualizado.

6. Especificidades por Banco

Cada seção abaixo segue o mesmo modelo: dados de identificação, dados bancários, credenciais, certificado e observações. Preencher uma seção por combinação de banco e tipo de conta (Pix ou Boleto).

7. Validação pós-cadastro

Depois de concluir o cadastro, consultar cada bloco (Company, Account e Convênio) e confirmar que o status está ativo. Se algum bloco falhar ou vier inativo, basta corrigir e reprocessar aquele bloco especificamente, sem precisar refazer o cadastro inteiro, já que as ações são independentes entre si.

8. Passos finais, comuns a qualquer banco ou gateway

Para concluir a configuração, criar um usuário no CentriumPag para que o cliente consiga acessar o serviço. Depois, repassar ao Suporte, para configuração no ambiente do cliente: o Código do Cliente, o GUID da Conta e o Usuário do CentriumPag.

9. Problemas comuns

Situação	Possível causa	O que fazer
Botão Cadastrar não some depois do cadastro	O ID (Company, Account ou Convênio) ainda não foi carregado	Atualizar a página
Falha ao cadastrar o Convênio	Company ou Account não foram cadastrados antes, ou fora de ordem	Refazer respeitando a ordem: Company, depois Account, depois Convênio
Bloco fica inativo depois do cadastro	Erro de retorno da Integradora	Consultar o bloco individualmente para ver o detalhe do erro e reprocessar apenas aquele bloco
Certificado rejeitado	Cadastrado antes do Convênio estar ativo	Aguardar o Convênio ficar publicado e ativo antes de cadastrar o certificado

10. Referências

Documentação Integradora da API Pix, documentação Integradora, Pasta de Apoio com os certificados no repositório interno, e contatos de suporte por banco, a preencher conforme forem levantados.