Primeiros Passos - API Pagamentos

Com a API de Pagamentos automáticos, seus clientes poderão realizar a programação de pagamentos e os extratos ficarão em um único lugar, agilizando o processo de gestão de contas a pagar.

Neste artigo você terá todas as informações para conseguir realizar os cadastros e gerar um pagamento seguindo os seguintes passos.

 

• Como conseguir o Token da Sofware House
• Cadastro do Pagador
• Cadastro de Conta
• Notificações
  • Criar notificações
• Transmissão automática
  • Como solicitar a Transmissão Automática junto ao Banco
  • Como preencher a carta para a transmissão automática
  • Tempo de envio e retorno de arquivos enviado via VAN Nexxera
• Fluxo ideal para emissão de Pagamentos

 

 

---

Como conseguir o Token da Sofware House

 

Para que seja possível dar inicio a integração com a API de Pagamentos, seria necessário primeiramente localizar o token da Sofware House.

O token da Software House é disponibilizado no portal de contas da TecnoSpeed, que pode ser acessado através da URL: https://conta.tecnospeed.com.br/.

A tela inicial de login que será apresentada é esta:

Assim que for realizado o acesso à página, será solicitado o e-mail e senha cadastrado, e se no caso você ainda não possuir este cadastro, é preciso somente clicar em Criar uma conta e informar e-mail, nome completo, CPF ou CNPJ e a senha para acesso.

Ao realizar o login será apresentada esta tela:

Para que você consiga adquirir o token da Software House basta clicar em Ver meu token, botão que fica localizado na parte central da página.

Lembramos que é de suma importância guardar este token, pois ele será utilizado para autenticar as requisições feitas pela API de Pagamentos.

---

Cadastro do Pagador

Antes de fazer qualquer ação no produto, é necessário fazer o cadastro do pagador, ou seja, cadastrar o CNPJ do pagador e as contas que irão gerar os pagamentos.

Este processo é feito através da rota abaixo:

POST

 Homologação:

 Produção:

 

Headers

 

Nome	Tipo	Descrição
cnpjsh	String	CPF ou CNPJ da Software House que possui contrato com a Tecnospeed
tokensh	String	Token da Software House. É disponibilizado no portal de contas da TecnoSpeed, que pode ser acessado através da URL: https://conta.tecnospeed.com.br/.
content-Type	String	Tipo de mídia, preencher com application/json. Exemplo: Content-Type: application/json

 

 

Body

 

Campo	Tipo	Descrição	Tamanho
name	string	Nome ou Razão Social do pagador.	<=250
email	string	Email do pagador	<=250
cpfCnpj	string	CPF ou CNPJ do pagador	<=18
accounts	array of objects	para ver o restante dos campos, acesse o link
ddaActived	boolean	Campo que define se o pagador cadastrado possuirá o serviço de DDA ativo ou não (a ativação necessita e contrato prévio com a Tecnospeed)
street	string	Logradouro do pagador. Nome da Rua, Av, Pça, Etc.	<=250
adressNumber	string	Número do Local do pagador.	<=10
neighborhood	string	Informar o Bairro do pagador.	<=250
adressComplement	string	Complemento de endereço do pagador. Casa, Apto, Sala, Etc	<=250
city	string	Nome da Cidade do pagador.	<=250
state	string	Sigla do Estado (UF) do pagador. Utilizar 2 caracteres. Ex: SP, RJ, PR, MG...	<=2
zipcode	string	CEP do pagador	<=10

 

---

Cadastro de Conta

O passo seguinte será efetuar o cadastro de contas.

POST

 Homologação:

 Produção:

 

Headers

 

Nome	Tipo	Descrição
cnpjsh	String	CPF ou CNPJ da Software House que possui contrato com a Tecnospeed
tokensh	String	Token da Software House. É disponibilizado no portal de contas da TecnoSpeed, que pode ser acessado através da URL: https://conta.tecnospeed.com.br/.
payercpfcnpj	String	CPF ou CNPJ do Pagador
content-Type	String	Tipo de mídia, preencher com application/json. Exemplo: Content-Type: application/json

 

 

Body

 

