Neste documento iremos detalhar todos os passos necessários para realizar a integração com o CapptaGpPlus por intermédio da API CappAPI que será utilizada para realizar toda a parte complexa e demorada da integração e facilitar a sua vida.
Possuimos duas maneiras de integração, sendo elas o modo Background e o Foreground. Ambas são bem simples de serem implementados.
Na integração Foreground cuidamos de toda a interação com o usuário para você, sendo assim basta nos enviar os dados do pagamento que iremos informar ao usuário todos os passos que precisam ser executados, desde a leitura do cartão até a sua autorização e ao final de tudo só lhe devolvemos os dados de autorização e cupons.
Por outro lado a integração Background é completamente transparente, ou seja, o CapptaGpPlus irá devolver todos os passos que devem ser executados entre ele exibição de mensagens ou a solicitação de alguns dados básicos para dar continuidade aos pagamentos.
Antes de qualquer coisa será necessário instalar a versão de homologação do CapptaGpPlus em seu ambiente de desenvolvimento, você pode adquiri-lo entrando em contato com a nossa turma de homologação.
Após a instalação solicite que ativem o modo de integração CappAPI, pronto agora seu TEF já está preparado para receber a conexão pela sua aplicação.
Fluxo de comunicação com a CappAPI
Durante a integração com a CappAPI será necessária a execução e validação de alguns procedimentos. A imagem abaixo demonstra este fluxo:
Após realizar a autenticação será necessário iniciar uma operação de pagamento, reimpressão ou cancelamento.
Ao iniciar uma operação TEF, seja pagamento ou administrativa, a CappAPI iniciará o modo de iteração.
Neste momento será necessário executar a função IterarOperacaoTef, ela irá retornar uma instância da interface IIteracaoTef.
Essa interface possui várias implementações dentre elas IRespostaOperacaoAprovada, IRespostaOperacaoNegada, IMensagem e IRequisicaoParametro (para mais detalhes sobre as propriedades e significado de cada uma destas implementações consulte Implementações da interface IIteracaoTef).
O procedimento de iteração deve ocorrer enquanto o retorno não for uma instância de IRespostaOperacaoAprovada ou IRespostaOperacaoNegada.
Caso receba uma IRespostaOperacaoNegada significa que a operação foi negada, o motivo da recusa está descrito na propriedade Motivo contida no objeto recebido.
Do contrário caso receba uma IRespostaOperacaoAprovada a operação foi aprovada e o objeto recebido possui todos os detalhes incluindo o cupom TEF relativo a operação executada.
Caso a operação aprovada seja de pagamento será necessário confirma-la ou desfaze-la.
Mais adiante iremos descrever como implementar cada um dos passos descritos acima no seu código.
Importando CappAPI
A CappAPI é um componente COM implementado em .NET. Existem as seguintes maneiras de importa-lo para o seu projeto:
Caso seu software também seja escrito em alguma da plataforma .NET a importação pode ser realizada diretamente pelo arquivo Cappta.Gp.Api.Com.dll.
Depois de importar a API basta criar uma nova instância da classe ClienteCappta e realizar a autenticação para começar a integrar outros serviços.
Abaixo são demonstrados os passos necessários para efetuar a importação da API em seu projeto Delphi. A IDE usada é a Lazarus 1.4.2.
Buscando o plugin necessário
No menu do topo, vá em Pacote > Instalar/desinstalar pacotes.
No campo disponível para instalação, digite LazActiveX 0.1. Selecione o plugin e depois clique em Instalar Seleção.
Após isso, clique em Salvar e Reconstruir IDE. Terminado o processo, o Lazarus será reinicializado.
Importando o componente
No menu do topo, vá em Ferramentas > Import Type Library.
Clique na aba ActiveX References, selecionando o componente Cappta_Gp_Api_Com.
OBS.: Este item irá aparecer apenas se o CapptaGpPlus, versão 3.1 ou posterior, estiver instalado na máquina.
Após clicar em OK, será mostrada a janela do editor de código, com um novo unit. Grave este novo arquivo.
Com isso, basta criar uma nova instância da classe IClienteCappta e realizar a autenticação para começar a integrar outros serviços.
var cappta : IClienteCappta;
string chaveAutenticacao = "2C1CE88C-6A0C-4FA6-BF2D-519B1DB31DF4";
chaveAutenticacao : string = '2C1CE88C-6A0C-4FA6-BF2D-519B1DB31DF4';
cnpj string É o CNPJ da loja que está utilizando o TEF da Cappta, precisa ser equivalente ao que está configurado no CapptaGpPlus
pdv int Número de pdv do CNPJ que está utilizando o TEF da Cappta, precisa ser equivalente ao que está configurado no CapptaGpPlus
chaveAutenticacao string Chave de autenticação do integrador disponibilizada pela turma de homologação
Após realizar a autenticação, é possível configurar sua integração com a CappAPI e definir algumas regras específicas (confira detalhes nas tabelas abaixo), para isso a classe ClienteCappta disponibiliza o método Configurar.
configs IConfiguracoes Objeto contendo as opções disponiveis para configurar o CapptaGpPlus
ExibirInterface Não. Por padrão sempre é false bool Determina a maneira de integração com a CappAPI, caso seja enviado true, cuidamos de toda a interação com o usuário para você (integração Foreground). Caso seja enviado false, a integração será completamente transparente (Background), ou seja, o CapptaGpPlus irá devolver todos os passos que devem ser executados, entre eles a exibição de mensagens ou a solicitação de alguns dados básicos para dar continuidade aos pagamentos.
Obs.: A chamada do método Configurar é opcional, se a sua integração não necessita de configurações específicas, não é necessário chama-lo.
Abaixo serão descritos todos os passos necessários para efetuar a recarga pela CappAPI.
O primeiro passo para a recarga é obter as operadoras disponíveis, para isso basta fazer uma simples requisição.
var resultado = cappta.ObterOperadoras();
if (resultado.CodigoResposta != 0)
Console.WriteLine("Não foi possível resgatar as operadoras");
//Agora basta continuar o fluxo de iteração de recarga aqui.
detalhesOperadoras : IDetalhesOperadoras;
detalhesOperadoras := cliente.ObterOperadoras;
if detalhesOperadoras.CodigoResposta <> 0 then
WriteLn('Não foi possível resgatar as operadoras');
// -- Agora basta continuar o fluxo de iteração de recarga aqui --
O segundo passo para a recarga é obter os produtos disponíveis para a operadora escolhida, para isso basta fazer uma simples requisição passando a operadora escolhida.
operadora string nome da operadora
//Obtenha e escolha sua operadora aqui.
var resultado = cappta.ObterProdutosOperadoras(operadora);
Console.WriteLine("Não foi possível resgatar os produtos de recarga.");
detalhesProdutos : IDetalhesProdutosOperadoras;
operadora : WideString;
// -- Obtenha e escolha sua operadora aqui. --
detalhesProdutos := cliente.ObterProdutosOperadoras(operadora);
WriteLn('Não foi possível resgatar os produtos de recarga.');
Depois de escolhermos a operadora e o produto é hora de realizar a recarga, para isso só precisaremos do ddd, número de celular e valor da recarga (se o produto for variável).
Para captura do número de celular do cliente, sugerimos a utilização do método Obter telefone pelo pinpad
//Obtenha e escolha sua operadora, produto, número de celular e valor aqui.
var recarga = new DetalhesRecarga();
recarga.Celular = celular; // inteiro.
recarga.Ddd = ddd; // inteiro.
recarga.Produto = produto; //IProdutoRecarga
recarga.ValorRecarga = valor; // double
var resultado = cappta.RecargaCelular(recarga);
if (!resultado is IRespostaRecarga)
Console.WriteLine("Não foi possível realizar a recarga.");
//Agora basta imprimir o cupom.
detalhesRecarga : IDetalhesRecarga;
produto : IProdutoRecarga;
celular : Integer;
ddd : Integer;
iteracao: IIteracaoTef;
// -- Obtenha e escolha sua operadora, produto, número de celular e valor aqui. --
detalhesRecarga := CoDetalhesRecarga.Create;
detalhesRecarga.Celular:= celular;
detalhesRecarga.Ddd:= ddd;
detalhesRecarga.ValorRecarga:= valor;
detalhesRecarga.Produto := produto;
iteracao := cliente.RecargaCelular(detalhesRecarga);
if Not (iteracao is IDetalhesRecarga) then
WriteLn('Não foi possível realizar a recarga.');
// -- Agora basta imprimir o cupom. --
recarga DetalhesRecarga Objeto contendo o detalhamento da recarga
Detalhes da Recarga
Celular Sim string número do celular onde será efetuada a recarga.
Ddd Sim int DDD do número onde será efetuada a recarga.
Produto Sim IProdutoRecarga Produto a ser comprado na recarga.
ValorRecarga Sim double Valor do produto a ser comprado na recarga.
Abaixo serão descritas todas as formas de pagamento disponibilizadas pela CappAPI
int resultado = cappta.PagamentoDebito(10D);
valor double Valor do pagamento
detalhes IDetalhesCredito Objeto contendo o detalhamento do pagamento à crédito
TransacaoParcelada Sim. Por padrão sempre é false bool Determina se o pagamento será parcelado
TipoParcelamento Somente se TransacaoParcelada for true int Determina a configuração do parcelamento, verifique a tabela Tipos de Parcelamento para consultar os valores possíveis
QuantidadeParcelas Somente se TransacaoParcelada for true int Quantidade de parcelas do pagamento
valor Valor do pagamento
detalhes Objeto contendo o detalhamento do pagamento crediário
QuantidadeParcelas Sim int Quantidade de parcelas do pagamento
Existem dois tipos de reimpressão de cupons, aquele que reimprime o cupom do último pagamento ou cancelamento e também outra versão que permite especificar qual é o pagamento a partir do número de controle.
tipoVia Determina qual a via do cupom que deve ser reimpressa, verifique a tabela Tipos de Vias para Reimpressão para consultar os valores possíves
Do contrário caso queira reimprimir um cupom especiífico utilize a seguinte função:
numeroControle Identificador única para pagamentos, é devolvido quando a transação é autorizada mas também pode ser consultado no portal de transações Cappta
senhaAdministrativa Senha solicitada no CapptaGpPlus necessária para liberar o acesso à cancelamentos de pagamentos
É necessário atentar-se ao seguinte detalhe, ao receber uma resposta de Operação Aprovada caso seja um pagamento não será possível executar nenhuma outra operação até que se tenha confirmado ou desfeito a atual.
Para mais detalhes sobre as implementações da interface IIteracaoTef que é retornada consultar a sessão Implementações da interface IIteracaoTef
Enviando parametros adicionais para a CappAPI
Esse código é apenas ilustrativo não o utilize
if tipoIteracao <> 4 then
// -- Sendo 1 para "Avançar" e 2 para "Cancelar" --
parametro string Valor informado pelo usuário final
acao int Existem apenas duas possibilidades, sendo elas 1 para avançar e 2 para cancelar a operação. Caso receba uma ação de cancelamento o valor do primeiro parâmetro será ignorado
Sempre que retornamos Operação Aprovada, ficamos aguardando a confirmação por parte da sua automação para finalizar a operação de pagamento.
O multi-cartões da Cappta é um pouco diferente do mercado. Desenvolvemos ela em busca de facilitar a vida do varejista. Ou seja, caso ocorra algum erro durante o pagamento multi-cartões o varejista não vai precisar cancelar as transações uma a uma, com um simples comando de cancelamento por meio da sua automação, ele poderá cancelar todas as transações dentro da sessão Multi Cartões.
Uma sessão multi-cartões torna possível que sejam autorizados uma quantidade de pagamentos equivalente ao que foi informado no parâmetro quantidadePagamentos sem a necessidade de finaliza-los ao serem autorizados, porém ao executar uma função de finalização (confirmação ou desfazimento) todos os pagamentos serão afetados. Ou seja, ao confirmar, confirma todos e ao desfazer, desfazer e cancela todos os pagamentos. A sessão multi cartões é representada pelo fluxograma abaixo:
quantidadePagamentos Número de pagamentos dentro da sessão multi cartões
Dentro de uma sessão multi cartões o timeout para confirmação ou desfazimento do CapptaGpPlus somente será ativado após a aprovação de todos os pagamentos.
Cpf 1 Representa um número do documento CPF, que contem 11 dígitos.
Telefone/Celular 2 Representa um número de telefone ou celular, contendo 10 ou 11 dígitos. DDD + Número, exemplo : (00) 91234-1234 ou (00) 1234-1234
Senha 3 Representa uma senha numérica de 4 a 12 dígitos.
1 Não autenticado/Alguma das informações fornecidas para autenticação não é válida
2 CapptaGpPlus está sendo inicializado
7 Erro interno no CapptaGpPlus
8 Erro na comunicação entre a CappAPI e o CapptaGpPlus
9 Ocorre quando qualquer operação é realizada sem que se tenha finalizado o último pagamento
10 Uma reimpressão ou cancelamento foi executada dentro de uma sessão multi-cartões
14 Valor digitado no pinpad é inválido.
3 Formato da requisição recebida pelo CapptaGpPlus é inválido
4 Operação cancelada pelo operador
5 Pagamento não autorizado/pendente/não encontrado
6 Pagamento ou cancelamento negados pela rede adquirente ou falta de conexão com internet
1 Parcelamento Administradora - Configuração de parcelamento em que os juros são arcados pelo banco ou administradora, o limite de parcelas e valor mínimo são pré-estabelecidos e a venda não é tratada como parcelada para o lojista sendo assim o valor será depoistado integralmente em sua conta bancária. O cliente irá pagar as prestações com juros que serão revertidos para o banco/administradora do cartão
2 Parcelamento Lojista - É o parcelamento em que a quantidade de parcelas é definida no ato da compra. O limite de quantidade de parcelas e valor mínimo para cada uma pode ser determinado nas configurações do CapptaGpPlus. O lojista irá receber os créditos mensalmente em sua conta e o custo pelo financiamento é definido e arcado pelo próprio estabelecimento
1 Todas as vias, tanto a lojista como a do cliente
2 Somente a via do cliente
3 Somente a via do lojista
TipoIteracao int Representa o tipo de iteração de mensagem e possui o valor fixo 1
NsuTef ulong Número sequencial único do canal de pagamento
NsuAdquirente string Número sequencial único da adquirente
CodigoAutorizacaoAdquirente string Código de autorização retornado pela adquirente
CupomCliente string Comprovante de pagamento ou estorno do cliente
CupomLojista string Comprovante de pagamento ou estorno do estabelecimento
CupomReduzido string Comprovante de pagamento ou estorno com tamanho reduzido
NomeAdquirente string Nome da adquirente responsável pela aprovação do pagamento ou cancelamento
NomeBandeiraCartao string Nome da bandeira do cartão do cliente
NumeroControle string Identificador único para pagamentos, é devolvido quando a transação é autorizada mas também pode ser consultado no portal de transações Cappta
DataHoraAutorizacao DateTime Contém a data + hora completa da autorização do pagamento ou cancelamento
CodigoBandeiraCartao int Código da bandeira do cartão, consulte aqui a Tabela de bandeira de cartões
NumeroCartaoCliente string Número do cartão (PAN) utilizado no pagamento, cifrado no seguinte formato: 999999******9999
NumeroAfiliacao string Número de afiliação do estabelecimento na rede adquirente. Obs.: Também conhecido como "Número Lógico" ou "Código do Estabelecimento"
QuantidadeParcelas int Quantidade de parcelas do pagamento. Para pagamentos na modalidade Débito ou Crédito à vista, terá como valor padrão 1
CodigoMotivo int Código que representa o motivo pelo qual a operação foi negada, as possibilidades deste código podem ser consultadas na tabela [Códigos de motivo para operações negadas]
TipoIteracao int Representa o tipo de iteração de mensagem e possui o valor fixo 2
Motivo string Descreve o motivo pelo qual a operação foi negada
Mensagem string É a mensagem enviada pelo CapptaGpPlus para ser exibida para o operador (opcionalmente)
ListaTransacoesPendentes array de objeto do tipo ITransacaoPendente Lista das transações que ficaram pendente
TipoIteracao int Representa o tipo de iteração de mensagem e possui o valor fixo 8
Detalhes da transação pendente
NumeroControle string Identificador única para pagamentos, é devolvido quando a transação é autorizada mas também pode ser consultado no portal de transações Cappta
DataHoraAutorizacao DateTime Contém a data+ hora completa da autorização do pagamento ou cancelamento
Valor double Valor da transação
Descricao string É a mensagem enviada pelo CapptaGpPlus para ser exibida para o operador
TipoIteracao int Representa o tipo de iteração de mensagem e possui o valor fixo 3
TipoIteracao int Representa o tipo de iteração de mensagem e possui o valor fixo 4
Mensagem string É a mensagem enviada pelo CapptaGpPlus para ser exibida para o operador, ela contém a solicitação do parâmentro necessário para proseguir com a operação TEF
Em conjunto com este manual você deve ter recebido um pacote com projetos de teste e aplicações de diversas linguagens, para simular a integração e facilitar o desenvolvimento em seu próprio software. Para utiliza-lo é necessário configura-lo de acordo com o sample da linguagem escolhida:
Para csharp, abra o arquivo app.config e altere as chaves do nó appSettings.
Já para delphi, abra o arquivo autenticacao.xml, o nó autenticacao, e altere os valores dos nós internos.
Os valores a serem inseridos são estes abaixo:
ChaveAutenticacao - Chave de autenticação recebida na abertura do processo de integração com a Cappta.
Cnpj - CNPJ da loja que está utilizando o TEF da Cappta, precisa ser equivalente ao que está configurado no CapptaGpPlus.
Pdv - Número de pdv do CNPJ que está utilizando o TEF da Cappta, precisa ser equivalente ao que está configurado no CapptaGpPlus.