Base de Conhecimento de Gestão Comercial de Saneamento

A maior base de documentação de GSAN do mercado mantida pela Consenso Tecnologia

Ferramentas do usuário

Ferramentas do site


integracoes:api-pagamento


API Pagamento

Documentação do funcionamento da API Pagamento construída para trabalhar com todos os Sistemas Comerciais suportados pela Consenso.

Este documento é direcionado para empresas administradoras de serviços de pagamento por cartão que necessitem integrar o GSAN com seu portfólio de serviços financeiros.

A API possui o recurso de segurança através de token, facilitando a habilitação e desabilitação de novos parceiros. Utiliza plataforma REST com simples, utilizando JSON como protocolo padrão.

Fluxo de Pagamento por Cartão

A seguir o fluxo completo do pagamento descrevendo os processos de autorização, pagamento do compromisso pela credenciada, resposta de autorização e baixa do pagamento pelo movimento arrecadador, até a baixa definitiva no GSAN.

sequence

Autenticação

Os endpoints que nescessitem autenticação serão informados abaixo. Os mesmos precisarão ter as seguintes chaves, client_secret e client_id, no cabeçalho HTTP, a chave em questão foi gerada para o ambiente de testes:

  • client_id: CREDENCIADA
  • client_secret: <HASH 256b>

ENDPOINT CONSULTAR DÉBITOS

Usar FLUXO DE ERRO PADRÃO

POST(autenticar): HTTPS://ENDPOINTALVO:PORTA/gsan/api/debitos

JSON de consulta:

 {documento:"21469517000102"}

OU

 {matricula:"99999"}
Resposta:
{
   matricula: 99999,
   nome: "EMPRESA DE EXEMPLO",
   documento: "21469517000102",
   debitos:    [
      {
         id: "C#76108553",
         tipoDebito: "CONTA",
         valorOriginal: 3109.00,
         valorDebito: 3199.35,
         valorAcrescimos: 90.35,
         validadeDebito: "20180513",
         referencia: "04/2018",
         descricao: "REFERENCIA 04/2018"
      },
      {
         id: "G#527414",
         tipoDebito: "GUIA",
         valorOriginal: 32.5,
         valorAcrescimos: 0.00,
         valorDebito: 32.5,
         validadeDebito: "20181129",
         referencia: "04/2018",
         descricao: "CADASTRO LIG AGUA MED IND"
      },
      {
         id: "D#72478737",
         tipoDebito: "DEBITO A COBRAR",
         valorOriginal: 1.98,
         valorAcrescimos: 0.00,
         valorDebito: 1.98,
         referencia: "04/2018",
         descricao: "MULTA P/IMPONTUALIDADE PRESTACAO:0/1"
      }
   ]
}

ENDPOINT PESQUISAR DÉBITOS PARA EMISSÃO DE EXTRATO

Usar FLUXO DE ERRO PADRÃO

JSON de consulta:

{
   matricula:"452812"
}

Resposta:

{
 matricula:"452812",
 debitos: [
      {
      id: "C#7454122",
      tipoDebito: "CONTA",
      valorOriginal: 34.67,
      valorAcrescimos: 10.48,
      valorDebito: 45.15,
      validadeDebito: "17/01/2018",
      descricao: "MATRICULA: 452812 REFERENCIA: 01/2018"
   },
      {
      id: "G#472527",
      tipoDebito: "GUIA",
      valorOriginal: 80,
      valorAcrescimos: 0,
      valorDebito: 80,
      validadeDebito: "03/11/2017",
      descricao: "ENTRADA PARCELAMENTO      PRESTACAO:1 / 1"
   }
]}

ENDPOINT EMITIR EXTRATO

Usar FLUXO DE ERRO PADRÃO

O débito gerado neste endpoint deve ser notificado no ENDPOINT NOTIFICAR PAGAMENTOS. Não devem ser notificados os débitos retornados no ENDPOINT PESQUISAR DÉBITOS PARA EMISSÃO DE EXTRATO.