Campo	Tipo	Descrição	Tamanho
CedenteRazaoSocial	string	Razão Social do Cedente	1 - 200
CedenteNomeFantasia	string	Nome Fantasia do Cedente	1 - 200
CedenteCPFCNPJ	string	CPF ou CNPJ do Cedente	11 (CPF) ou 14 (CNPJ)
CedenteEnderecoLogradouro	string	Endereço do Cedente	1 - 200
CedenteEnderecoNumero	string	Número do logradouro do endereço	1 - 10
CedenteEnderecoComplemento	string	Complemento do endereço	1 - 100
CedenteEnderecoBairro	string	Nome do bairro	1 - 100
CedenteEnderecoCEP	string	CEP do Cedente	8
CedenteEnderecoCidadeIBGE	string	Código IBGE da cidade do Cedente	7 (clique aqui para consultar o código de sua cidade)
CedenteTelefone	string	Número do telefone do Cedente	11
CedenteEmail	string	E-mail do Cedente	1 - 150

 

---

Notificações

Os Webhooks são as notificações que enviamos para você sempre que um evento ocorre, ou seja, sempre que seus pagamentos sofrerem alguma alteração oriunda dos retornos gerados pelo banco.

A cada atualização, o sistema envia um HTTP POST para a URL configurada no webhook, com todas as informações relevantes sobre cobranças, pedidos, assinaturas, entre outros. Desta maneira, o seu sistema, ao receber essa notificação, pode executar os próximos passos.

Você tem total liberdade para escolher sobre quais eventos quer ser notificado e para qual URL cada webhook será enviado.

 

Criar notificação

A rota a seguir mostrará como criar notificações.

Atenção: É importante ressaltar que o envio das notificações webhook estão disponíveis apenas para o ambiente de produção.

 

POST

 Homologação:

 Produção:

 

Headers

 

Campo	Tipo	Descrição
cnpjsh	String	CPF ou CNPJ da Software House que possui contrato com a Tecnospeed
tokensh	String	Token da Software House. É disponibilizado no portal de contas da TecnoSpeed, que pode ser acessado através da URL: https://conta.tecnospeed.com.br/.
payercpfcnpj	String	CPF ou CNPJ do Pagador
content-Type	String	Tipo de mídia, preencher com application/json. Exemplo: Content-Type: application/json

 

 

Body

 

Campo	Tipo	Descrição	Tamanho
CedenteRazaoSocial	string	Razão Social do Cedente	1 - 200
CedenteNomeFantasia	string	Nome Fantasia do Cedente	1 - 200
CedenteCPFCNPJ	string	CPF ou CNPJ do Cedente	11 (CPF) ou 14 (CNPJ)
CedenteEnderecoLogradouro	string	Endereço do Cedente	1 - 200
CedenteEnderecoNumero	string	Número do logradouro do endereço	1 - 10
CedenteEnderecoComplemento	string	Complemento do endereço	1 - 100
CedenteEnderecoBairro	string	Nome do bairro	1 - 100
CedenteEnderecoCEP	string	CEP do Cedente	8
CedenteEnderecoCidadeIBGE	string	Código IBGE da cidade do Cedente	7 (clique aqui para consultar o código de sua cidade)
CedenteTelefone	string	Número do telefone do Cedente	11
CedenteEmail	string	E-mail do Cedente	1 - 150

 

---

Transmissão automática

 

A Transmissão Automática é um recurso que faz o envio da Remessa e o upload do Retorno sem manipulação de arquivos. Ou seja, quando gerada a remessa, ela será encaminhada ao banco automaticamente, sem a necessidade de salvar em arquivo.

O mesmo vale para o arquivo de retorno, quando disponibilizado pelo banco, será processado pela API automaticamente, não sendo necessário baixar o arquivo no internet banking e encaminhar para a nossa API.

• Como solicitar a Transmissão Automática junto ao Banco

Iniciando o processo de liberação da Transmissão Automática na instituição bancária:

Passo 1: Preenchimento da Carta

Para começarmos o processo de ativação da Transmissão Automática para sua conta, o primeiro passo é preencher a Carta de Abertura de Relacionamento.

Alguns bancos podem solicitar a integração com a própria carta, caso a sua solicitação seja para os bancos Sicredi, Banco do Brasil ou Itaú, estão disponíveis as seguintes arquivos:

Sicredi

Banco do Brasil

Itaú

*** Junto ao preenchimento da carta, não alterar os dados referente aos responsáveis técnicos, para que o processo de liberação junto a Nexxera possa seguir normalmente.

 

