Manual de Integração
Antes de tudo você precisa saber que existem diversos métodos de integração, veja abaixo quais são:
Foreground: Integração visível, quando a interface da Cappta aparece para o usuário.
Background: Interação com o usuário fica por conta da software house. (personalizável).
API WEB: Sempre visível, utiliza dados de um Javascript em um webservice.
Intpós: Troca de arquivos. Modelo mais antigo de integração do mercado (não recomendado).
É necessário instalar e configurar o Pinpad para que a instalação do ambiente de desenvolvimento possa ser concluída.
Caso escolha utilizar uma máquina virtual com Pinpad físico, será necessário habilita-lo
clicando no ícone USB localizado no menu inferior direito do Virtual box.
Fale conosco através dos canais:
Telefone: (11) 4302-6179
Skype: homologa.cappta1
E-mail: homologa@cappta.com.br
É muito importante termos registros de nossas atividades,
afim de melhor atende-lo, por isso não esqueça de preencher
um pequeno formulário clicando neste link.
Neste documento iremos detalhar todos os passos necessários para realizar a integração com o CapptaGpPlus por intermédio de nosso Checkout, que será utilizado para realizar toda a parte complexa e demorada da integração e facilitar a sua vida.
Com o Checkout Cappta, 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.
Ambiente de testes
Versão do CapptaGpPlus
O time de tecnologia da Cappta preza pela retrocompatibilidade de nossa aplicação.
Sendo assim se a versão para homologação for uma diferente da instalada em produção não haverá problemas de integração.
Para ter acesso ao nosso software e iniciar os testes de integração, entre em contato com o time. A instalação é super pratica e fácil.
Para instalar siga os passos:
Na sua área de trabalho execute o GP clicando sobre o ícone, aguarde a conclusão até aparecer uma mensagem
"Estamos prontos para capturar seus pagamentos".
No taskbar click com botão direito e procure a opção configurações.
Clique no botão gravar para que suas configurações fiquem salvas.
Máquinas Virtuais
Para instalação de nossa solução em ambiente virtual siga exatamente o exemplo
anterior apenas fique atento com a configuração do Pinpad. Basta habilita-lo.
Clique com o botão direito do mouse sobre o ícone (USB) e selecione
o Pinpad que deseja habilitar.
Para configurar a Integração do checkout Web entre em contato
com o time e peça a senha do dia.
Atenção!
Quando estiver configurando, escolha o drive de acordo com o fabricante do PINPAD.
Utilizando o código de exemplo
Em conjunto com este manual você deve ter recebido um projeto de teste para simular a integração e facilitar o desenvolvimento em seu próprio software.
Em conjunto com este manual você deve ter recebido um projeto de teste para simular a integração e facilitar o desenvolvimento em seu próprio software.
É necessário rodar essa aplicação em um servidor local de sua preferência (IIS, Apache, Nginx e etc) para que o index.html esteja dentro de um protocolo http://. Não será possível rodar a aplicação abrindo o arquivo no navegador através de file:///.
Para utiliza-lo é necessário configura-lo, para isso, abra o arquivo sample.js e altere os valores
da variável authenticationRequest, logo no inicio do arquivo.
Os valores a serem inseridos são estes abaixo:
var authenticationRequest = {
authenticationKey: '2C1CE88C-6A0C-4FA6-BF2D-519B1DB31DF4'
};- Instale o Node Js na sua máquina, para download aqui
- Coloque a pasta sample-aplication no disco C
- Via prompt de comando, acesse o diretorio "sample-application
- Execute o comando "npm install"
- Execute o comando "npm run gulp"
- Execute o comando "npm install"
- O sample irá rodar automaticamente no endereço http://localhost:8000/
- Para saber mais sobre o Node JS
- authenticationRequest - Chave de autenticação recebida na abertura do processo de integração com a Cappta.
- *merchantCnpj - CNPJ da loja que está utilizando o TEF da Cappta, precisa ser equivalente ao que está configurado no CapptaGpPlus.
- checkoutNumber - Número de pdv do CNPJ que está utilizando o TEF da Cappta, precisa ser equivalente ao que está configurado no CapptaGpPlus.
Preparativos para integração
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 o nosso time de homologação. Após a instalação solicite que ativem o modo de integração Checkout Cappta.
Após ativação do modo de integração, o CapptaGpPlus já está preparado para receber a conexão pela sua aplicação.
Fluxo de comunicação com o Checkout Cappta
Durante a integração com o Checkout Cappta será necessária a execução e validação de alguns procedimentos. A imagem ao lado demonstra este fluxo:
- Após realizar a autenticação será necessário iniciar uma operação de pagamento ou cancelamento.
- Ao iniciar uma operação TEF, seja pagamento ou cancelamento o Checkout Cappta será exibido, neste momento
o operador irá interagir diretamente no checkout até que a operação seja finalizada. - Após o final da transação, seja aprovada ou negada, o Checkout Cappta irá fechar e a resposta será retornada
pelos callbacks informados durante a chamada da operação.
Mais adiante iremos descrever como utilizar cada função disponível pela API.
Importando o Checkout Cappta
O Checkout Cappta é uma API JavaScript, por isso é muito simples importa-la, basta incluir na sua página o seguinte tag abaixo:
<script type="text/javascript" src="https://s3.amazonaws.com/cappta.api/v2/dist/cappta-checkout.js"></script>Realizando a autenticação
Antes de realizar seus pagamentos será necessário autenticar o seu PDV, para isso a API disponibiliza a função authenticate.
var authenticationRequest = {
authenticationKey: '795180024C04479982560F61B3C2C06E'
};
var success = function(response) {
// callback para autenticação bem sucedida
console.log(response.merchantCheckoutGuid);
};
var error = function(response) {
// callback para autenticação que falhou
console.log(response.reason);
};
var handlePendingPayments = function(response) {
// callback para notificação de transações pendentes
console.log(response.details.administrativeCodes)
};
// instância do CheckoutCappta
var checkout = CapptaCheckout.authenticate(authenticationRequest, success, error, handlePendingPayments);Essa função retorna uma instância do Checkout Cappta, através dela você terá acesso a todas as funções disponibilizadas pela API, que serão descritas mais abaixo.
authenticationKey
string
Chave de autenticação do integrador disponibilizada pelo time de homologação.
merchantCnpj
string
É o CNPJ da loja que está utilizando o TEF da Cappta, precisa ser equivalente ao que está configurado no CapptaGpPlus.
checkoutNumber
number
Número de pdv do CNPJ que está utilizando o TEF da Cappta, precisa ser equivalente ao que está configurado no CapptaGpPlus.
Callback de sucesso
Será executado o callback de sucesso quando a autenticação for bem sucedida, através dele será passado os seguintes parâmetros:
authenticated
bool
Confirmação da autenticação efetuada com sucesso.
merchantCheckoutGuid
string
Token do PDV autenticado, guarde esse valor pois ele será necessário para capturar mais detalhes da sua transação através da API restful, vamos explicar com mais detalhes em seguida.
Callback de erro
Será executado o callback de erro quando não for possível autenticar com o CapptaGpPlus, através dele será passado os seguintes parâmetros:
reasonCode
number
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
reason
string
Descreve o motivo pelo qual a operação foi negada
Callback de transações pendentes
Será executado o callback de transações pendentes caso a última sessão de múltiplos pagamentos tenha ficado em aberto.
Por exemplo: Foi informada a quantidade de 5 pagamentos para iniciar a sessão de múltiplos pagamentos, porém ao final do 3° ocorreu um erro e a página foi recarregada, no momento que for realizada a autenticação novamente, essa função será chamada, o código administrativo dos 3 pagamentos realizados será informado e nesse momento você deve confirmar ou desfazer as transações para finalizar a sessão pendente. Veja mais detalhes na sessão de Multiplos pagamentos.
reasonCode
number
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
details
object
Objeto contendo os códigos administrativos das transações que ficaram pendentes da sessão de multiplos pagamentos.
Para detalhamento dos códigos de retorno consulte a tabela Possíveis códigos de retorno
Para recuperar o CNPJ e PDV do TEF basta clicar com o botão direito do mouse no ícone do CapptaGpPlus no taskbar do windows e selecionar a opção Sobre o Cappta Cartões a tela que será exibida contém as informações necessárias.
A chave de autenticação será fornecida pelo time de homologação assim que o processo de integração for solicitado. Ela deverá ser sempre utilizada para identificar o seu software.
Obs: Caso a chave utilizada seja inválida, o CapptaGpPlus não irá autenticar a integração.
Pagamento
Pagamento Débito / Voucher
//Não esqueça de realizar a autenticação aqui \o/
var success = function(response) {
// callback para pagamento bem sucedido
console.log(response.administrativeCode);
console.log(response.receipt.merchantReceipt);
};
var error = function(response) {
// callback para pagamento que falhou
console.log(response.reason);
};
checkout.debitPayment({ amount: 10 }, success, error);Para realizar um pagamento débito ou voucher é bem simples, basta informar o valor a ser debitado.
amount
Sim
float
Valor do pagamento
Para detalhamento das funções de sucesso e erro, consulte a sessão de Callback das operações
.
Pagamento Crédito
O pagamento crédito também é bem simples, porém precisamos de alguns dados a mais para configura-lo,
como quantidade de parcelas e a configuração de parcelamento (confira logo abaixo para mais detalhes).
//Não esqueça de realizar a autenticação aqui \o/
var request = {
amount: 10,
installments: 3,
installmentType: 1 //Parcelamento Administradora
};
var success = function(response) {
// callback para pagamento bem sucedido
console.log(response.administrativeCode);
console.log(response.receipt.merchantReceipt);
};
var error = function(response) {
// callback para pagamento que falhou
console.log(response.reason);
};
checkout.creditPayment(request, success, error);Atenção!
Para detalhamento das funções de sucesso e erro, consulte a sessão de Callback das operações
amount
Sim.
number
Valor do pagamento
installments
Sim.
number
Determina a quantidade de parcelas do pagamento, caso seja informado 1 a venda será realizada como crédito à vista, caso seja maior que isso será um crédito parcelado. Caso não seja informado o valor default é igual a 1, ou seja, a venda será considerada automaticamente a vista.
installmentType
Somente se installments for maior que 1
number
Determina a configuração do parcelamento, verifique a tabela Tipos de Parcelamento para consultar os valores possíveis
Pagamento Crediário
//Não esqueça de realizar a autenticação aqui \o/
var request = {
amount: 10,
installments: 3
};
var success = function(response) {
// callback para pagamento bem sucedido
console.log(response.administrativeCode);
console.log(response.receipt.merchantReceipt);
};
var error = function(response) {
// callback para pagamento que falhou
console.log(response.reason);
};
checkout.splittedDebitPayment(request, success, error);using System;
using System.Net.Http;
var baseAddress = new Uri("https://integracao.cappta.com.br/payment/");
using (var httpClient = new HttpClient{ BaseAddress = baseAddress })
{
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("apikey", "1B489E726C284CC78DE715C7399114BF");
using(var response = await httpClient.GetAsync("0C63C53CF0094F9E95F6803C965BDF5C/02312413000"))
{
string responseData = await response.Content.ReadAsStringAsync();
}
}<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://integracao.cappta.com.br/payment/0C63C53CF0094F9E95F6803C965BDF5C/02312413000");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
"apiKey: 1B489E726C284CC78DE715C7399114BF"
));
$response = curl_exec($ch);
curl_close($ch);
var_dump($response);Assim como o pagamento crédito o crediário também necessita de alguns dados a mais para facilitar o seu processamento.
amount
SIm
float
Valor do pagamento
installments
Sim
number
Quantidade de parcelas do pagamento
Para detalhamento das funções de sucesso e erro, consulte a sessão de Callback das operações
Cancelamento de pagamentos
//Não esqueça de realizar a autenticação aqui \o/
var request = {
administrativePassword: 'cappta',
administrativeCode: '000000000'
};
var success = function(response) {
// callback para cancelamento bem sucedido
console.log(response.administrativeCode);
console.log(response.receipt.merchantReceipt);
};
var error = function(response) {
// callback para cancelamento que falhou
console.log(response.reason);
};
checkout.paymentReversal(request, success, error);Somente será possível cancelar pagamentos que já foram confirmados dentro do mesmo dia ou seja não será possível cancelar pagamentos de dias anteriores.
NOTA: No caso de uma transação conter uma ordem de split esta será cancelado também.
administrativePassword
administrativeCode
administrativeCode
Identificador único para pagamentos, é devolvido quando a transação é autorizada mas também pode ser consultado no portal de transações Cappta
Callback das operações
Para cada operação com o CapptaGpPlus, seja pagamento ou cancelamento, além do objeto de request para cada operação você irá passar duas funções como parâmetro, que serão descritas abaixo:
Será executado o callback de sucesso da operação logo que o pagamento ou cancelamento for bem sucedido, através dele será passado as seguintes informações:
administrativeCode
string
Identificador único para pagamentos, é devolvido quando a transação é autorizada mas também pode ser consultado no portal de transações Cappta.
acquirerAffiliationKey
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”.
acquirerAuthorizationCode
string
Código de autorização retornado pela adquirente.
acquirerAuthorizationDateTime
date
Contém a data + hora completa da autorização do pagamento ou cancelamento.
acquirerName
string
Nome da adquirente responsável pela aprovação do pagamento ou cancelamento.
acquirerUniqueSequentialNumber
string
Número sequencial único da adquirente.
cardBrandCode
number
Código da bandeira do cartão.
cardBrandName
string
Nome da bandeira do cartão do cliente.
customerCardPan
string
Número do cartão (PAN) utilizado no pagamento, cifrado no seguinte formato: 999999**9999
installments
number
Quantidade de parcelas do pagamento.
uniqueSequentialNumber
string
Número sequencial único do canal de pagamento.
receipt
object
Objeto contento os cupons para impressão, mais detalhes na tabela abaixo.
customerReceipt
string
Cupom do cliente
merchantReceipt
string
Cupom do lojista
reducedReceipt
string
Cupom reduzido
reasonCode
number
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
reason
string
Descreve o motivo pelo qual a operação foi negada.
Capturando todos os dados da transação
GET https://integracao.cappta.com.br/payment/checkoutGuid/administrativeCode
A chamada acima retornam um JSON estruturado como este:
{
"AcquirerAffiliationKey": "SIMULA",
"AcquirerAuthorizationCode": "SIMULA",
"AuthorizationDateTime": "2017-02-03T14:13:45",
"AcquirerName": "Cielo",
"AcquirerUniqueSequentialNumber": "",
"AdministrativeCode": "02312413000",
"CardBrandName": "MASTERCARD",
"CustomerCardBin": "605088",
"CustomerCardLastFourDigits": "8775",
"CustomerReceipt": "Cupom do cliente",
"MerchantReceipt": "Cupom do lojista",
"ReducedReceipt": "Cupom reduzido",
"PaymentProductName": "Crédito à Vista",
"PaymentTransactionAmount": 7.89,
"PaymentTransactionInstallments": 1,
"UniqueSequentialNumber": "013214"
}using System;
using System.Net.Http;
var baseAddress = new Uri("https://integracao.cappta.com.br/payment/");
using (var httpClient = new HttpClient{ BaseAddress = baseAddress })
{
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("apikey", "1B489E726C284CC78DE715C7399114BF");
using(var response = await httpClient.GetAsync("0C63C53CF0094F9E95F6803C965BDF5C/02312413000"))
{
string responseData = await response.Content.ReadAsStringAsync();
}
}<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://integracao.cappta.com.br/payment/0C63C53CF0094F9E95F6803C965BDF5C/02312413000");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
"apiKey: 1B489E726C284CC78DE715C7399114BF"
));
$response = curl_exec($ch);
curl_close($ch);
var_dump($response);Assim que você realizar um pagamento ou cancelamento através do Checkout Cappta, receberá o código administrativo da transação e os cupons para impressão.
Alem dessas informações, você pode capturar outros dados sobre a transação, e para isso disponibilizamos uma API REST.
merchantCheckoutGuid
Sim
string - no caminho da solicitação
GUID do PDV, recebido no momento da autenticação.
administrativeCode
Sim
string - no caminho da solicitação
Identificador único para pagamentos, é devolvido quando a transação é autorizada mas também pode ser consultado no portal de transações Cappta.
apiKey
Sim
string - no header da solicitação
Chave de autenticação do integrador disponibilizada pelo time de homologação
Inicializando uma sessão de multiplos pagamentos
O múltiplos pagamentos 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 múltiplos pagamentos 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 que foram realizadas dentro da sessão Múltiplos Pagamentos.
//Não esqueça de realizar a autenticação aqui \o/
var complete = function(){
console.log('Sessão multiplos pagamentos finalizada com sucesso!');
};
checkout.startMultiplePayments(3, complete);Assim que o último pagamento da sessão múltiplos pagamentos for autorizado, automaticamente todos os pagamentos serão confirmados, não há necessidade de enviar nenhum comando para isso. A sessão múltiplos cartões é representada pelo fluxograma abaixo:
numberOfPayments
number
Número de pagamentos dentro da sessão multiplos pagamentos.
complete
function
Callback que será acionado assim que a sessão multiplos pagamentos for finalizada.
Confirmando ou desfazendo os pagamentos
//Não esqueça de realizar a autenticação aqui \o/
if (confirm('Deseja encerrar a sessão multiplos pagamentos?')){
if (confirm('Clique em "Ok" para confirmar os pagamentos da sessão ou "Cancel" para desfaze-los')){
checkout.confirmPayments();
} else {
checkout.undoPayments();
}
}Para finalizar uma sessão múltiplos cartões antes que se tenha aprovado a quantidade de pagamentos informada, basta confirmar (confirmPayments) ou desfazer (undoPayments) os pagamentos pendentes.
Reforçamos que os pagamentos serão aprovados automaticamente ao terminar a sessão, a confirmação ou desfazimento é necessária apenas para encerrar a sessão antes do último pagamento, por exemplo: Foram informados 5 pagamentos para sessão, porém ao final do 3° surgiu a necessidade desfazer todos os anteriores, nesse momento deve ser chamada a função undoPayments.
Existe um limite de no máximo 9 cartões para uma sessão.
Solicitando informações pelo Pinpad
//Não esqueça de realizar a autenticação aqui \o/
var success = function (response) {
console.log(response.pinpadValue);
};
var error = function (response) {
console.log(response.reason);
};
var inputType = 1; // CPF
checkout.getPinpadInformation({ inputType: inputType }, success, error);Utilizando esta função, é possível solicitar informações a serem digitadas no pinpad. As opções consistem em: CPF, Telefone/Celular e senha.
inputType
Sim
number
Tipo de informação a ser solicitada no pinpad. Consulte a tabela abaixo para os valores.
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.
Será executado o callback de sucesso logo em que for confirmada a informação no Pinpad:
reasonCode
number
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
reason
string
Descreve o motivo pelo qual a operação foi negada.
Possíveis códigos de retorno
0
Sucesso
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 o Checkout Cappta 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.
15
Existem pagamentos pendentes de uma sessão de multiplos pagamentos não finalizada.
Códigos de motivo para operações negadas
1
Não autenticado/Alguma das informações fornecidas para autenticação não é válida
2
CapptaGpPlus está sendo inicializado
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
7
Erro interno no CapptaGpPlus
8
Erro na comunicação entre o Checkout Cappta e o CapptaGpPlus
Tipos de Parcelamento
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
O que é Recorrência:
Com a Cappta é possível cobrar seus clientes de forma recorrente através de planos e assinaturas.
A recorrência de pagamentos é a forma com que a loja consegue cobrar seus clientes de maneira pré-definida e continua baseando-se em planos que mais se encaixem no seu modelo de negócio. Umas das vantagens da recorrência é o fato de que ela não compromete limite do cartão do cliente durante o período da assinatura, cobrando apenas o valor estipulado mensalmente.
O plano define como a loja gostaria de cobrar seu cliente. Ao criar um plano é definido diversos parâmetros como periodicidade da cobrança (dias, semanal, mensal, trimestral, etc), a duração e o valor a ser cobrado. Cada plano tem uma lista de itens que correspondem aos produtos e/ou serviços oferecidos naquele plano, a soma dos valores desses itens define o valor do plano a ser cobrado.
Uma assinatura é o vínculo entre o cliente final e o plano contratado, nela são adicionados o cliente e o cartão que será utilizado nas cobranças. Para uma assinatura ser criada é necessário existir pelo menos um plano no qual ela será vinculada, ou seja, um plano pode ter várias assinaturas e uma assinatura pode estar atrelada somente a um plano.
Após a assinatura feita é possível personaliza-la acrescentando mais itens que não estavam no plano ou aplicando descontos. Esses itens podem ser temporários, escolhendo a quantidade de ciclos que devem ser aplicados, ou permanentes, sendo aplicado a todos os ciclos até o final da recorrência.
Plano
Planos são as propostas apresentadas pelas empresas aos clientes para oferecerem seus serviços. Com eles a empresa pode montar diversas formas de cobranças, itens, valores e periodicidade oferecendo uma grande variedade de opções para os clientes.
Criar Plano
var request = {
name: "Plano Ingles Premium",
description: "Plano anual de ingles com aulas e matrial incluso",
statement_descriptor: "Ingles Plano Premium",
cycles: 12,
interval: "month",
interval_count: 1,
trial_period_days: 15,
items: [
{
name: "Aula",
description: "Aulas presenciais",
quantity: 1,
cycles: 12,
price: 12900
},
{
name: "Material",
description: "Material utilizado em aula",
quantity: 1,
cycles: 6,
price: 5990
}
]
};
var onRecurrencySuccess = function (response) {
console.log(response);
};
var onRecurrencyDenied = function (error) {
updateResult('Código: ' + error.reasonCode + '<br>' + error.reason);
};
checkout.createPlan(request, onRecurrencySuccess, onRecurrencyDenied);Esse método é utilizado para criar um plano. Para isso é preciso criar um objeto plano passando obrigatóriamente name, description, interval_count e os items que compõem o plano como mostra na tabela abaixo:
Request para criar plano
name
String
Sim
Nome do plano.
description
String
Sim
Descrição do plano.
statement_descriptor
String
Não
Texto exibido na fatura do cartão.
cycles
Int
Não
Representa a quantidade de vezes que o cliente será cobrado.
interval
String
Sim
Periodicidade no qual será feita a cobrança do plano.
Os valores possíveis são week, month ou year
interval_count
Int
Sim
ntervalo da cobrança. Ex:
plano mensal = interval_count (1) e interval (month)
plano semestral = interval_count (6) e interval (month)
plano anual = interval_count (1) e interval (year)
trial_period_days
Int
Sim
Período de teste em dias. A assinatura só será cobrada após esse périodo.
items
Array de
Itens do Plano
Sim
Itens do plano.
Para mais informações sobre itens do plano clique aqui
Uma escola de inglês oferece um curso premium de um ano e deseja cobrar seus clientes com a recorrência. Um plano é a representação desse curso dentro da recorrência. Para esse curso com duração de um ano o cycles dele será igual a 12 representando as doze cobranças que serão feitas. O intervalo dessas cobranças é mensal, logo o interval recebe o valor de “month” e o interval_count que representa a quantidade de meses de um período será 1. Quando um cliente assinar esse plano a escola quer dar um presente ao aluno de 15 dias de aulas antes de começar a cobrar, então o trial_period_days será 15.
O valor de um plano é definido pela soma dos price de seus itens
Nesse plano estão inclusos as aulas e o material, representados por dois itens. A aula será cobrada durante todo o curso então o cycles do item será 12 e o valor dele é representado pelo price de 12900 (que é o equivalente a R$129,00). O material só será cobrado nas 6 primeiras parcelas da recorrência então o cycles é definido como 6 e o price de 5990 (R$ 59,90).
O valor de um plano é definido pela soma dos price de seus itens, portanto nesse exemplo o plano tem valor de R$188,90 (12900 + 5990). Após os 6 primeiros meses de valor do plano cai para R$ 129,90 pois o material para de ser cobrado na recorrência.
Atenção!
Se os ciclos da recorrência não forem informados, a assinatura continuará a ser cobrada até ser cancelada
Response para criar plano
id
String
Id do plano criado.
status
String
Status do plano que foi criado
description
String
Descrição do plano.
name
String
Nome do plano.
creation_datetime
DateTime
Data de criação do plano.
Excluir Plano
{
var success = function () {
alert('Plano excluído com sucesso. Id: ' + plan_id);
}
var error = function (error) {
updateResult('Código: ' + error.reasonCode + '<br>' + error.reason);
}
checkout.deletePlan(plan_id, success, error);
}Excluir um plano é bem simples, basta apenas passar o id do plano que deseja excluir para o método.
Request para excluir plano
plan_id
String
Id do plano a ser excluído.
Response de excluir plano
codigo_resposta
Int
Representa o código de retorno da exclusão de plano. Para detalhamento dos códigos de retorno consulte a tabela Possíveis códigos de retorno
Fique atento!
Ao excluir um plano, as assinaturas que foram criadas a partir desse plano não são afetadas, elas continuarão sendo cobradas até o termino do período da recorrência.
Listar Planos
//Request de getPlans
{
var success = function (response) {
updateResult(response);
};
var error = function (error) {
updateResult('Código: ' + error.reasonCode + '<br>' + error.reason);
};
checkout.getPlans(success, error);
}Para se obter todos os planos basta fazer uma requisição sem parâmetros para a função getPlans, com isso será retornado uma array contendo todos os planos criados vinculados aquele checkout.
Response de obter todos os planos
plans
array de planos
Lista contendo todos os planos daquele checkout.
cycles
int
Representa a quantidade de vezes que o cliente será cobrado.
interval_count
int
Intervalo da cobrança. Ex:
plano mensal = interval_count (1) e interval (month)
plano semestral = interval_count (6) e interval (month)
plano anual = interval_count (1) e interval (year)
trial_period_days
int
Período de teste em dias. A assinatura só será cobrada após esse périodo.
description
string
Descrição do plano.
id
string
Id do plano.
interval
string
Periodicidade no qual será feita a cobrança do plano.
Os valores possíveis são week, month ou year
name
string
Nome do plano.
statement_descriptor
string
Texto exibido na fatura do cartão.
status
string
Status do plano.
created_at
DateTime
Data da criação.
deleted_at
DateTime
Data da exclusão.
updated_at
DateTime
Data da última atualização.
items
array de itens
Lista contendo todos os itens do plano. Para mais informações verifique a sessão de Itens do plano
Obter plano por Id
Request para obter apenas um plano
//Request de getPlanById
{
var success = function (response) {
updateResult(response);
};
var error = function (error) {
updateResult('Código: ' + error.reasonCode + '<br>' + error.reason);
};
checkout.getPlanById({ planId: planId }, success, error);
}plan_id
String
Sim
Id do plano a ser excluido.
Response para obter apenas um plano
plan
Plano
Objeto do tipo plano. Para mais informações veja Objeto Plano
Itens do plano
Os itens do plano são a representação dos produtos e serviços oferecidos no plano. Um plano pode ter diversos itens e a soma dos valores deses itens resultam no valor total do plano.
name
String
Nome
description
String
Descrição do item.
quantity
Int
Quantidade
cycles
Int
Ciclos de cobrança. Ex: 1 ciclo representa um item que será cobrado apenas uma vez
price
Int
Valor do item em centavos. Ex. 5990 equivale a R$59,90
Importante!
Ao incluir ou excluir um item do plano, as assinaturas ativas que foram criadas a partir desse plano não são afetadas, o valor delas continuará o mesmo do plano original que ela foi criada. Consulte a sessão incluir item na assinatura para incluir um item em uma assinatura ativa.
Adicionar item
Para incluir um item em um plano é necessário chamar o método passando o id do plano no qual ele será inserido junto com o item que será incluído.
//Request de getPlanById
{
var success = function (response) {
updateResult(response);
};
var error = function (error) {
updateResult('Código: ' + error.reasonCode + '<br>' + error.reason);
};
checkout.getPlanById({ planId: planId }, success, error);
}Request para incluir um item no plano
plan_id
String
Sim
Id do plano.
item
Item do plano
Sim
Item a ser incluído. Ver item do plano
Response de incluir um item no plano
item_id
String
Sim
Id do item que foi incluído.
Remover item
{
var request = {
plan_id: "pln_N6d8RyrhX5FL9n17",
item_id: "si_qvreq6UJncLBNQk0"
};
var success = function (response) {
updateResult('Item removido com sucesso!');
console.log(response);
};
var error = function (error) {
updateResult('Código: ' + error.reasonCode + '<br>' + error.reason);
};
checkout.removePlanItem(request, success, error);
}
Remover um item de um plano é bem simples, basta informar o id do plano que o item deve ser removido e o id do item a ser removido.
Request para excluir plano
plan_id
String
Sim
Id do plano.
itemId
String
Sim
Id do item a ser excluido.
Response de excluir plano
codigo_resposta
Int
Representa o código de retorno da exclusão de plano. Para detalhamento dos códigos de retorno consulte a tabela Possíveis códigos de retorno
Assinatura
Criar assinatura
var request = {
plan_id: "plan_82j19pMCzsy3axdv",
start_date: "2017-07-21T12:15:11Z",
customer: {
name: "Carlos Alberto de Nobrega",
email: "carlos.nobrega@gmail.com"
}
};
var onRecurrencySuccess = function (response) {
console.log(response);
};
var onRecurrencyDenied = function (error) {
updateResult('Código: ' + error.reasonCode + '<br>' + error.reason);
};
checkout.createSubscription(request, onRecurrencySuccess, onRecurrencyDenied);Para criar uma assinatura é necessário ter no mínimo um plano já criado na sua conta. Para detalhamento sobre como criar um plano consulte a sessão de Planos.
Com o plano já criado, basta chamar o método e informar o id do plano no qual a assinatura será vinculada, a data do início da recorrência, as informações do cliente que está assinando o plano. Após enviar essas informações o CapptaGpPlus irá fazer uma chamada para o pinpad pegar as informações do cartão que será utilizado naquela assinatura.
Quando a assinatura for finalizada com sucesso será retornado algumas informações como id da assinatura criada, status e data de criação além disso será enviado um comprovante contendo os detalhes da assinatura, plano, valores para ser entregue ao cliente.
Request para criar assinatura
plan_id
String
Sim
Id do plano. Para detalhamento sobre planos consulte a sessão de Planos
start_date
DateTime
Sim
Data que será iniciado a cobrança do plano.
customer
Customer
Sim
Cliente que está assinando o plano.
Customer
name
String
Sim
Nome do cliente.
String
Não
Email.
Response após criar assinatura
id
String
Id da assinatura criada.
status
String
Data que será iniciado a cobrança do plano
created_at
DateTime
data da criação da assinatura
Cancelar assinatura
var request = {
subscriptionId: subscriptionId,
cancel_pending_invoices: true
};
var success = function () {
alert('Assinatura cancelada com sucesso!');
};
var error = function (error) {
updateResult('Código: ' + error.reasonCode + '<br>' + error.reason);
};
checkout.cancelSubscription(request, success, error);
Para cancelar uma assinatura basta chamar o método passando o id da assinatura que será cancelada e se deseja cancelar também as faturas pendentes, para mais informações sobre faturas clique aqui
Request para cancelar uma assinatura:
subscription_id
String
Sim
Id da assinatura a ser cancelada.
cancel_pending_invoices
Bool
Não
Indica se as faturas pendentes devem ser canceladas, se nenhum valor for informado o padrão será false
codigo_resposta
Int
Representa o código de retorno da exclusão de plano. Para detalhamento dos códigos de retorno consulte a tabela Possíveis códigos de retorno
Editar cartão da assinatura
{
var request = {
subscription_id: document.getElementById('subscription_id').value
}
};
var success = function (response) {
updateResult('Cartão atualizado com sucesso!');
console.log(response);
};
var error = function (error) {
updateResult('Código: ' + error.reasonCode + '<br>' + error.reason);
};
checkout.updateSubscriptionCard(request, success, error);
}
Durante o período da assinatura é possível alterar o cartão no qual a assinatura é cobrada, para isso é preciso fazer uma chamada para o método updateSubscriptionCard passando o ID da assinatura que deve ser atualizada, após isso, o CapptaGpPlus irá fazer uma chamada para o pinpad pegar as informações do novo cartão que será utilizado naquela assinatura.
Request para atualizar cartão da assinatura
subscription_id
String
Sim
Id da assinatura
Response de cancelar uma assinatura
codigo_resposta
Int
Representa o código de retorno da exclusão de plano. Para detalhamento dos códigos de retorno consulte a tabela Possíveis códigos de retorno
Editar data de cobrança da assinatura
{
var request = {
subscription_id: document.getElementById('subscription_id').value,
next_billing_date: "2017-09-20T18:25:40Z"
};
var success = function (response) {
updateResult('Data da próxima cobrança atualizada com sucesso!');
console.log(response);
};
var error = function (error) {
updateResult('Código: ' + error.reasonCode + '<br>' + error.reason);
};
checkout.updateSubscriptionBillingDate(request, success, error);
}Assim como o cartão de cobrança, também é possível alterar a data de de cobrança da assinatura, para isso é preciso fazer uma chamada para o método updateSubscriptionBillingDate passando o ID da assinatura que será alterada e a nova data de cobrança.
Request para atualizar a data de cobrança da assinatura
subscription_id
String
Sim
Id da assinatura.
next_billing_date
DateTime
Sim
Nova data de cobrança da assinatura
Response de cancelar uma assinatura
codigo_resposta
Int
Representa o código de retorno da exclusão de plano. Para detalhamento dos códigos de retorno consulte a tabela Possíveis códigos de retorno
Listar assinaturas
{
var success = function (response) {
updateResult('Assinaturas obtidas com sucesso! Total: ' + response.length);
console.log(response);
};
var error = function (error) {
updateResult('Código: ' + error.reasonCode + '<br>' + error.reason);
};
checkout.getSubscriptions(success, error);Para obter uma lista com todas as assinaturas é necessário fazer uma requisição sem parâmetros para a função getSubscriptions, fazendo isso será retornado uma array contendo todas as assinaturas vinculadas aquele checkout.
Response de obter todos as assinaturas
subscriptions
array de subscriptions
Lista contendo assinaturas
interval_count
int
Intervalo da cobrança. Ex:
plano mensal = interval_count (1) e interval (month)
plano semestral = interval_count (6) e interval (month)
plano anual = interval_count (1) e interval (year)
id
string
Id da assinatura.
interval
string
Periodicidade no qual será feita a cobrança do plano.
Os valores possíveis são week, month ou year
statement_descriptor
string
Texto exibido na fatura do cartão.
status
string
Status da assinatura.
canceled_at
DateTime
Data de cancelamento.
created_at
DateTime
Data de criação.
next_billing_at
DateTime
Data da próxima cobrança.
start_at
DateTime
Data de início da assinatura.
updated_at
DateTime
Data da última atualização
credit_card
CreditCard
Objeto do tipo cartão de crédito. Para saber mais verifique a sessão CreditCard
customer
Customer
Objeto do tipo customer. Para saber mais verifique a sessão Customer
discounts
array de Desconto
Lista de descontos da assinatura. Para saber mais verifique a sessão Descontos da assinatura
items
array de Item
Lista de itens da assinatura. Para saber mais verifique a sessão Itens da assinatura
Obter assinatura por Id
{
var success = function (response) {
updateResult(response);
console.log(response);
};
var error = function (error) {
updateResult('Código: ' + error.reasonCode + '<br>' + error.reason);
};
checkout.getSubscriptionById("sub_N6d8RyrhX5FL9n17", success, error);
}Para obter apenas uma assinatura especifica basta fazer a requisição para a função getSubscriptionsById passando o id da assinatura que deseja consultar.
Request para obter apenas uma assinatura
subscription_id
String
Sim
Id da assinatura.
Response para obter apenas uma assinatura
Assinatura
Objeto assinatura
Ver Objeto Assinatura
Itens da assinatura
Com os itens da assinatura você pode personalizar suas assinaturas deixando elas únicas para atender a necessidade de cada cliente.
name
String
Nome
description
String
Descrição do item.
quantity
Int
Quantidade
cycles
Int
Ciclos de cobrança. Ex: 1 ciclo representa um item que será cobrado apenas uma vez
price
Int
Valor do item em centavos. Ex. 5990 equivale a R$59,90
Adicionar itens na assinatura
{
var request = {
subscription_id: "sub_N6d8RyrhX5FL9n17",
value: 3990,
cycles: 4,
description: "Aula adicional de reforço"
};
var success = function (response) {
updateResult('Item criado com sucesso!');
console.log(response);
};
var error = function (error) {
updateResult('Código: ' + error.reasonCode + '<br>' + error.reason);
};
checkout.createSubscriptionItem(request, success, error);
}
Para adicionar um item a assinatura basta indicar em qual assinatura aquele item deverá ser adicionado, isso é feito passando o subscriptionId e o item a ser adicionado.
Request para incluir um item na assinatura
subscriptionId
String
Sim
Id da assinatura.
item
Item da assinatura
Sim
Item a ser incluído. Ver item da assinatura
Response de incluir um item no plano
subscriptionItemId
String
Sim
Id do item que foi incluído.
Remover item da assinatura
Remover um item de um assinatura é bem simples, basta informar o ID da assinatura que o item deve ser removido e o ID do item a ser removido.
{
var request = {
subscription_id: "sub_N6d8RyrhX5FL9n17",
item_id: "si_qvreq6UJncLBNQk0"
};
var success = function (response) {
updateResult('Item removido com sucesso!');
console.log(response);
};
var error = function (error) {
updateResult('Código: ' + error.reasonCode + '<br>' + error.reason);
};
checkout.removeSubscriptionItem(request, success, error);
}
subscription_id
String
Sim
Id da assinatura.
item_id
String
Sim
Id do item a ser excluído.
codigo_resposta
Int
Representa o código de retorno da exclusão de plano. Para detalhamento dos códigos de retorno consulte a tabela Possíveis códigos de retorno
Desconto da assinatura
Assim como os itens da assinatura, os descontos ajudam a personalizar uma assinatura. Os descontos podem ser de duas maneiras:
Flat: Representa o desconto com valor fixo, nesse tipo de desconto o valor informado será exatamente o descontado da assinatura.
Percentage: Representa o desconto com valor variável, nesse tipo de desconto é informado a porcentagem de desconto que deseja incluir na assinatura e o valor descontado variará de acordo com o valor da fatura.
Desconto da assinatura:
subcriptionId
String
Id da assinatura.
value
int
Valor a ser descontado.
discountType
String
Tipo de desconto a ser aplicado. Os valores possíveis são flat ou percentage.
cycles
Int
Ciclos de cobrança. Ex: 1 ciclo representa um item que será cobrado apenas uma vez
Adicionar desconto na assinatura
{
var request = {
subscription_id: "sub_N6d8RyrhX5FL9n17",
value: 10,
cycles: 12,
discount_type: "percentage"
};
var success = function (response) {
updateResult('Desconto criado com sucesso!');
console.log(response);
};
var error = function (error) {
updateResult('Código: ' + error.reasonCode + '<br>' + error.reason);
};
checkout.createSubscriptionDiscount(request, success, error);
}
subscriptionId
String
Sim
Id da assinatura.
codigo_resposta
Int
Representa o código de retorno da exclusão de plano. Para detalhamento dos códigos de retorno consulte a tabela Possíveis códigos de retorno
Para adicionar um desconto a uma assinatura basta informar o <trong>subscriptionId , este deve ser inserido e enviar um objeto desconto.
Remover desconto da assinatura
Remover um desconto de uma assinatura é bem simples, basta informar o id da assinatura que o desconto deve ser removido e o id do desconto a ser removido
{
var request = {
subscription_id: "sub_N6d8RyrhX5FL9n17",
discount_id: "dis_brMgW6KCdmf2dEQ7"
};
var success = function (response) {
updateResult('Desconto removido com sucesso!');
console.log(response);
};
var error = function (error) {
updateResult('Código: ' + error.reasonCode + '<br>' + error.reason);
};
checkout.removeSubscriptionDiscount(request, success, error);
}
subscriptionId
String
Sim
Id da assinatura.
DiscountId
String
Sim
Id do item a ser excluído.
codigo_resposta
Int
Representa o código de retorno da exclusão de plano. Para detalhamento dos códigos de retorno consulte a tabela Possíveis códigos de retorno
Fatura
Fatura é como cobraremos o cliente de forma recorrente, a cada ciclo da assinatura é gerada uma fatura.
amount
Int
Valor da fatura.
id
int
Id da fatura.
acquirer_affiliation_code
String
Código de afiliação do estabelecimento na adquirente.
acquirer_authorization_code
String
Código de autorização.
acquirer_unique_sequential_number
String
Número Sequencial Único.
acquirer_name
String
Nome da adquirente.
card_brand_name
String
Nome da bandeira do cartão.
merchant_cnpj
String
CNPJ da loja.
status
String
Status da fatura, os valores possíveis são pending, paid, canceled, scheduled ou failed.
statement_descriptor
String
Texto exibido na fatura do cartão.
created_at
DateTime
Data de criação da fatura.
due_at
DateTime
Data de vencimento da fatura.
updated_at
DateTime
Data da ultima atualização.
customer
DateTime
Cliente que assinou a fatura.
Obter fatura por Id
Para obter uma fatura é preciso fazer uma requisição passando o Id da fatura para o método getInvoiceById.
{
var success = function (response) {
updateResult(message);
console.log(response);
};
var error = function (error) {
updateResult('Código: ' + error.reasonCode + '<br>' + error.reason);
};
checkout.getInvoiceById("in_qBY5VvpuEACaw5bg" , success, error);
}
invoice_id
String
Sim
Id da fatura
Response de excluir um desconto da assinatura:
invoice
Invoce
Objeto do tipo invoice.
Request para obter uma fatura
Listar faturas
{
var success = function (response) {
updateResult('Faturas obtidas com sucesso! Total: ' + response.length);
};
var error = function (error) {
updateResult('Código: ' + error.reasonCode + '<br>' + error.reason);
};
checkout.getInvoices(success, error);
}
Para obter uma lista com todas as faturas é necessário fazer um request para o método getInvoices, o retorno será uma lista contando todas as faturas do checkout.
Response de excluir um desconto da assinatura
invoices
Array de Invoce
Sim
Lista de objetos do tipo invoice
Cancelar fatura
{
var success = function (response) {
updateResult('Fatura estornada com sucesso!');
console.log(response);
};
var error = function (error) {
updateResult('Código: ' + error.reasonCode + '<br>' + error.reason);
};
checkout.cancelInvoice("in_qBY5VvpuEACaw5bg", success, error);
}
Cancelar a fatura de uma assinatura é bem simples, basta chamar o método cancelInvoice informando o id da assinatura que deseja cancelar.
Request para cancelar uma fatura
subscriptionId
String
Sim
Id da assinatura.
DiscountId
String
Sim
Id do item a ser excluído
Response de excluir/ cancelar uma fatura
codigo_resposta
Int
Representa o código de retorno da exclusão de plano. Para detalhamento dos códigos de retorno consulte a tabela
O que é Token de Cartão de Crédito:
A Tokenizção de Cartões de Credito já é comum no mundo online possibilitando as funcionalidades de one-click buy em muitos e-commerce.
A Tokenização consiste na criação de um Token, ou seja, uma string única formada por caracteres, que perite a uma loja física, sem certificação PCI, armazenar e realizar transações sem o cliente precisar passar o cartão novamente.
Criar Token com Transação
Essa função permite realizar uma transação do tipo crédito e criar o token do cartão simultaneamente.
var elInstallmentType = document.getElementById("installmentType");
var installmentType = elInstallmentType.options[elInstallmentType.selectedIndex].value;
var installments = document.getElementById('txtCreditInstallments').value;
var request = {
amount: parseFloat(document.getElementById('txtCreditAmount').value.replace(',', '')),
installments: installments === '' ? 0 : installments,
installmentType: installmentType,
customer: {
name: document.getElementById('txtCustomerName').value,
document: document.getElementById('txtCustomerDocument').value,
email: document.getElementById('txtCustomerEmail').value
}
};
var success = function(response) {
console.log(response.cardTokenDetails.cardToken);
console.log(response.cardTokenDetails.cardBrandName);
console.log(response.response.cardTokenDetails.lastFourDigits);
console.log(response.cardTokenDetails.expMonth);
console.log(response.response.cardTokenDetails.expYear);
console.log(response.response.cardTokenDetails.customer.customerId);
console.log(response.response.cardTokenDetails.customer.document);
console.log(response.response.cardTokenDetails.customer.name);
console.log(response.response.cardTokenDetails.customer.email);
console.log(response.response.cardTokenDetails.expYear);
console.log(response.receipt.merchantReceipt);
console.log(response.receipt.customerReceipt);
};
var error = function(err) {
console.log('Código: ' + err.reasonCode + '<br>' + err.reason);
};
checkout.creditPaymentAndCreateCardToken(request, success, error);Request de pagamento com criação de token
amount
number
Sim
Valor do pagamento.
installments
number
Sim
Determina a quantidade de parcelas do pagamento, caso seja informado 1 a venda será realizada como crédito à vista, caso seja maior que isso será um crédito parcelado. Caso não seja informado o valor default é igual a 1, ou seja, a venda será considerada automaticamente a vista.
installmentsType
Boolean
Somente se installments for maior que 1
Determina a configuração do parcelamento, verifique a tabela Tipos de Parcelamento para consultar os valores possíveis
customer
Objeto Customer
Sim
Objeto do tipo customer contendo as informações do cliente.
Objeto Customer
name
String
Sim
Nome do cliente
document
String
Sim
Numero do documento do cliente
documentType
String
Sim
Tipo do documento. Os valores possíveis são: individual (pessoa física) ou company (pessoa jurídica)
String
Sim
Email do cliente
Após o pagamento é retornado um Callback das operações , junto com isso, também é retornado um objeto do tipo CardTokenDetails contendo as informações do token do cartão utilizado.
Objeto CardTokenDetails
cardToken
String
Identificador único do cartão criado.
cardBrandName
String
Nome da bandeira do cartão do cliente.
lastFourDigits
Int
Quatro últimos dígitos do cartão utilizado.
expMonth
int
Mês de expiração do cartão.
expYear
int
Ano de expiração do cartão
customer
Objeto Customer
Objeto do tipo customer contendo as informações do cliente.
Criar Token
Essa é a função que deve ser chamada para realizar a criação:
var request = {
customer: {
name: document.getElementById('txtCustomerNameTokenCreation').value,
document: document.getElementById('txtCustomerDocumentTokenCreation').value,
documentType: document.getElementById('txtCustomerDocumentTypeTokenCreation').value,
email: document.getElementById('txtCustomerEmailTokenCreation').value
}
};
var success = function(response) {
console.log(response.cardToken);
console.log(response.cardBrandName);
console.log(response.lastFourDigits);
console.log(response.expMonth);
console.log(response.expYear);
console.log(response.customer.customerId);
console.log(response.customer.document);
console.log(response.customer.name);
console.log(response.customer.email);
};
var error = function(err) {
console.log('Código: ' + err.reasonCode + '<br>' + err.reason);
};
checkout.createCardToken(request, success, error);Request de criação de token
customer
Objeto Customer
Sim
Objeto do tipo customer contendo as informações do cliente. Clique aqui para mais informações sobre customer.
Response para criação de token
cardToken
String
Identificador único do cartão criado.
cardBrandName
String
Nome da bandeira do cartão utilizado.
lastFourDigits
Int
Quatro últimos dígitos do cartão utilizado.
expMonth
Int
Mês de expiração do cartão.
expYear
Int
Ano de expiração do cartão
customer
Objeto tipo Customer
Objeto do tipo customer contendo as informações do cliente. Clique aqui para mais informações sobre customer.
Criar Pagamento com Token
var elInstallmentType = document.getElementById("tokenInstallmentType");
var installmentType = elInstallmentType.options[elInstallmentType.selectedIndex].value;
var installments = document.getElementById('txtTokenCreditInstallments').value;
var request = {
amount: document.getElementById("txtTokenAmount").value,
installments: installments === '' ? 0 : installments,
installmentType: installmentType,
cardToken: document.getElementById("txtCardToken").value,
customer: {
externalId: document.getElementById('txtCustomerId').value
}
};
var success = function(response) {
console.log(response.paymentKey);
};
var error = function(err) {
console.log('Código: ' + err.reasonCode + '<br>' + err.reason);
};
checkout.paymentWithToken(request, success, error);amount
number
Sim
Valor do pagamento
installments
number
Sim
Determina a quantidade de parcelas do pagamento, caso seja informado 1 a venda será realizada como crédito à vista, caso seja maior que isso será um crédito parcelado. Caso não seja informado o valor default é igual a 1, ou seja, a venda será considerada automaticamente a vista.
installmentType
number
Sim
Determina a configuração do parcelamento, verifique a tabela Tipos de Parcelamento para consultar os valores possíveis
cardToken
string
Sim
Identificador único do cartão
customer.ExternalId
string
Sim
Identificador do proprietário do cartão
Cancelar Pagamento com Token
Essa requisição deve ser utilizada para realizar o cancelamento de um pagamento realizado através de um token de cartão.
Para realizar a requisição é necessário o paymentKey que a requisição de pagamento retorna.
var request = {
paymentKey: "7e94ded9-1946-43da-b228-b07e07cc6141"
};
var success = function(response) {
console.log(response.paymentKey);
console.log(response.amount);
};
var error = function(err) {
console.log('Código: ' + err.reasonCode + '<br>' + err.reason);
};
checkout.cancelTokenPayment(request, success, error);paymentKey
string
Sim
Chave do pagamento recebido do request de pagamento
O que é a pré-autorização de crédito
O crédito pré-autorizado ou pré-autorização de crédito funciona como um pagamento comum de crédito, porém, em vez do valor ser capturado na hora, ele fica reservado do limite do cartão até realizar a captura do valor final. Isso possibilita ao estabelecimento ter uma garantia de que, após utilizar o serviço, o cliente terá limite disponível para realizar o pagamento.
Portanto temos dois passos distintos para realizar o pagamento:
1. A solicitação do crédito pré-autorizado: É o momento em que o valor estimado do produto/serviço é reservado do limite do cartão do cliente.
2. A captura do crédito pré-autorizado: É o momento no qual é debitado o valor real do produto/serviço utilizado pelo cliente.
Criar crédito pré-autorizado
Para realizar a reserva do limite do cartão é necessário enviar uma requisição para o método createPreAuthorizedCreditPayment passando como parâmetro a quantia que deverá ser reservada do limite do cartão do cliente.
Atenção!
Normalmente uma pré-autorização de crédito possui uma validade, que pode variar em função da adquirente, bandeira e/ou emissor do cartão. Após esse prazo, o limite é liberado.
var request = {
amount: 560;
};
var success = function(response) {
// callback para pre-autorizacao bem sucedida
console.log(response.administrativeCode);
console.log(response.receipt.merchantReceipt);
};
var error = function(response) {
// callback para pre-autorizacao que falhou
console.log(response.reason);
};
checkout.createPreAuthorizedCreditPayment(request, success, error);Requisição utilizada para realizar a solicitação do crédito pré-autorizado.
amount
Sim
number
Valor que deverá ser reservado do limite do cartão.
Retorno do método
Capturar crédito pré-autorizado
Para capturar uma venda pré-autorizada é necessário enviar para o método capturePreAuthorizedCreditPayment o valor que deseja capturar e o administrativeCode que foi retornado do método de criar crédito pré-autorizado
Atenção!
Se o valor de captura for menor que o valor pré-autorizado, o restante do crédito pré-aprovado é liberado no limite do cartão automaticamente.
Requisição utilizada para realizar a captura do crédito pré-autorizado.
var request = {
amount: 480,
administrativeCode: '01020676031';
};
var success = function(response) {
// callback para captura de credito bem sucedidoa
console.log(response.administrativeCode);
console.log(response.receipt.merchantReceipt);
};
var error = function(response) {
// callback para captura que falhou
console.log(response.reason);
};
checkout.capturePreAuthorizedCreditPayment(request, success, error);amount
sim
number
Valor a ser capturado.
administrativeCode
sim
String
Número de controle da transação retornado quando foi criado o crédito pré-autorizado.
Cancelamento de crédito pré-autorizado
Cancelar um crédito pré-autorizado é como cancelar uma venda normal, basta enviar o administrativePassword e o administrativeCode para o método paymentReversal
//Não esqueça de realizar a autenticação aqui \o/
var request = {
administrativePassword: 'cappta',
administrativeCode: '000000000'
};
var success = function(response) {
// callback para cancelamento bem sucedido
console.log(response.administrativeCode);
console.log(response.receipt.merchantReceipt);
};
var error = function(response) {
// callback para cancelamento que falhou
console.log(response.reason);
};
checkout.paymentReversal(request, success, error);Será possível cancelar somente créditos pré-aprovados que não foram capturados.
administrativePassword
Sim
String
Senha para realizar o cancelamento de operações.
administrativeCode
Sim
String
Identificador único para pagamentos, é devolvido quando a transação é autorizada, mas também pode ser consultado no portal de transações Cappta.
O que é MultiLoja
Com a Cappta os clientes podem ter diversos CNPJs vinculados na mesma instalação do CapptaGpPlus e selecionar qual deseja utilizar no momento da venda.
Além de ter diversas lojas vinculadas, o Multi Loja permite ao lojista uma flexibilidade maior sobre suas vendas, possibilitando que ele as direcione para o CNPJ de sua escolha. Automaticamente o valor dessa venda será direcionado ao domicilio bancário do CNPJ selecionado.
Para fazer o cadastro de um ou mais CNPJs o mesmo deve entrar em contato diretamente com a Cappta.
Abaixo estão descritos os métodos necessários para utilizar a função Multi Loja.
Obtendo lista de lojas
O método abaixo é usado para se obter uma lista de todos os CNPJs que estão vinculados a instalação e disponiveis para ativação. Com essa lista você pode exibi-la para que o operador possa selecionar o CNPJ que deseja ativar.
checkout.getCheckouts(success, error)
success
callback
error
callback
Essa função possuí dois callbacks, uma executada em caso de sucesso e a outra em caso de erro. Ao lado pode se conferir o código necessário para se exibir todos as lojas em um combo chamado checkouList .
function getCheckouts() {
var success = function (response) {
var combo = document.getElementById("checkoutList");
checkouts = response.checkouts;
response.checkouts.map(function (checkout) {
var option = document.createElement("option");
option.text = checkout.MerchantCnpj;
option.value = checkout.MerchantCnpj;
combo.add(option, null);
});
};
var error = function (response) {
updateResult(response.reason);
};
checkout.getCheckouts(success, error);
}Ativando uma loja
Após o operador selecionar a loja desejada, ele deve usar a função abaixo para ativá-la. Após essa função ser chamada, todas as transações, reimpressões e estornos serão referentes ao CNPJ ativo.
checkout.setCheckout(cnpj, success, error)
cnpj
String
success
Callback
error
Callback
O exemplo ao lado mostra o código necessário para setar uma loja com o valor do cnpj obtido de um combo chamado checkoutList.
function setCheckout() {
var success = function (response, cnpj) {
console.log("PDV ativado com sucesso");
};
var error = function (response) {
console.log(response);
};
var cnpj = document.getElementById("checkoutList").value;
checkout.setCheckout(cnpj, success, error);
}Callbacks
Cada uma das operações do Multiloja possui dois callbacks sendo um para casos de sucesso e outro para casos de erro.
Exemplo de callback de sucesso
var success = function(response) {
//Código que será executado em caso de sucesso
}
O objeto response neste caso conterá uma lista de lojas ou checkouts cada um com as seguintes propriedades:
CheckoutId
int
TradingName
string
MerchantCnpj
string
CheckoutNumber
int
Exemplo de callback de erro
var error = function(response) {
//Código que será executado em caso de erro
}
O objeto response neste caso contém as mesmas propriedades descritas aqui
Exemplo do callback de sucesso
var success = function(response, cnpj) {
//Código que será executado no caso de sucesso
}
O objeto reponse será um objeto de SuccessResponse vazio, e o objeto CNPJ estará preenchido com o cnpj da loja a escolhida para ser ativada
Exemplo do callback de erro
var error = function(response) {
//Código que será executado no caso de erro
}
O objeto response neste caso contém as mesmas propriedades descritas aqui