JSON de consulta:

{
   matricula:777985,
   debitos: [
            {
         id: "C#74481982"
      },{
         id: "G#472527"
      }
   ]
}

Resposta:

{
   matricula: 777985,
   debitos: [   {
      id: "E#17029415",
      codigoBarras: "826400000012251700412975001191624012702941514151",
      valorDebito: 125.17
   }]
}

ENDPOINT DESCONTO EXTRATO

Usar FLUXO DE ERRO PADRÃO

Esse endpoint não gera débito. Apenas retorna a matrícula e o valor de desconto com base nos débitos passados jo JSON de entrada.

JSON de consulta:

{
   matricula:777985,
   debitos: [
            {
         id: "C#74481982"
      },{
         id: "G#472527"
      }
   ]
}

Resposta:

{
   matricula: 777985,
   valorDesconto: 25.17
}

ENDPOINT NOTIFICAR PAGAMENTOS

Usar FLUXO DE ERRO PADRÃO

POST(autenticar): HTTPS://ENDPOINTALVO:PORTA/gsan/api/pagamentos/notificarPagamento

JSON de Consulta:

{
   identificacaoTransacao: "5462158456512",
   tipoCartao: "creditoAVista",  
   debitos:    [
            {
         id: "C#78422196",
	 autenticacao: "JHAJl765765765"
      },
            {
         id: "G#408204",
	 autenticacao: "6565163516516574654361351351351354531"
      }
   ]
}
{
   identificacaoTransacao: "5462158456512",
   tipoCartao: "debito",  
   debitos:    [
            {
         id: "C#78422196",
	 autenticacao: "JHAJl765765765"
      },
            {
         id: "G#408204",
	 autenticacao: "6565163516516574654361351351351354531"
      }
   ]
}
{
   identificacaoTransacao: "5462158456512",
   tipoCartao: "creditoParcelado",  
   debitos:    [
            {
         id: "E#408204",
	 autenticacao: "6565163516516574654361351351351354531"
      }
   ]
}

Resposta:

{status: "OK"}

ENDPOINT NOTIFICAR CANCELAMENTO DE PAGAMENTO

Usar FLUXO DE ERRO PADRÃO

POST(autenticar): HTTPS://ENDPOINTALVO:PORTA/gsan/api/pagamentos/notificarPagamento

JSON de Consulta:

{
   identificacaoTransacao: "5462158456512",
   status: "chargeback",
   debitos:    [
            {
         id: "C#78422196",
	 autenticacao: "JHAJl765765765"
      },
            {
         id: "G#408204",
	 autenticacao: "6565163516516574654361351351351354531"
      }
   ]
}

Resposta:

{status: "OK"}

ENDPOINT OBTER URL CHECKOUT

GET: HTTPS://ENDPOINTALVO:PORTA/gsan/api/pagamentos/obterUrlCheckoutEmpresaPagamento

Parâmetros de Consulta:

  • credenciada = identificacao da credenciada
  • codBarra = código de barras do documento
  • doc = cpf/cnpj do cliente
  • nome = Nome do cliente
  • id = identificação do débito fornecido pela API de emitir débito.

JSON Resposta:

{
  url: "https://example.com/?param=fsdfsdf5454f35s4df5sd4f",
  erro: false
}

Obs.: Este endpoint realiza um POST para o endpoint(com o token para acessar este endpoint) disponibilizado pela EMPRESA CREDENCIADA, passando como parâmetros:

  • codigoBarras = código de barras do documento
  • matricula = matrícula do imóvel [Opcional]
  • documento = cpf/cnpj do cliente [Opcional]
  • nome = Nome do cliente [Opcional]
  • id = identificação do débito fornecido pela API de emitir débito. [Opcional]

JSON Resposta:

{
  url: "https://example.com/?param=fsdfsdf5454f35s4df5sd4f"
}

FLUXO DE ERRO PADRÃO

Dicionário de código de erros em anexo.

Resposta:

{erro: {
   cod: 3,
   msg: "EMPRESA NAO CADASTRADA"
}}

Tabela de Erros:

CodigoErro
0NÃO TRATADO
1client_id obrigatório
2client_secret obrigatório
3EMPRESA NAO CADASTRADA
4chave inválida
100variável documento inexistente
101variável debitos inexistente
102variável debitos vazia
103variável nsu ou identificacaoTransacao inexistente
104cliente inexistente
105documento inválido
106documento obrigatório
107documento cadastrado para vários clientes na base
108identidicador do débito com formato inválido
109invoice_number vazio
110id do débito pago vazio
111autenticacao do débito pago vazia
112ID do débito inexistente na base
113status inexistente
114matricula inexistente
115imóvel não cadastrado
116extrato não permitido para imóvel
117variável credenciada inexistente
118matrícula obrigatória
119matrícula inválida
120 pagamento inexistente
121Este imóvel não tem perfil
122Já existe pagamento para documento

Apêndice 1 - Layout Arquivo de Remessa de Arrecadação

“Layout” Padrão de Arrecadação/Recebimento com Utilização do Código de Barras

Para as empresas que possuem serviço de VAN é necessário respeitar o layou abaixo, conforme Febraban V.04, para transmitir o movimento com o arquivo com os devidos pagamentos, o layout abaixo precisa ser respeitado, ver UC0262 para mais detalhes.

Distribuir Registro Código A (CABEÇALHO DO ARQUIVO)

DESCRIÇÃO DO REGISTRO A - HEADER OBRIGATÓRIO EM TODOS OS ARQUIVOS
POSIÇÕES
CAMPOS DE ATÉ FORMATO CONTEÚDO
A. 01 1 1 CHAR(1) Código do registro = A
A. 02 2 2 NUM(1) Código de Remessa
A. 03 3 22 CHAR(20) Código do Convênio
A. 04 23 42 CHAR(20) Nome da Empresa
A. 05 43 45 NUM(3) Código do Banco
A. 06 46 65 CHAR(20) Nome do Banco
A. 07 66 73 NUM(08) Data da geração do arquivo (AAAAMMDD)
A. 08 74 79 NUM(06) Número sequencial do arquivo (NSA)
A. 09 80 81 NUM(02 ) Versão do layout
A. 10 82 98 CHAR(17) Tipo de Movimento
A.11 99 150 CHAR(52) Reservado para o futuro (em branco)

DESCRIÇÃO DOS CAMPOS DO REGISTRO “A”

A.01 - Código do registro = “A”
A.02 - Código de Remessa

2 - RETORNO - Enviado pelo Banco para a Empresa/Órgão

A.03 - Código do Convênio

Definido pelo banco

A.04 - Nome da Empresa/Órgão
A.05 - Código do Banco

Código do Banco na câmara de compensação

A.06 - Nome do Banco
A.07 - Data da geração do arquivo (AAAAMMDD )
A.08 - Número seqüencial do arquivo ( NSA )

Este número deverá evoluir de 1 em 1 para cada arquivo gerado

A.09 - Versão do lay - out

legada = versão 03
atual = versão 04
nova = versão 05 - disponível a partir de 01.08.2016.

A.10 – Identificação do serviço

Deverá conter “CÓDIGO DE BARRAS”

A.11 – Reservado para o futuro (filler)


Distribuir Registro Código G

DESCRIÇÃO DO REGISTRO G - RETORNO DAS ARRECADAÇÕES IDENTIFICADAS COM CÓDIGO DE BARRAS
POSIÇÕES
CAMPOS DE ATÉ FORMATO CONTEÚDO
G.01 1 1 CHAR(1) Código do registro = G
G.02 2 21 CHAR(20) Identificação da agência/conta/dígito creditada
G.03 22 29 NUM(08) Data de pagamento (AAAAMMDD)
G.04 30 37 NUM(08) Data prevista para o crédito (AAAAMMDD)
G. 05 38 81 CHAR(44) Código de Barras
G.06 82 93 NUM(12,2) Valor recebido
G.07 94 100 NUM(7,2) Valor da tarifa
G.08 101 108 NUM(8) NSR - Número Sequencial de Registro
G.09 109 116 CHAR(8) Código da agência arrecadadora
G.10 117 117 CHAR(1) Forma de arrecadação/captura
G.11 118 140 CHAR(23) Número de autenticação caixa ou código de transação
G.12 141 141 NUM(1) Forma de Pagamento, se a forma de pagamento for nula alterar para valor 1
G.13 142 150 CHAR(9) Reservado para o futuro