Passo 2: Entrega da carta à Tecnospeed

A carta preenchida pelo correntista com as informações da conta precisa ser enviada à Tecnospeed, via chat ou ticket, para que nós possamos iniciar por aqui o fluxo de liberação da Transmissão Automática.

Após nos entregar as cartas um ticket registrando o pedido será aberto, e para que o processo se conclua com sucesso e no menor tempo possível, é essencial que a mesma carta seja entregue ao banco para que o mesmo inicie o processo de configuração e ativação da Transmissão Automática das remessas e retornos (explicaremos com mais detalhes este processo na sequência).

 

Passo 3: Entrega da Carta ao banco e validação das remessas

Após preencher a carta com os dados da conta do cliente, é necessário encaminhá-la ao gerente bancário responsável pela conta do cedente, informando a necessidade de trafegar arquivos de Cobrança Registrada com a VAN Nexxera (caso o gerente tenha dificuldades em fazer este processo, logo abaixo traremos com mais detalhes o processo nos principais bancos);

*Exceto para o banco SICOOB, onde não é necessário a carta para abertura de relacionamento, a abertura deve ser feita diretamente no Internet Banking.

Ao entregar ao gerente da conta as cartas, é de fundamental importância que você também solicite a ele o processo de validação das remessas geradas. Para isso, utilize a nossa rotina de geração de remessas para gerar pelo menos 10 arquivos (a quantidade varia de acordo com o banco) e encaminhe-as ao gerente para a validação.

Feito isso, assim que o banco concluir todas as configurações ele notificará a Nexxera/Tecnospeed para que nós possamos prosseguir com o processo de liberação

Desta forma, tendo qualquer novidade sobre o andamento e assim que estiver tudo pronto nós te avisaremos pelo ticket!

 

Mas e se o banco gerente tiver dificuldades em iniciar o processo de liberação?

Por via de regra, a orientação junto aos bancos é solicitar uma alteração na forma como as remessas e retornos são recepcionados.
Deixando de ser via internet banking, e passando a ser via VAN.

 

• Como preencher a carta para a transmissão automática

Para o preenchimento da carta, é necessário informar os dados referente ao cedente (Emissor da cobrança), abaixo seque um modelo da carta utiliza para a abertura de relacionamento.

As informações destacadas na cor amarela deve ser substituídas pelos dados do cedente.

Segue abaixo os links das cartas de transmissão:

Abaixo temos uma dica de preenchimento para os campos destacados:

• Banco - Nome do banco onde será solicitado a transmissão automática.

• Agência - Agência do cedente (Informar DV se tiver).

• Cidade - Cidade onde esta localizada a empresa do cedente.

• UF - Estado onde esta localizada a empresa do cedente.

• A/C - Informar o nome do gerente da conta.

• Fone - Telefone para contato do cedente.

• Serviço no Banco - Serviço utilizado no banco, informar PAGAMENTO.

• Conta/DV - Conta completa com DV (Mesmo valor cadastrado para o cedente).

• Convênio: - Informar o mesmo convênio cadastrado para o cedente.

• Layout Cliente - CNAB utilizado pelo cedente (240 ou 400).

• RAZÃO SOCIAL - Razão Social do cedente.CNPJ - CNPJ ou CPF do cedente.

• NOME - Nome do solicitante.

• CARGO - Cargo do solicitante dentro da empresa.

• FONE - Telefone para contato do solicitante.

• E-MAIL - E-mail para contado do solicitante.

 

• Como habilitar a Transmissão Automática

Assim que o processo de Transmissão Automática for concluído, a alteração na forma de transmissão (da transmissão manual para a transmissão automática) será feita totalmente por nós da TecnoSpeed.

Portanto, no momento em que a solicitação para a transmissão automática for finalizada pelo banco e pela Nexxera, nossos consultores entrarão em contato com a Software House informando que o novo recurso já está disponível pra uso e se a Software House desejar.

Após habilitada a transmissão automática é necessário apenas chamar a rota/método de geração da remessa com os pagamentos que deseja transmitir ao banco. A partir deste momento, o tráfego de arquivos (remessas e retorno) passará a ser feito pela Tecnospeed.

 

• Tempo de envio e retorno de arquivos enviado via VAN Nexxera

