Diretrizes de API para geração de tela de Checkout para liquidação direta

Esta documentação tem o intuito de descrever um padrão para a criação de uma API REST para o envio de débitos e o retorno de link com tela de checkout para o pagamento deste débito. 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 deve possuir recurso de segurança através de token.

Estrutura de Troca de Mensagens

Todas as requisições devem ser do tipo POST e terem a seguintes chaves: Authorization. No cabeçalho HTTP. O Gsan considerará todas as mensagens com HTTP Status Code 200 válidas. Qualquer fluxo de negócio diferente de sucesso devem ser encaminhadas com código 4XX ou 5XX.

Authorization: <HASH 256b>

ENDPOINT INSERIR DOCUMENTO PARA TELA CHECKOUT

JSON de consulta:

{ "id":"E#654213", "barcode":"826100000106207100410019005866570012702851114158", "identidade":"07391472425","nome":"Maria Alberta" }

Resposta:

{ "id":"E#654213", "url":"https:example.com/?sampleparameter=146b7fae-7dc4-4760-be6d-cb0512a4f97b" }

FLUXO DE ERRO PARA TODAS AS REQUISIÇÕES

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

Resposta:

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

Tabela de Erros:

Codigo	Erro
NÃO TRATADO
1	client_id obrigatório
2	client_secret obrigatório
3	EMPRESAO 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 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

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

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~~