DESCRIÇÃO DOS CAMPOS DO REGISTRO “G”

G.01 - Código do registro = “G”
G.02 - Identificação da empresa/órgão no banco/agência/conta/dígito creditada
G.03 - Data do pagamento no formato Ano/Mês /Dia
G.04 - Data do crédito no formato Ano/Mês/Dia
G.05 - Informações do Código de Barras
G.06 - Valor efetivamente recebido
G.07 - Valor da tarifa referente a cada comprovante arrecadado (será informado desde que acordado entre as partes)
G.08 - Uso do Banco - Identificação do registro dentro do arquivo gerado
G.09 – Código da agência arrecadadora
G.10 – Forma de arrecadação/captura (canais de recebimento)

1 – Guichê de Caixa com fatura/guia de arrecadação

2 – Arrecadação Eletrônica com fatura/guia de arrecadação (terminais de auto - atendimento,

ATM, home/office banking)

3 – Internet com fatura/guia de arrecadação

4 – Outros meios com fatura/guia de arrecadação

5 – Casas lotéricas/correspondentes bancários com fatura/guia de arrecadação

6 – Telefone com fatura/guia de arrecadação
a – Guichê de Caixa sem fatura/guia de arrecadação

b – Arrecadação Eletrônica sem fatura/guia de arrecadação (terminais de auto - atendimento, ATM, home/office banking)

c – Internet sem fatura/guia de arrecadação

d – Casas lotéricas/correspondentes bancários sem fatura/guia de arrecadação

e – Telefone sem fatura/guia de arrecadação

f – Outros meios sem fatura/guia de arrecadação

7 – Casas lotéricas com fatura/guia de arrecadação
8 - Cartão/Multibanco com fatura/guia de arrecadação
9 – PIX com fatura/guia de arrecadação

a – Guichê de Caixa sem fatura/guia de arrecadação
b – Arrecadação Eletrônica sem fatura/guia de arrecadação (terminais de auto - atendimento, ATM, home banking)
c – Internet/mobile sem fatura/guia de arrecadação
d – Correspondentes bancários sem fatura/guia de arrecadação
e – Telefone sem fatura/guia de arrecadação
f – Outros meios sem fatura/guia de arrecadação
g – Casas lotéricas sem fatura/guia de arrecadação
h – Cartão/Multibanco sem fatura/guia de arrecadação
i – PIX sem fatura/guia de arrecadação

G.11 – Número de autenticação caixa ou código de transação (será informado desde que acordado entre as partes).
G.12 – Forma de Pagamento

1 – Dinheiro

2 – Cheque

3 – Não identificado

G.13 – Reservado para o futuro


Distribuir Registro Código Z (TRAILLER)

Distribuir os campos do registro do arquivo de movimento de arrecadadores de acordo com o formato abaixo:

DESCRIÇÃO DO REGISTRO Z - TRAILLER OBRIGATÓRIO EM TODOS OS ARQUIVOS
POSIÇÕES
CAMPOS DE ATÉ FORMATO CONTEÚDO
Z. 01 1 1 CHAR(1) Código do Registro = Z
Z. 02 2 7 NUM(06) Total de registros do arquivo
Z. 03 8 24 NUM(17,2) Valor total recebido dos registros do arquivo
Z. 04 25 150 CHAR(126) Reservado para o futuro (brancos)


integracoes/api-pagamento.txt · Última modificação: 22/11/2023 13:20 por moises.simoes