• Entendendo o fluxo de envio de remessas e retornos:

De forma simplificada podemos sintetizar o processo de envio e recepção de remessas da seguinte forma:

Passo 1: Remessa é enviada ao banco via VAN Nexxera;

Passo 2: Remessa é processada pelo banco e gera um retorno;

Passo 3: Conciliação do retorno.

O processo de envio e recebimento de remessas é algo bem simples, contudo, por conta da particularidade de cada banco o tempo de envio e recebimento para os arquivos variam de banco para banco.

Para os principais bancos elaboramos um descritivo, mostrando qual o tempo de envio de remessas e recebimento de retornos para o serviço de Pagamentos:

• Bradesco:

Envio: Pagamentos enviados até 17:59 autorizados

Retorno: 2 horas para o processamento.

• Itaú:

Envio: Pagamentos enviados até 17h, após este horário será bloqueado.

Retorno: 2 horas para o processamento.

• Santander:

Envio: Pagamentos enviados até às 17h podem ser autorizados. Após às 17h será bloqueado. Pagamentos a receber até às 20hrs.

Retorno: Próximo dia útil

• Banco do Brasil:

Envio: Pagamentos enviados até 17:59 autorizados

Retorno: Próximo dia útil

---

Fluxo ideal para emissão de Pagamentos

A fim de facilitar a integração de nossos clientes e parceiros, elaboramos este breve descritivo para mostrar de uma forma intuitiva e modelada o fluxo ideal de emissão de pagamentos, utilizando a nossa solução para integração de Pagamentos.

Tudo começa com a geração do JSON em seu sistema

Em nossa integração, as informações dos Pagamentos podem ser passadas via JSON, com campos padronizados. Ou seja, independente do banco ou tipo de pagamento**, os campos dos pagamentos terão o mesmo nome

**vale lembrar temos alguns tipos de pagamentos e bancos com campos específicos, porém descritos na documentação.

É claro, existem particularidades entre bancos, como o Banco X exigir determinado campo, enquanto que o mesmo campo não é aceito pelo Banco Y. Mas estes são detalhes que vamos acertando no momento de homologar o pagamentos junto ao banco. O que importa é que com esta padronização, o esforço no desenvolvimento para homologar diferentes bancos fica muito reduzido!

 

E a partir daqui, esta é a sequencia do fluxo:

1º - Inclusão do JSON de Pagamento: Ou seja, é o momento que você pega o JSON que seu sistema montou e envia para nossa API (via https). Nós recebemos este arquivo e te devolvemos um uniqueID, que é um ID único que vai identificar seu pagamento em nosso sistema. Esse ID é importante porque para algumas partes do fluxo nós iremos utilizá-lo.

2º - Gerar a remessa desse pagamento: É o momento que realizamos a geração desse remessa de pagamento para o envio ao banco. Vale lembrar que atualmente contamos com a forma de envio automática, que pode ser vista com melhores detalhes nessa mesma documentação, buscando por: “Transmissão automática”

3º - Aguardar a conciliação do retorno bancário: Para esse passo, basta aguardar o prazo estipulado pelo banco para a conciliação bancária, para a grande maioria dos bancos o envio de pagamentos tem um tempo médio de processamento e envio de retorno entre 2 à 4h a partir do momento que o arquivo for enviado ao banco.

4º - Consultar o uniqueID: É o momento que consultamos o pagamento em nosso banco de dados, para sabermos se se ele está com uma das seguintes situações:

• CREATED - Pagamento criado na API da Tecnospeed;
• PAID (*) - Pagamento efetivado e confirmado pelo banco;
• SCHEDULED (*) - Pagamento agendado junto ao banco;
• CANCELLED (*) - Solicitação de pagamento cancelada junto ao banco;
• REJECTED (*) - Pedido de pagamento rejeitado pelo banco;
• REFUNDED (*) - Pagamento devolvido pelo banco.

*Status que serão alterados apenas após existir a conciliação bancária.

Para facilitar a compreensão, segue também o modelo com a sequência de fluxos:

Vale lembrar que além destes métodos modelados acima, temos também diversos outros métodos, incluindo:

• Notificações via Webhook;
• Emissão de um comprovante de pagamento;
• Consulta de bilhetagem;
• Conciliação de Extrato bancário via VAN(OFX);
• Pagamentos em Lote

---