Interface com Automação Comercial · 02 05/12/2011 Marcelo D. Fonseca Definição arquivos...
Transcript of Interface com Automação Comercial · 02 05/12/2011 Marcelo D. Fonseca Definição arquivos...
Solução Completa de Pagamento Eletrônico Interface com Automação Comercial Por Troca de Arquivos Especificação Técnica Versão 01.00
Revisão: 03 Data: 02/01/2012 Responsável: Marcelo D. Fonseca
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 2
Informações Gerais
Leia antes de iniciar o desenvolvimento:
É imprescindível a leitura deste material para o entendimento do fluxo das transações e processos
envolvidos na troca de arquivos entre o SCOPE e Automação Comercial.
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 3
Revisão Data Responsável Histórico
00 24/11/2011 Marcelo D. Fonseca Versão Preliminar
01 02/12/2011 Marcelo D. Fonseca Revisão segundo necessidades da Eletropaulo e melhorias gerais
02 05/12/2011 Marcelo D. Fonseca Definição arquivos Estorno e melhorias gerais
03 02/01/2012 Marcelo D. Fonseca Formalização número seqüencial de 3 dígitos. Descrição do FAPI.
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 4
Índice ________________________________________________________________________________________________
Prefácio...............................................................................................................................5 A quem se destina.......................................................................................................................................... 5 Descrição do Produto ..................................................................................................................................... 5
Objetivo ....................................................................................................................................................... 5 Definição ..................................................................................................................................................... 5 Benefícios.................................................................................................................................................... 5 Maiores Informações................................................................................................................................... 5
Referências .................................................................................................................................................... 6
Regras Gerais ....................................................................................................................7 Organização dos Diretórios............................................................................................................................ 7 Nomenclatura dos Arquivos ........................................................................................................................... 7 Fluxo da Troca de Arquivos ........................................................................................................................... 8 Visão Geral ..................................................................................................................................................... 9 Fluxos de Mensagens de uma TEF ............................................................................................................. 10 Estrutura dos Arquivos ................................................................................................................................. 11 Padrões adotados neste documento............................................................................................................ 12
Legenda de Abreviações .......................................................................................................................... 12 Campos Previstos ........................................................................................................................................ 12
Composição dos Arquivos .............................................................................................14 Solicitação de TEF ....................................................................................................................................... 14 Resposta da TEF.......................................................................................................................................... 14 Confirmar ou Desfazer TEF ......................................................................................................................... 15 Estorno de TEF ............................................................................................................................................ 16 Solicitação de Estorno.................................................................................................................................. 16 Resposta do Estorno .................................................................................................................................... 16 Confirmar ou Desfazer Estorno.................................................................................................................... 17
FAPI...................................................................................................................................18 Instalação ..................................................................................................................................................... 18 Configuração ................................................................................................................................................ 18 Execução...................................................................................................................................................... 18 Operação...................................................................................................................................................... 19
Apêndice A – Exemplos de Arquivos.............................................................................20
Apêndice B – Códigos de Resposta das Redes............................................................23
Apêndice C – Códigos de Resposta do SCOPE............................................................25
Apêndice D – Glossário...................................................................................................29
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 5
Prefácio _____________________________________________________________________________________________________
A quem se destina Este documento se destina aos clientes ou parceiros da Itautec que desejam integrar seu sistema
de Automação Comercial com o SCOPE através da interface de Troca de Arquivos.
Existem situações no mercado em que a integração de um sistema de Automação Comercial
através de chamadas de funções do SCOPE Client é inviável.
Para estas situações o SCOPE pretende oferecer a alternativa de integração através de troca de
arquivos.
Descrição do Produto
Objetivo
O sistema SCOPE – Solução Completa para Pagamento Eletrônico – permite ao software de
PDV (Automação Comercial) efetuar o pagamento através de TEF, por exemplo, cartões de
crédito e débito, através da digitação do emboço ou leitura da tarja magnética ou chip.
Definição
O SCOPE foi concebido para gerenciar todas as etapas de uma TEF abstraindo a complexidade
inerente à transação do aplicativo PDV.
Benefícios
• O sistema permite uma arquitetura flexível, multiempresa, multifilial, centralizada ou
distribuída, adequando-se à necessidade do cliente.
• Facilita a gestão do negócio, pois oferece ferramentas de consulta e relatórios
operacionais e gerenciais.
• Permite a gestão da sessão contábil, pelo estabelecimento ou pelo centro de
processamento, de forma a indicar eventuais divergências nos créditos efetuados pelos
bancos.
• Permite mecanismos de alta-disponibilidade através de solução cluster e rotas de
contingência.
Maiores Informações
Podem ser obtidas através dos documentos do produto SCOPE, conforme relação descrita nas
Referências abaixo. Você pode solicitá-los ao seu representante comercial Itautec.
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 6
Referências International Standard Financial Transaction Card Originated Messages
ISO–8583
Interchange Message Specification
2nd Edition – 15/12/2003
American National Standard for Financial Services
X9.8–2003
BANKING - PERSONAL IDENTIFICATION NUMBER MANAGEMENT AND SECURITY
Part 1: PIN protection principles and techniques for online PIN verification in ATM & POS systems
Documentos SCOPE
• SCOPE – Manual Desenvolvedor
• SCOPE – Manual de Instalação e Configuração
• SCOPE – Manual de Administração
• SCOPE – Guia de Codificação Segura
• SCOPE – Guia de Implementação PA-DSS
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 7
Regras Gerais _____________________________________________________________________________________________________
Toda interação entre Automação Comercial e SCOPE é feita através de Troca de Arquivos.
Abaixo estão descritas as regras de organização, nomenclatura, manipulação e estrutura destes
arquivos.
Organização dos Diretórios Devem existir dois diretórios configuráveis, um de entrada e outro de saída, usando o SCOPE
como referência. Por exemplo:
Diretório Caminho Entrada C:\SCOPE\IN Saída C:\SCOPE\OUT
A Automação Comercial (AC) deve sempre gravar no diretório de Entrada do SCOPE.
O SCOPE deve sempre gravar no diretório de Saída.
Para evitar conflitos, as gravações dos arquivos devem necessariamente seguir os passos abaixo:
• Criar o arquivo com nome temporário;
• Gravar os dados do arquivo;
• Forçar a gravação imediata através de comando do tipo flush.
• Fechar o arquivo;
• Renomear o arquivo para o nome definitivo.
Estas regras devem ser seguidas tanto pela AC quanto pelo SCOPE.
Após leitura com sucesso do arquivo, o mesmo deve ser eliminado do diretório. Portanto, a
responsabilidade de eliminar os arquivos do diretório de Entrada é do SCOPE. Analogamente, a
responsabilidade por eliminar os arquivos do diretório de Saída é da AC.
Nomenclatura dos Arquivos Os arquivos trocados entre AC e SCOPE devem seguir as seguintes regras de nomenclatura:
Arquivo Diretório Criado por Nome Temporário Nome Definitivo Eliminado por Solicitação Entrada AC REQT<nnnn>.tmp REQT<nnnn>.sc_ SCOPE Resposta Saída SCOPE RESP<nnnn>.tmp RESP<nnnn>.ac_ AC Confirmação/Desfazimento
Entrada AC COMP<nnnn>.tmp COMP<nnnn>.sc_ SCOPE
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 8
Sendo que <nnnn> representa um número seqüencial (entre 0001 e 9999) que deve ser mantido
constante ao longo do ciclo de vida da transação, ou seja, deve ser o mesmo nos três arquivos.
Embora não haja tratamento de transações simultâneas, este número seqüencial é uma garantia
de que os três arquivos referem-se a uma mesma transação.
Este número é controlado pela AC e pode ser reiniciado diariamente ou não, a critério da AC.
Fluxo da Troca de Arquivos A figura abaixo representa o fluxo da troca de arquivos entre AC e SCOPE:
Considerando <nnnn> como 0001, o ciclo de vida de uma transação aprovada representado pelo
diagrama acima seria:
1. AC grava arquivo REQT0001.sc_ com solicitação da TEF no diretório de entrada;
2. SCOPE lê arquivo REQT0001.sc_ e efetua a TEF;
3. SCOPE grava arquivo RESP0001.ac_ com resposta da TEF no diretório de saída;
4. AC lê arquivo RESP0001.ac_ e imprime comprovante de TEF;
5. AC grava arquivo COMP0001.sc_ confirmando (ou desfazendo em caso de erro no
tratamento da resposta) a TEF;
6. SCOPE lê arquivo COMP0001.sc_ e envia confirmação (ou desfazimento) da TEF;
O arquivo de resposta sempre é gerado pelo SCOPE, mesmo em casos de erro, como nos
exemplos abaixo:
• A transação foi negada pela rede autorizadora;
• O SCOPE não recebeu resposta da rede (timeout);
• A transação foi abortada pelo operador;
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 9
• Os dados recebidos são inválidos ou insuficientes;
• Ocorreu um erro interno inesperado;
Visão Geral No diagrama abaixo está representada uma visão geral do processo:
Descrição do Diagrama:
A troca de arquivos ocorre no PDV, onde estão sendo executados:
• Automação Comercial;
• Módulo SCOPE gerenciador da interface de Troca de Arquivos, integrado ao SCOPE
Client;
O SCOPE Client interage com o SCOPE Server para consultar a configuração e solicitar a TEF;
O SCOPE Server é responsável por interagir com os PDVs, armazenar as transações em Banco de
Dados e interagir com o SCOPE Gateway (que pode estar instalado na mesma máquina do SCOPE
Server);
O SCOPE Gateway gerencia as conexões com as redes autorizadoras, geralmente através de X.25,
repassando as solicitações do SCOPE Server para as redes e as respostas das redes
autorizadoras ao SCOPE Server.
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 10
Fluxos de Mensagens de uma TEF Para facilitar o entendimento de todo o processo envolvido na TEF, abaixo está descrito como
funciona a troca de mensagens entre o SCOPE e a rede autorizadora:
Transação Aprovada e Confirmada
Considerando um fluxo básico de sucesso, temos:
O arquivo de solicitação é interpretado pelo SCOPE e uma perna ISO8583 cujo código de
mensagem é 0200 (primeira perna) é enviada à rede autorizadora. Esta por sua vez responde à
solicitação com uma mensagem 0210 (segunda perna) aprovando ou negando a TEF. Caso a
transação tenha sido aprovada, o SCOPE precisa enviar uma 0202 (terceira perna) para informar
à rede que a transação deve ser confirmada. Para algumas redes, a 0202 é enviada também para
transações negadas.
Desfazimento
Em caso de timeout (a 0210 não chegou ao SCOPE em tempo hábil) ou falha na AC no
tratamento da resposta, a perna de confirmação é substituída por uma perna de solicitação de
desfazimento:
O desfazimento pode ocorrer um duas situações:
SSCCOOPPEE AAuuttoorriizzaaddoorr
00221100
00442200
00220000
00443300
SSCCOOPPEE AAuuttoorriizzaaddoorr
00221100
00220022
00220000
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 11
• A resposta 0210 foi recebida e a transação foi aprovada, porém a AC sinalizou falha na
impressão do comprovante e/ou tratamento da resposta. Neste caso o envio da 0420
depende da geração do arquivo COMP<nnnn>.sc_, que é de responsabilidade da AC.
Caso não gerado, a transação ficará pendente.
• A resposta 0210 não foi recebida, ou seja, ocorreu timeout. Neste caso a 0420 é enviada
automaticamente pelo SCOPE e um arquivo RESP<nnnn>.ac_ é gerado para informar
erro à AC. Neste caso não é necessário gerar o arquivo COMP<nnnn>.sc_.
Outro ponto importante a ser comentado é que a 0430 não é imprescindível, pois a transação já é
considerada desfeita no SCOPE. Podem existir situações em que a rede não está recebendo
nenhuma perna, por exemplo, quando há problemas no provedor X.25. Neste caso o motivo do
timeout pode ser o não recebimento da perna 0200 pela rede e, portanto, provavelmente a
mesma não irá receber a 0420 nem responder com 0430.
Estrutura dos Arquivos Todos os arquivos trocados terão do tipo texto, múltiplas linhas, cada linha finalizada com CRLF
(carriage return e line feed), ou seja, 0x0D e 0x0A.
A estrutura interna dos arquivos segue o seguinte formato:
CCC . NNN : DDD..D CRLF
Sendo:
Campo Tamanho Descrição CCC 3 Código do campo
. 1 Caractere ‘.’ (ponto) NNN 3 Número seqüencial da linha do campo.
000 - Se campo de linha única; 001 até nnn - Se campo de várias linhas
: 1 Caractere ‘:’ (dois pontos) DDD..D variável Dados do campo CRLF 2 carriage return e line feed (0x0D e 0x0A)
Obrigatoriamente todos os arquivos deverão conter pelo menos 3 linhas, sendo:
Header Ação
Linhas de Dados (se existir) Finalizador
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 12
Padrões adotados neste documento
Legenda de Abreviações
Formato Atributo
a Caracteres alfabéticos. n Caracteres numéricos.
an Caracteres alfabéticos e numéricos. ans Caracteres alfabéticos, numéricos e especiais. MM Mês. DD Dia. AA Ano. hh Hora. mm Minuto. ss Segundo.
LLvar Tamanho de um campo variável. Ex. Se o conteúdo do campo = “AB1234CD”, teremos para representá-lo: “08 AB1234CD” .
LLLvar Tamanho de um campo variável. Ex. Se o conteúdo do campo = “AB1234CD”, teremos para representá-lo: “008 AB1234CD” .
10 Tamanho fixo de 10 caracteres. ..10 Tamanho variável de até 10 caracteres. b Representação binária dos dados.
Campos Previstos Abaixo a relação de campos previstos:
Campo Tamanho Descrição Formato 000 an3 Header SCOPEvvv, Sendo:
vvv = versão, atualmente fixo em 001 001 a3 Ação CCC, Sendo:
TEF – Solicitar TEF; CNF – Confirmar TEF; DSF – Desfazer TEF; CAN – Cancelar TEF; IMP – Imprimir Cupom; EXB – Exibir Negada; ERR – Tratar Erro;
002 n3 Código do Grupo de Serviço
GGG, Sendo: 001 – Débito; 002 – Crédito;
003 n3 Código do Serviço SSS, Sendo: 006 – Débito à vista; 009 – Crédito à vista; 027 – Crédito parcelado Adm; 028 – Crédito parcelado Loja; 031 – Estorno Débito; 032 – Estorno Crédito; 050 – Débito Voucher; 051 – Estorno Voucher;
004 n12 Valor da Venda 999999999999 em centavos de Real, por exemplo: 000000001050 significa R$10,50.
005 n12 Taxa de Serviço 999999999999 006 n12 Taxa de Embarque 999999999999 007 n12 Valor do Saque 999999999999
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 13
008 n3 Qtd de Parcelas 999 009 an8 Identificação da AC XXXXXXXX 010 an8 Versão do Software da
AC XXXXXXXX
011 n5 Código de Resposta do SCOPE
012 an3 Código de Resposta da Rede
013 ans40 Mensagem Final 014 n12 Valor Total Final 999999999999 015 n3 Código da Rede 016 ans40 Nome da Rede 017 n3 Código da Bandeira 018 ans40 Nome da Bandeira 019 ans22 Número do Cartão
Mascarado
020 n4 Validade do Cartão AAMM 021 ans40 Nome do Cliente 022 n8 Data da Transação DDMMAAAA 023 n6 Hora da Transação hhmmss 024 n6 NSU NNNNNN 025 ans12 NSU Host NNNNNNNNNNNN 026 n6 Código da Autorização NNNNNN 027 n11 Controle NNNNNNNNNNN 028 an15 Código do
Estabelecimento
029 n4 Código da Empresa EEEE 030 n4 Código da Filial FFFF 031 n3 Código do PDV PPP 032 n4 Tamanho Total do
Cupom via Estabelecimento
LLLL
033 LLvar Cupom via Estabelecimento
Linha do Cupom via Estabelecimento
034 n4 Tamanho Total do Cupom via Cliente
LLLL
035 LLvar Cupom via Cliente Linha do Cupom via Cliente 036 n4 Tamanho Total do
Cupom via Reduzida LLLL
037 LLvar Cupom via Reduzida Linha do Cupom via Reduzida 038 LLLvar Atributo da Aplicação LLLDDD...D Sendo:
LLL tamanho dos dados a seguir; DDD...D dados
039 LLvar Identificador da venda Campo identificador da venda ou pedido gerado pela AC e fornecido no arquivo de solicitação a ser ecoado no arquivo de resposta
999 a3 Finalizador FIM
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 14
Composição dos Arquivos _____________________________________________________________________________________________________
Nesta sessão estão descritos os campos por arquivo, mandatórios, opcionais, ecoados ou
condicionais, sendo:
• M = Mandatório;
• O = Opcional;
• E = Ecoado;
• C1 = Condicional, se aprovada;
• C2 = Condicional, se negada;
• C3 = Condicional, se aprovada ou negada;
• C4 = Condicional, se existir;
• C5 = Condicional, se aprovada e se existir.
Solicitação de TEF
Campo Presença Descrição Conteúdo 000 M Header SCOPE001 001 M Ação TEF 002 M Código do Grupo de
Serviço 001 – Débito; 002 – Crédito;
003 O Código do Serviço Opcional. Se não fornecido e configuração permitir a decisão será do operador.
004 M Valor da Venda 999999999999 005 O Taxa de Serviço 999999999999 006 O Taxa de Embarque 999999999999 007 O Valor do Saque 999999999999 008 O Qtd de Parcelas 999 009 M Identificação da AC XXXXXXXX 010 M Versão do Software da
AC XXXXXXXX
038 O Atributo da Aplicação LLLD...D 039 O Identificador da venda LLD...D 999 M Finalizador FIM
Resposta da TEF Campo Presença Descrição Conteúdo
000 M Header SCOPE001 001 M Ação IMP – Imprimir Cupom;
EXB – Exibir Negada; ERR – Tratar Erro.
002 E Código do Grupo de Serviço
001 – Débito; 002 – Crédito;
003 M Código do Serviço 006 – Débito à vista; 009 – Crédito à vista; 027 – Crédito parcelado Adm; 028 – Crédito parcelado Loja;
004 E Valor da Venda 999999999999 005 O Taxa de Serviço 999999999999
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 15
006 O Taxa de Embarque 999999999999 007 O Valor do Saque 999999999999 008 O Qtd de Parcelas 999 011 M Código de Resposta do
SCOPE
012 M Código de Resposta da Rede
013 M Mensagem Final 014 M Valor Total Final 015 M Código da Rede 016 M Nome da Rede 017 M Código da Bandeira 018 M Nome da Bandeira 019 O Número do Cartão
Mascarado
020 O Validade do Cartão AAMM 021 O Nome do Cliente 022 C3 Data da Transação DDMMAAAA 023 C3 Hora da Transação hhmmss 024 C1 NSU NNNNNN 025 C4 NSU Host NNNNNNNNNNNN 026 C4 Código da Autorização NNNNNN 027 C1 Controle NNNNNNNNNNN 028 C3 Código do
Estabelecimento
029 O Código da Empresa EEEE 030 O Código da Filial FFFF 031 O Código do PDV PPP 032 C1 Tamanho Total do
Cupom via Estabelecimento
LLLL
033 C1 Cupom via Estabelecimento
Linha do Cupom via Estabelecimento
034 C1 Tamanho Total do Cupom via Cliente
LLLL
035 C1 Cupom via Cliente Linha do Cupom via Cliente 036 C5 Tamanho Total do
Cupom via Reduzida LLLL
037 C5 Cupom via Reduzida Linha do Cupom via Reduzida 039 E Identificador da venda LLD...D 999 M Finalizador FIM
Confirmar ou Desfazer TEF Somente se recebido o arquivo de resposta com ação IMP.
Campo Presença Descrição Conteúdo 000 M Header SCOPE001 001 M Ação CNF – Confirmar;
DSF – Desfazer. 015 E Código da Rede 017 E Código da Bandeira 022 E Data da Transação DDMMAAAA 023 E Hora da Transação hhmmss 024 E NSU NNNNNN 028 E Código do
Estabelecimento
039 E Identificador da venda LLD...D 999 M Finalizador FIM
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 16
Estorno de TEF Abaixo estão descritos os arquivos envolvidos em um Estorno (Cancelamento) de TEF.
Solicitação de Estorno
Campo Presença Descrição Conteúdo 000 M Header SCOPE001 001 M Ação CAN 004 M Valor 999999999999 009 M Identificação da AC XXXXXXXX 010 M Versão do Software da
AC XXXXXXXX
027 M Controle NNNNNNNNNNN Identifica a transação a ser cancelada
999 M Finalizador FIM
Resposta do Estorno Campo Presença Descrição Conteúdo
000 M Header SCOPE001 001 M Ação IMP – Imprimir Cupom;
EXB – Exibir Negada; ERR – Tratar Erro.
002 M Código do Grupo de Serviço
Código do Grupo de Serviço da transação original
003 M Código do Serviço Código do Serviço da transação original 004 M Valor 999999999999 011 M Código de Resposta do
SCOPE
012 M Código de Resposta da Rede
013 M Mensagem Final 015 M Código da Rede 016 M Nome da Rede 017 M Código da Bandeira 018 M Nome da Bandeira 022 C3 Data da Transação DDMMAAAA 023 C3 Hora da Transação hhmmss 024 C1 NSU NNNNNN 025 C4 NSU Host NNNNNNNNNNNN 026 C4 Código da Autorização NNNNNN 028 C3 Código do
Estabelecimento
032 C1 Tamanho Total do Cupom via Estabelecimento
LLLL
033 C1 Cupom via Estabelecimento
Linha do Cupom via Estabelecimento
034 C1 Tamanho Total do Cupom via Cliente
LLLL
035 C1 Cupom via Cliente Linha do Cupom via Cliente 999 M Finalizador FIM
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 17
Confirmar ou Desfazer Estorno Somente se recebido o arquivo de resposta com ação IMP.
Campo Presença Descrição Conteúdo 000 M Header SCOPE001 001 M Ação CNF – Confirmar;
DSF – Desfazer. 015 E Código da Rede 017 E Código da Bandeira 022 E Data da Transação DDMMAAAA 023 E Hora da Transação hhmmss 024 E NSU NNNNNN 028 E Código do
Estabelecimento
999 M Finalizador FIM
IMPORTANTE: Algumas redes autorizadoras não permitem o desfazimento do estorno.
Portanto, o recomendável é que a AC sempre solicite a confirmação do mesmo.
Caso a AC solicite o desfazimento de um estorno para uma rede que não possua este
recurso, pode ser necessário um ajuste na conciliação.
Além disso, as regras de quanto tempo um estorno pode ser executado varia de rede para
rede. Normalmente o estorno somente é possível no dia em que a transação foi realizada.
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 18
FAPI _____________________________________________________________________________________________________
Nesta sessão estão descritas as regras de instalação e configuração do módulo
FAPI – File Application Programming Interface.
Instalação A instalação é feita através de cópia simples dos arquivos abaixo para o mesmo diretório onde
está instalado o SCOPE Client, em ambiente Windows 32 bits.
• FAPI.EXE
• FAPI.INI
Configuração A configuração é feita através do arquivo FAPI.INI, conforme exemplo abaixo:
[FAPI]
ArquivoCaminhoEntrada=C:\SCOPE\IN
ArquivoCaminhoSaida=C:\SCOPE\OUT
ScopeEmpresa=0001
ScopeFilial=0001
ScopePdv=001
LogoCliente=c:\meulogo.wmf
Sendo:
ArquivoCaminhoEntrada Caminho completo do diretório de entrada ArquivoCaminhoSaida Caminho completo do diretório de saída ScopeEmpresa Código da Empresa deste PDV (4 dígitos) ScopeFilial Código da Filial deste PDV (4 dígitos) ScopePdv Código deste PDV (3 dígitos) LogoCliente Logotipo do cliente (opcional)
Formato bmp, gif, jpg, wmf, emf ou ico
Execução Para realizar uma TEF, o sistema SCOPE deve estar em execução no servidor, com as devidas
redes configuradas e em operação.
No PDV, o módulo FAPI.EXE também deve estar em execução. Este módulo, enquanto está a
espera por arquivos, não apresenta nenhuma tela. Pode-se perceber que o mesmo está em
execução devido ao ícone na barra de tarefas, no canto inferior direito da tela, como mostrado
no exemplo abaixo:
Este módulo não é finalizado a cada TEF. O mesmo permanece sempre em operação a espera
pelo próximo arquivo.
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 19
Se necessário, o FAPI pode ser finalizado clicando-se neste ícone com o botão direito do mouse e
selecionando-se Sair.
Operação Quando o FAPI percebe que um arquivo de solicitação foi gravado no diretório de entrada, a tela
abaixo é apresentada para permitir a coleta das informações necessárias para a execução da
TEF:
O operador do PDV deve então realizar o passo-a-passo do fluxo de coleta da TEF até a
conclusão da mesma.
No passo mostrado acima, o SCOPE está solicitado a leitura do cartão, que pode ser digitado, por
tarja magnética ou chip. Nos dois últimos casos é necessário que esteja conectado e configurado
um PINPad compatível.
NOTA: Durante a execução da TEF recomenda-se que a Automação Comercial garanta
que não seja possível iniciar nova TEF até que a que está em execução seja finalizada.
Caso necessário, a Automação Comercial poderá apresentar informações complementares
em outra tela, como por exemplo, valor total dos produtos, valor da TEF que está em
andamento, etc.
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 20
Apêndice A – Exemplos de Arquivos _____________________________________________________________________________________________________
Os arquivos abaixo devem ser usados apenas como exemplos de formato. As transações representadas
pelos mesmos foram realizadas através do ScopeAUT e portanto são simuladas. Alguns campos,
principalmente os cupons, podem possuir diferenças de formatação do conteúdo. Não é recomendada a
extração de conteúdo diretamente dos cupons formatados, já que os mesmos podem ter sido montados
diretamente pela Rede Autorizadora e, portanto, seu conteúdo pode sofrer alterações sem aviso prévio.
Exemplo de um arquivo de solicitação de TEF de crédito de R$1,00 deixando-se a seleção do serviço
a cargo do Operador de TEF:
000.000:SCOPE001
001.000:TEF
002.000:002
004.000:000000000100
009.000:AC001
010.000:1.0
999.000:FIM
Exemplo de um arquivo de solicitação de TEF de crédito parcelado loja de R$100,00 em 3 parcelas:
000.000:SCOPE001
001.000:TEF
002.000:002
003.000:028
004.000:000000010000
008.000:3
009.000:AC001
010.000:1.0
999.000:FIM
Exemplo de um arquivo de solicitação de TEF de crédito à vista de R$32,53:
000.000:SCOPE001
001.000:TEF
002.000:002
003.000:009
004.000:000000003253
009.000:AC001
010.000:1.0
999.000:FIM
Exemplo de um arquivo de solicitação de TEF de débito à vista de R$20,00:
000.000:SCOPE001
001.000:TEF
002.000:001
003.000:006
004.000:000000002000
009.000:AC001
010.000:1.0
999.000:FIM
Exemplo de um arquivo de resposta:
000.000:SCOPE001
001.000:IMP
002.000:002
003.000:009
004.000:000000005000
011.000:00000
012.000:000
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 21
013.001:AUTORIZADO
013.002:Controle 01200181000
014.000:000000005000
015.000:103
016.000:REDECARD-L0500
017.000:002
018.000:MASTERCARD
019.000:548826XXXXXX0000
020.000:0316
022.000:0102
023.000:145459
024.000:001081
025.000:SIMULADOR
026.000:001081
027.000:01200181000
028.000:000100010000103
029.000:0001
030.000:0001
031.000:001
032.000:680
033.001:38 REDECARD
033.002:00
033.003:38 MASTERCARD
033.004:00
033.005:00
033.006:38COMPR:123456789 VALOR: 9.999,99
033.007:00
033.008:38ESTAB:013932594 SCOPE TESTE SIMULADO
033.009:38DD.MM.AA-HH:MM:SS TERM:PV123456/pppnnn
033.010:24CARTAO: 548826XXXXXX0000
033.011:38AUTORIZACAO: 123456
033.012:38 RECONHECO E PAGAREI A DIVIDA
033.013:38 AQUI REPRESENTADA
033.014:00
033.015:38**************************************
033.016:38 D E M O N S T R A C A O
033.017:38 Transacao sem validade para reembolso
033.018:38 Autorizacao gerada por simulador
033.019:38**************************************
033.020:00
033.021:38 ____________________________
033.022:38
033.023:00
033.024:00
033.025:00
033.026:00
033.027:00
033.028:15AAAAA 111 AAAAA
033.029:15BBBBB 222 BBBBB
033.030:00
033.031:38CONTROLE 01200181000 ITAUTEC SCOPE
034.000:680
035.001:38 REDECARD
035.002:00
035.003:38 MASTERCARD
035.004:00
035.005:00
035.006:38COMPR:123456789 VALOR: 9.999,99
035.007:00
035.008:38ESTAB:013932594 SCOPE TESTE SIMULADO
035.009:38DD.MM.AA-HH:MM:SS TERM:PV123456/pppnnn
035.010:24CARTAO: 548826XXXXXX0000
035.011:38AUTORIZACAO: 123456
035.012:38 RECONHECO E PAGAREI A DIVIDA
035.013:38 AQUI REPRESENTADA
035.014:00
035.015:38**************************************
035.016:38 D E M O N S T R A C A O
035.017:38 Transacao sem validade para reembolso
035.018:38 Autorizacao gerada por simulador
035.019:38**************************************
035.020:00
035.021:38 ____________________________
035.022:38
035.023:00
035.024:00
035.025:00
035.026:00
035.027:00
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 22
035.028:15AAAAA 111 AAAAA
035.029:15BBBBB 222 BBBBB
035.030:00
035.031:38CONTROLE 01200181000 ITAUTEC SCOPE
036.000:171
037.001:38MASTERCARD 548826XXXXXX0000 03/16
037.002:35AUT:001081 NSU:001081 DOC:SIMULADOR
037.003:22VENDA CREDITO A VISTA
037.004:38VALOR: 50,00 CTR:01200181000
037.005:00
037.006:15AAAAA 111 AAAAA
999.000:FIM
Exemplo de um arquivo de confirmação:
000.000:SCOPE001
001.000:CNF
015.000:103
017.000:002
022.000:0102
023.000:145459
024.000:001081
028.000:000100010000103
999.000:FIM
Exemplo de um arquivo de desfazimento:
000.000:SCOPE001
001.000:DSF
015.000:103
017.000:002
022.000:0102
023.000:145459
024.000:001081
028.000:000100010000103
999.000:FIM
Exemplo de um arquivo de solicitação de estorno:
000.000:SCOPE001
001.000:CAN
004.000:000000005000
009.000:AC001
010.000:1.0
027.000:01200181000
999.000:FIM
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 23
Apêndice B – Códigos de Resposta das Redes _____________________________________________________________________________________________________
Os códigos de resposta abaixo são exemplos de conteúdo do campo 012 – Código de Resposta da Rede.
A AC deve sempre verificar o conteúdo deste campo no arquivo de resposta. Se ‘000’ a transação foi
aprovada. Se diferente de ‘000’ a transação foi negada.
Os códigos de resposta de transações negadas variam de rede para rede. O quadro abaixo deve ser
utilizado apenas como uma referência básica, pois não há garantias de que todas as redes seguem este
padrão.
Para saber exatamente o significado de um código, entre em contato com a rede para a qual a transação foi
enviada (Redecard, Cielo, Amex, etc).
Código Resposta
Descrição
000 Aprovada, transação executada.
003 Estabelecimento comercial inválido
006 Erro no processamento
009
Transação em andamento (somente para transação de consulta de status de transação).
012 Transação inválida
013 Valor da transação inválido
014 Cartão inválido
015 Instituição não cadastrada
019 Refaça a transação
030 Erro de formato
031 Instituição não pertence à rede
038 Excedido número de tentativas do PIN
041 Cartão extraviado
043 Cartão roubado
051 Saldo insuficiente
055 Senha incorreta
057 Transação não permitida a esse cliente
060 Entrar em contato com a instituição
061 Excedido limite de saque
065 Excedido frequência de saque
076 Cartão bloqueado
077 Pendente de confirmação
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 24
078 Transação cancelada
080 Transação não existe
083 Time-out
084 Log-on (terminal não aberto)
085 Problema rede local
086 Transação desfeita
091 Instituição temporariamente fora de operação
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 25
Apêndice C – Códigos de Resposta do SCOPE _____________________________________________________________________________________________________
Os códigos de resposta abaixo são exemplos de conteúdo do campo 011 – Código de Resposta do
SCOPE. A maioria destes erros nunca deve ocorrer, pois são situações tratadas pelo módulo gerenciador
de arquivos, já que é este módulo que está integrado ao SCOPE Client.
Porém, alguns destes erros podem ocorrer no dia-a-dia e não necessariamente representam um problema.
Exemplos:
• 65280 – Indica que o servidor SCOPE não está disponível. Pode ser problema de configuração (IP)
ou falha de conexão (rede);
• 65281 – Instituição offline. A rede autorizadora está fora-do-ar no momento. Pode ser um problema
temporário do autorizador e o restabelecimento será automático quanto o mesmo retornar a operar.
Pode ser também uma falha no provedor X.25.
• 65283 – Serviço ou BIN não configurado. O SCOPE não encontrou nenhum serviço e/ou nenhuma
rede para rotear esse cartão. Por exemplo, ocorre quando se tenta pagar com um cartão de
bandeira que não está sendo contemplada por nenhuma rede com as quais o estabelecimento
possui contratos.
IMPORTANTE: Como o presente documento possui uma versão de especificação
independente da versão do SCOPE, a tabela abaixo pode estar desatualizada. A mesma
está sendo fornecida neste documento como um facilitador de entendimento, porém
recomenda-se usar a tabela presente no documento “SCOPE - Manual Desenvolvedor”
como referência atualizada.
Código Resposta
Significado
65024 A transação em andamento – a aplicação deve aguardar 65025 SCOPE API não foi inicializada corretamente 65026 SCOPE API já foi inicializada corretamente 65027 Existe transação suspensa 65028 Não existe transação suspensa 65029 API ainda não fez nenhuma transação após a inicialização. A
aplicação está tentando obter um handle sem ter feito nenhuma transação desde última conexão com o ScopeSRV
65030 Logon duplicado 65031 Protocolo não suportado – SCOPE Client com versão de protocolo
superior ao SCOPE Server 65032 POS não cadastrado 65033 Servidor não configurado no arquivo scope.ini 65034 Não há mais PDV’s disponíveis. Erro retornado quando a aplicação
passa o caractere “#” como PDV para que o SCOPE Server lhe dê um número de PDV válido, mas não há mais PDV’s disponíveis
65035 Protocolo incompatível – SCOPE Client com versão de protocolo extremamente antigo (P00, P01 ou P02).
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 26
Código Resposta
Significado
65036 Não pode mais desfazer uma transação que já iniciou o ciclo de finalização – situação que pode ocorrer apos queda de energia ou na inicialização da aplicação.
65037 Não há arquivo com dados da transação anterior salvo 65280 ScopeSrv off-line ou o IP configurado no arquivo scope.ini está
apontando para a máquina errada 65281 Instituição off-line 65282 Transação cancelada pelo operador ou no caso de um estorno via
REDECARD: estorno fora do prazo permitido, validade não confere. 65283 Serviço ou BIN não configurado 65284 Transação já foi cancelada 65285 Transação não encontrada 65286 Transação não permite cancelamento 65287 Dados informados não conferem com a transação original 65288 Erro no acesso ao banco de dados 65289 Time-out no acesso ao banco de dados 65290 Banco de dados off-line 65291 Transação abortada pelo aplicativo 65292 Transação não implementada 65293 Handle inválido (ver Obtendo handle) 65294 Taxa de serviço é inválida 65295 Taxa de serviço excede limite 65296 Dado inválido 65297 Não existe cupom válido 65298 Área reservada para o buffer é insuficiente para o SCOPE Client
preencher com os dados solicitados 65299 Limite inválido – inferior ao permitido 65300 Transação desfeita 65301 Digitação não permitida 65302 Memória insuficiente 65303 “Service Code” inválido 65304 Data inválida 65305 Cartão vencido 65306 Cartão inválido 65307 Desfazimento não disponível 65308 Erro na impressão do cupom 65309 Sessão em andamento – a transação solicitada deve ser única numa
sessão de TEF, ou seja, não pode ser chamada se há transações na sessão de TEF atual
65310 Transação já efetuada 65311 Inserir chip do cartão 65312 Controle obrigatório 65313 Pré-autorização obrigatória 65314 Serviço não configurado 65315 Serviço não definido 65316 Número de parcelas inválidas 65317 Valor inválido 65318 Serviço ou BIN não configurado para Visanet 65319 Estado de coleta não definido 65320 Operação não permitida 65321 CNPJ/CPF inválido 65322 Primeiro bloco do código de barras está inválido 65323 Segundo bloco do código de barras está inválido 65324 Terceiro bloco do código de barras está inválido 65325 Quarto bloco do código de barras está inválido 65326 Dados adicionais AID do chip do cartão inexistente 65328 Autorizador retornou dados inválidos 65329 Conta não permitida
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 27
Código Resposta
Significado
65330 Conta vencida 65331 Não existe resumo 65332 Código de barra inválido 65333 Erro na consistência do DAC 65334 Erro no envio da confirmação ou desfazimento da transação anterior 65335 Serviço invertido – a aplicação está tentando fazer uma transação de
débito com um cartão de crédito ou vice-versa 65336 Cartão não permitido 65337 Permitido somente a coleta do CPF – consulta de cheque 65338 Erro interno na execução da coleta 65339 Lista (de produtos, de medicamentos, etc.) não está disponível. 65340 Erro de leitura do cartão 65341 Controle inválido 65342 Erro ao enviar mensagem para o servidor 65343 Interface SAB não inicializada 65344 Erro: dados ainda não disponíveis (SAB) 65345 Erro: dados indisponíveis (SAB) 65346 Servidor SAB off-line 65347 Erro de conexão entre SCOPE e SAB 65348 Erro no NSU recebido 65349 Erro no logon do PDV 65350 Erro no processamento do chip 65351 Operadora inválida 65352 Dados, da recarga de celular, não encontrados. 65353 Transação cancelada pelo cliente 65360 Transação aprovada off-line 65361 Versão do banco de dados incompatível 65362 Cancelamento fora do prazo permitido 65363 Mensagem inválida 65364 PIN-Pad não foi aberto 65365 PIN-Pad já foi aberto – a aplicação abriu o PIN-Pad antes de conectar
ao ScopeSRV, mas não deveria ter-lo feito, pois no ScopeCNF está configurado com uso exclusivo do SCOPE
65366 Estado inválido – a aplicação está tentando obter os serviços disponíveis num estado de coleta inadequado
65367 PIN-Pad compartilhado não está configurado, mas a rede exige que seja compartilhado
65368 PIN-Pad compartilhado não trabalha com a versão 2000 da VISA 65369 Função de uso exclusivo na interface coleta 65370 Área insuficiente para os atributos do serviço 65371 O SCOPE está configurado para uso de PIN-Pad compartilhado, mas
a aplicação informou que está com o kit Visanet para PIN-Pad 65372 O SCOPE não está configurado para uso de PIN-Pad compartilhado,
mas a aplicação informou que está com PIN-Pad compartilhado 65373 Erro ao inicializar periféricos – na interface HLAPI 65374 Erro ao desmontar a estrutura ISO 65375 Bandeira não está configurada 65376 Função indisponível 65377 Valor mínimo da parcela é inválido 65378 Valor da consulta Vale Gás ainda não está disponível 65379 Número de Telefone inválido 65380 DDD inválido 65381 Erro Rede – Modelo 2 65382 Erro Rede – Modelo 3 65383 Confirmação Positiva Inconsistente 65384 Transação Offline – Permitido apenas reimpressão offline 65385 Contrato Suspenso 65386 Transação permite somente digitado
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 28
Código Resposta
Significado
65387 Não Encontrado (para quando não veio menu dinâmico na carga de tabelas).
65535 Erro genérico
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 29
Apêndice D – Glossário _____________________________________________________________________________________________________
A Acquirer: veja Adquirente
Adquirente: é a entidade ou associação de entidades
financeiras que a partir de transações efetuadas com
cartões nos estabelecimentos comerciais (Merchant)
associados, estabelece o devido vínculo com as
entidades autorizadoras (authorizing agent) (VISA,
MasterCard, Amex).
Aplicação frente de caixa: software executado no
PDV com a finalidade de realizar a venda de produtos
da empresa.
Aplicação de PDV: veja Aplicação frente de caixa.
Authorizing agent: veja Autorizador
Autorizador: é a organização (VISA, MasterCard,
Amex) que gerencia e controla operações com cartões
de crédito, passando informações entre o Adquirente e
o Banco emissor.
B Banco de dados: também conhecido como base de
dados, são arquivos ou sistemas com uma estrutura
regular que organizam informações. Essas estruturas
podem ter a forma de uma tabela: cada tabela é
composta por linhas e colunas. As informações
utilizadas para um mesmo fim são agrupadas em uma
base de dados.
Bandeira: entidade detentora de marcas e logotipos
utilizados em cartões de crédito, débito e outros meios
de pagamentos. Exemplos: Visa, Mastercard, American
Express, Visa Electron, Maestro, Cheque Eletrônico.
Banco emissor: é a entidade financeira associada a
uma ou mais organizações autorizadoras e que é
responsável pela emissão de cartões para seus
clientes.
BIN (Bank Identification Number): número de
identificação do banco representado pelos primeiros 6
dígitos do cartão.
C CHIP: também conhecido como Circuito Integrado ou
CI. Nos cartões é usado como alternativa mais segura
às tradicionais tarjas magnéticas.
E EMV (Europay Mastercard Visa): norma estabelecida
por estas três entidades para estabelecer regras de
autenticidade e segurança em TEF através de cartões
com chip.
Endereço IP (Internet Protocol): trata-se de uma
tecnologia que permite a comunicação padronizada
entre computadores, mesmo que estes sejam de
plataformas diferentes, cada máquina possui um
endereço IP que a diferencie das demais.
Estabelecimento: ou estabelecimento comercial é a
entidade que aceita o cartão (card acceptor) como
forma de pagamento referente à comercialização de
um bem ou serviço prestado ao portador do cartão
(card holder).
F FAPI (File Application Programming Interface):
Módulo SCOPE gerenciador da interface de
programação através de arquivos.
Fatura: documento emitido pela administradora do
cartão relacionando as compras realizadas no período
através do cartão de crédito.
G Grupo de serviço: um serviço no SCOPE pertence
sempre a um grupo, que pode definir a forma de
pagamento, ou ainda, a tecla finalizadora do PDV.
Exemplos: cartão de crédito, cartão de débito, consulta
de cheque, recarga de celular, estorno. Ver Serviço.
GUI: do inglês ‘Graphic User Interface’ que é a
interface gráfica exibida para o usuário da aplicação.
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 30
I Issuer: Veja Banco emissor.
M
Módulo residente: São aplicativos para DOS que
rodam e permanecem em memória volátil. É uma forma
de diminuir o programa executável para que a memória
convencional não ficasse carregada.
P PDV: acrônimo para ‘Ponto de Venda’. Terminal
inteligente utilizado na operação de pagamento. Veja
também PoS.
PIN (Personal Identification Number): número de
identificação pessoal, senha do cartão digitada em
PINPad.
PINPad: equipamento utilizado para ler um cartão, via
tarja magnética ou chip. Possui um pequeno teclado
numérico para permitir a coleta da senha.
PoS: termo em inglês ‘Point of Sale’. Veja também
PDV.
Private Label: bandeira emitida por um
estabelecimento comercial, também conhecida como
Bandeira do Lojista.
R Rede autorizadora: empresa que concentra o
recebimento de transações TEF de diversos
estabelecimentos, e as autoriza através de um sistema
autorizador. Exemplos: Visanet, Redecard, TecBan.
S SCOPE: O SCOPE é a solução Itautec para
pagamentos eletrônicos
ScopeADM (SCOPE Administrador): é o módulo
responsável por realizar consultas operacionais e
gerenciais das transações realizadas além de permitir a
geração de relatórios.
ScopeCNF (SCOPE Configurador): é o módulo
responsável pela configuração e cadastramento de
parâmetros para a solução SCOPE.
SCOPE Client: conjunto de bibliotecas localizadas na
máquina em que a aplicação de frente de loja. O
conjunto de bibliotecas pode variar conforme o sistema
operacional e a linguagem de programação utilizada.
ScopeGW (SCOPE Gateway): funciona como um
roteador de mensagens entre um ou mais servidores
SCOPE e uma ou diversas redes.
ScopeSRV (SCOPE Server): é o módulo principal da
solução SCOPE. É responsável por estabelecer o
contato inicial de todos os contratos cadastrados na
base de dados com as respectivas redes, garantindo
também o fluxo de transações com estas redes
Serviço: o termo serviço no contexto do SCOPE define
o objetivo de uma transação. Exemplos: compra com
cartão de crédito à vista, compra com cartão de crédito
parcelada pelo estabelecimento (sem juros), compra
com cartão de crédito parcelada de administradora
(com juros), compra com cartão de débito à vista,
compra com cartão de débito pré-datado, compra com
cartão de débito voucher, consulta cheque, estorno
crédito, estorno débito.
Servidor: é o computador que administra e fornece
programas e informações para os outros computadores
conectados em rede.
T TEF (Transferência Eletrônica de Fundos): termo
utilizado para se referir a uma transação de
transferência de fundos, como ocorre em uma compra
com cartão de crédito ou débito.
TSR: abreviação do termo em inglês ‘Terminate and
Stay Resident’. Veja Módulo residente.
Interface com Automação Comercial por Troca de Arquivos Solução Completa para Pagamento Eletrônico 31
2011
Esse documento é propriedade da Itautec S.A. – Grupo Itautec.
Tem caráter técnico/informativo. Todos os direitos são reservados.
Não pode, no todo ou em parte, ser copiado, fotocopiado, reproduzido, traduzido ou reduzido a qualquer meio eletrônico
ou forma legível por máquina, sem a autorização escrita da I t a u t e c S . A . - G r u p o I t a u t e c .
Esta se reserva, por outro lado, o direito de alterar seu conteúdo e forma, sem qualquer aviso prévio.
Produzido no Brasil.