Essa é uma revisão anterior do documento!
Tabela de conteúdos
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>
Fluxo de Negócio
|
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. |
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 |
|---|---|
| 0 | 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~~