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

1. Objetivo e escopo

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

• Boleto Multi Bancos, via PlugBoleto (TecnoSpeed)
• Pix Multi Bancos, via API Pix (TecnoSpeed)

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 inteiramente na tela Contas (trnconta) do CentriumPag.

O fluxo básico é: o cliente já cadastrado em trncliente recebe uma conta 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 ou Cedente, 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 abrir a tela Contas para iniciar o cadastro, é preciso ter em mãos:

1. Cliente já cadastrado em trncliente. (link do processo).
2. Dados bancários completos do banco em questão (ver seção 7, específica de cada banco).
3. Credenciais de acesso ao banco ou ao portal do desenvolvedor (ver seção 7).
4. Certificado, quando o banco exigir (ver seção 7).

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 trnconta

A tela de cadastro de conta é dividida nos seguintes blocos:

4.1 Dados de identificação

• Gateway (seleção: Boleto Multi Bancos ou Pix Multi Bancos)
• Nome da Conta
• Cliente

4.2 Dados Bancários

Campos variam por banco — ver seção específica de cada banco.

4.3 Certificado

Campos: upload do arquivo (.pfx, .csr, .cer ou .p12), senha, validade do certificado e status de publicado (sim ou não).

O certificado só deve ser cadastrado depois que o Convênio estiver publicado e ativo. Ver ordem completa na seção 5.

4.4 Taxas

Tipo e valor da taxa de desconto, tipo de partilha do desconto entre gateway e Centrium, e tipo e valor da taxa cobrada pelo Centrium.

4.5 Dados de Conexão Gateway (Credenciais)

Campos comuns na tela, com valores específicos por banco:

• 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
• ChavePix

4.6 Blocos de integração (Company ou Cedente, Account, Convênio)

Cada bloco (Company Multi Bancos, Account Multi Bancos, Convênio Multi Bancos, ou Cedente, dependendo do banco) tem um campo de ID, um status (ativo ou inativo) e um botão que muda de função conforme o estado do cadastro. Quando o ID ainda está vazio, aparece só o botão Cadastrar. Depois que o ID é gerado, esse botão desaparece e no lugar aparecem Consultar, Alterar e Inativar.

Cada um desses botões dispara uma chamada própria e independente à API da TecnoSpeed. Por isso o cadastro é feito manualmente, campo a campo, o que permite identificar sucesso ou falha isoladamente em cada bloco, sem precisar refazer o processo inteiro se um deles falhar.

4.7 Configurações Centrium Postback (exclusivo do Pix)

Campos: Host, Base URL, Usuário Centrium e Senha Centrium. São o endereço e as credenciais de acesso ao Centrium Web do próprio cliente. Depois que o CentriumPag recebe do banco a confirmação de que um Pix foi pago, ele repassa esse status para o Centrium Web do cliente através desse canal. O ícone ao lado do campo de senha testa a conexão com o ambiente do cliente.

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

4.8 WebHook (exclusivo do Pix)

Campo: URL Postback Gateway. É o endpoint do próprio CentriumPag que recebe, via webhook, a notificação do banco (TecnoSpeed) informando que um Pix foi pago. É esse recebimento que dispara o repasse ao Centrium Web descrito no item 4.7. O botão Configurar registra essa URL do lado do banco, Info mostra o status e o detalhe da configuração atual, e Desconfigurar remove o registro.

Url Postback Gateway: https://centriumpag.azurewebsites.net/APICentriumPag/Post_TecnoSpeed_Pix

4.9 Client ID, Client Secret e Token (exclusivo do Pix)

Campos: Client ID, Client Secret, Token, Escopo do Token e Validade.

Ao cadastrar a Company, o CentriumPag envia por e-mail ao cliente os dados de Client ID e Client Secret gerados para aquela conta. Esses dados, recebidos por e-mail, precisam ser preenchidos e confirmados aqui antes de seguir para o cadastro da Account: sem essa confirmação não é possível cadastrar a Account do Pix.

O botão Atualizar Token serve para validar se a credencial está funcionando. Basta atualizar e conferir se o campo Validade foi atualizado com uma nova data.

5. Passo a passo genérico

1. Selecionar o Cliente, escolher o Gateway e Confirme. O Nome da conta recebe um default no Insert e abre novamente em Update para continuar.
2. Preencher os Dados Bancários.
3. Preencher os Dados de Conexão Gateway considerando 6. Especificadades por Banco.
4. Cadastrar a Company Multi Bancos. No caso do Pix, ao cadastrar a Company o CentriumPag envia por e-mail ao cliente o Client ID e o Client Secret daquela conta; esses dados precisam ser preenchidos na Conta e confirmados na Transação. Ao retornar a TrnConta a ação Atualizar Token pode ser utilizada para validar se o Client ID e Client Secret funcionaram.
5. Cadastrar a Account Multi Bancos e, na sequência, o Convênio Multi Bancos se for Boleto. Depois de cada cadastro, atualizar a página para que o ID seja carregado e o botão correspondente passe a mostrar Consultar, Alterar e Inativar.
6. Cadastrar o Certificado, somente depois que o Convênio estiver ativo.
7. Configurar as Taxas se não forem default (ver com comercial).
8. No caso do Pix, configurar também o Postback (endereço do Centrium Web do cliente) e o WebHook (endpoint do CentriumPag que recebe a confirmação de pagamento do banco).
9. Confirmar.

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 ou Cedente) 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 TecnoSpeed	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 TecnoSpeed da API Pix, documentação TecnoSpeed do PlugBoleto, Pasta de Apoio com os certificados no repositório interno, e contatos de suporte por banco, a preencher conforme forem levantados.