Tabela de conteúdos
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. |
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
- POST (autenticar): HTTPS://ENDPOINTALVO:PORTA/gsan/api/pagamentos/extrato/debitos
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
- POST(autenticar): HTTPS://ENDPOINTALVO:PORTA/gsan/api/pagamentos/extrato/emitir
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
- POST(autenticar): HTTPS://ENDPOINTALVO:PORTA/gsan/api/pagamentos/extrato/desconto
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
POST: 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:
Codigo | Erro |
---|---|
0 | NÃO TRATADO |
1 | client_id obrigatório |
2 | client_secret obrigatório |
3 | EMPRESA NAO CADASTRADA |
4 | chave inválida |
100 | variável documento inexistente |
101 | variável debitos inexistente |
102 | variável debitos vazia |
103 | variável nsu ou identificacaoTransacao inexistente |
104 | cliente inexistente |
105 | documento inválido |
106 | documento obrigatório |
107 | documento cadastrado para vários clientes na base |
108 | identidicador do débito com formato inválido |
109 | invoice_number vazio |
110 | id do débito pago vazio |
111 | autenticacao do débito pago vazia |
112 | ID do débito inexistente na base |
113 | status inexistente |
114 | matricula inexistente |
115 | imóvel não cadastrado |
116 | extrato não permitido para imóvel |
117 | variável credenciada inexistente |
118 | matrícula obrigatória |
119 | matrícula inválida |
120 | pagamento inexistente |
121 | Este imóvel não tem perfil |
122 | Já 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) |
~~NOSIDEBAR~~