CapptaGpPlus Checkout Web

Suggest Edits

Manual de Integração

 

Seja bem vindo, a documentação CapptAPI-Web, qualquer dúvida, sugestão e critica nos mande uma mensagem:

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.

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 este pequeno formulário Homologa Cappta

Conheça também:
Android
DeskTop
Conciliação

O que deseja aprender?

Suggest Edits

Ambiente de testes

 

Versão do CapptaGpPlus

O time de tecnologia da Cappta vela 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

Execute o Instalador como administrador

Utilize a senha, PDV e CNPJ fornecidos

Confirme os dados

Escolha o Pinpad

Configurar o GP

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".

Configurações

No taskbar  click com botão direito e procure a opção configurações.

No taskbar click com botão direito e procure a opção configurações.

Solicite  a senha do dia para nosso time.

Solicite a senha do dia para nosso time.

Com as configurações abertas click na opção TEF

Marque a opção Checkout web

Grave a alteração

Grave a alteração

Suggest Edits

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.

Botão direito sobre o ícone e habilite o Pinpad

Botão direito sobre o ícone e habilite o Pinpad

Para configurar a Integração do checkout Web entre em contato com o time e peça a senha do dia.

Suggest Edits

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.

É 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 ao lado:

Uma forma mais simples

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.

var authenticationRequest = {
    authenticationKey: '2C1CE88C-6A0C-4FA6-BF2D-519B1DB31DF4'  
};
Suggest Edits

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.

Suggest Edits

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:

  1. Após realizar a autenticação será necessário iniciar uma operação de pagamento ou cancelamento.
  2. 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.
  3. 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.

Suggest Edits

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 ao lado

<script type="text/javascript" src="https://s3.amazonaws.com/cappta.api/v2/dist/cappta-checkout.js"></script>
Suggest Edits

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.

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.

Request para autenticação

Parâmetro
Tipo
Descrição

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.

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);
Suggest Edits

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:

Propriedade
Tipo
Descrição

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.

Suggest Edits

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:

Propriedade
Tipo
Descrição

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

Suggest Edits

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.

Propriedade
Tipo
Descrição

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.

Suggest Edits

Pagamento

 

Abaixo serão descritas todas as formas de pagamento disponibilizadas pelo Checkout Cappta.

Suggest Edits

Pagamento Débito / Voucher

 

Para realizar um pagamento débito ou voucher é bem simples, basta informar o valor a ser debitado.

Request para pagamento débito / voucher

Parâmetro
Obrigatório?
Tipo
Descrição

amount

Sim

float

Valor do pagamento

Para detalhamento das funções de sucesso e erro, consulte a sessão de Callback das operações

.

//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);
Suggest Edits

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).

Para detalhamento das funções de sucesso e erro, consulte a sessão de Callback das operações

Request para pagamento crédito

Parâmetro
Obrigatório?
Tipo
Descrição

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

//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);
Suggest Edits

Pagamento Crediário

 

Assim como o pagamento crédito o crediário também necessita de alguns dados a mais para facilitar o seu processamento.

Request para pagamento crediário

Parâmetro
Obrigatório?
Tipo
Descrição

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

//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);
Suggest Edits

Cancelamento de pagamentos

 

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.

Request para cancelamento

Parâmetro
Descrição

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

//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);
Suggest Edits

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:

Callback de sucesso

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:

Propriedade
Tipo
Descrição

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.

Receipt

Propriedade
Tipo
Descrição

customerReceipt

string

Cupom do cliente

merchantReceipt

string

Cupom do lojista

reducedReceipt

string

Cupom reduzido

Callback de erro

Propriedade
Tipo
Descrição

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.

Suggest Edits

Capturando todos os dados da transação

 

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.

Parâmetro
Obrigatório?
Tipo
Descrição

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

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);
Suggest Edits

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.

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:

Parâmetro
Tipo
Descrição

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.

//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);
Suggest Edits

Confirmando ou desfazendo os pagamentos

 

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.

//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();
    }
}

Observações

Existe um limite de no máximo 9 cartões para uma sessão.

Suggest Edits

Solicitando informações pelo Pinpad

 

Utilizando esta função, é possível solicitar informações a serem digitadas no pinpad. As opções consistem em: CPF, Telefone/Celular e senha.

Request para informações do Pinpad

Parâmetro
Obrigatório?
Tipo
Descrição

inputType

Sim

number

Tipo de informação a ser solicitada no pinpad. Consulte a tabela abaixo para os valores.

Tipos de informação

Tipo
Valor
Descrição

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.

Callback de sucesso

Será executado o callback de sucesso logo em que for confirmada a informação no Pinpad:

Propriedade
Tipo
Descrição

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.

//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);
Suggest Edits

Possíveis códigos de retorno

 
Código
Descrição

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.

Suggest Edits

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

Suggest Edits

Tipos de Parcelamento

 
Código
Descrição

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

Suggest Edits

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 plicados, ou permanentes, sendo aplicado a todos os ciclos até o final da recorrência.

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.

Suggest Edits

Criar Plano

 

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

Propriedade
Tipo
Obrigatório
Descrição

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.

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.

Se os ciclos da recorrência não forem informados, a assinatura continuará a ser cobrada até ser cancelada

Response para criar plano

Propiedade
tipo
Descrição

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.

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);

O valor de um plano é definido pela soma dos price de seus itens

Suggest Edits

Excluir Plano

 

Excluir um plano é bem simples, basta apenas passar o id do plano que deseja excluir para o método.

Request para excluir plano

Propiedade
tipo
Descrição

plan_id

String

Id do plano a ser excluído.

Response de excluir plano

Propiedade
tipo
Descrição

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

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.

{
    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);
}
Suggest Edits

Listar Planos

 

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

Propiedade
tipo
Descrição

plans

array de planos

Lista contendo todos os planos daquele checkout.

Objeto Plano

Propiedade
tipo
Descrição

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

//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);
}
Suggest Edits

Obter plano por Id

 

Request para obter apenas um plano

Propiedade
tipo
Obrigatório
Descrição

plan_id

String

Sim

Id do plano a ser excluido.

Response para obter apenas um plano

Propiedade
tipo
Descrição

plan

Plano

Objeto do tipo plano. Para mais informações veja Objeto 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);
}
Suggest Edits

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.

Propiedade
tipo
Descrição

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

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.

Suggest Edits

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

Propiedade
tipo
Obrigatório
Descrição

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

Propiedade
tipo
Obrigatório
Descrição

item_id

String

Sim

Id do item que foi incluído.

Suggest Edits

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

Propiedade
tipo
Obrigatório
Descrição

plan_id

String

Sim

Id do plano.

itemId

String

Sim

Id do item a ser excluido.

Response de excluir plano

Propiedade
tipo
Descrição

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

Suggest Edits

Assinatura

 

Assinatura representa o vínculo entre o cliente final e o plano oferecido pelo lojista, é através dela que o cliente será cobrado de forma recorrente.

Abaixo segue a descrição dos métodos e estruturas necessárias para integrar com as assinaturas.

Suggest Edits

Criar assinatura

 

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

Propiedade
tipo
Obrigatório
Descrição

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

Propiedade
tipo
Obrigatório
Descrição

name

String

Sim

Nome do cliente.

email

String

Não

Email.

Response após criar assinatura

Propiedade
tipo
Descrição

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

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);
Suggest Edits

Cancelar assinatura

 

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

Propiedade
tipo
Obrigatório
Descrição

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

Response de cancelar uma assinatura

Propiedade
tipo
Descrição

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

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);
Suggest Edits

Editar cartão da assinatura

 

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

Propiedade
tipo
Obrigatório
Descrição

subscription_id

String

Sim

Id da assinatura

Response de cancelar uma assinatura

Propiedade
tipo
Descrição

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

{
    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);
}
Suggest Edits

Editar data de cobrança da assinatura

 

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

Propiedade
tipo
Obrigatório
Descrição

subscription_id

String

Sim

Id da assinatura.

next_billing_date

DateTime

Sim

Nova data de cobrança da assinatura

Response de cancelar uma assinatura

Propiedade
tipo
Descrição

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

{
    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);
}
Suggest Edits

Listar assinaturas

 

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

Propiedade
tipo
Descrição

subscriptions

array de subscriptions

Lista contendo assinaturas

Objeto Assinatura

Propiedade
tipo
Descrição

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

{

    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);
Suggest Edits

Obter assinatura por Id

 

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

Propiedade
tipo
Obrigatório
Descrição

subscription_id

String

Sim

Id da assinatura.

Response para obter apenas uma assinatura

Propiedade
tipo
Descrição

Assinatura

Objeto assinatura

Ver Objeto Assinatura

{
    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);
}
Suggest Edits

Itens da assinatura

 

Com os itens da assinatura você pode personalizar suas assinaturas deixando elas únicas para atender a necessidade de cada cliente.

Item da assinatura

Propiedade
tipo
Descrição

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

Suggest Edits

Adicionar itens na assinatura

 

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

Propiedade
tipo
Obrigatório
Descrição

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

Propiedade
tipo
Obrigatório
Descrição

subscriptionItemId

String

Sim

Id do item que foi incluído.

{
    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);
}
Suggest Edits

Remover item da assinatura

 
{    
    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);
}

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.

Request para excluir um item da assinatura

Propiedade
tipo
Obrigatório
Descrição

subscription_id

String

Sim

Id da assinatura.

item_id

String

Sim

Id do item a ser excluído.

Response de excluir um item da assinatura

Propiedade
tipo
Descrição

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

Suggest Edits

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

Propiedade
tipo
Descrição

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

Suggest Edits

Adicionar desconto na assinatura

 

Para adicionar um desconto a uma assinatura basta informar o <trong>subscriptionId , este deve ser inserido e enviar um objeto desconto.

Request para incluir um desconto na assinatura

Propiedade
tipo
Obrigatório
Descrição

subscriptionId

String

Sim

Id da assinatura.

discount

Desconto da assinatura

Sim

Item a ser incluido. Ver desconto da assinatura

Response de incluir um desconto no plano

Propiedade
tipo
Descrição

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

{
    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);
}
Suggest Edits

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

Request para excluir um desconto da assinatura

Propiedade
tipo
Obrigatório
Descrição

subscriptionId

String

Sim

Id da assinatura.

DiscountId

String

Sim

Id do item a ser excluído.

Response de excluir um desconto da assinatura

Propiedade
tipo
Descrição

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

{
    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);
}

Fatura é como cobraremos o cliente de forma recorrente, a cada ciclo da assinatura é gerada uma fatura.

Objeto Invoice

Propiedade
tipo
Descrição

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.

Suggest Edits

Obter fatura por Id

 

Para obter uma fatura é preciso fazer uma requisição passando o Id da fatura para o método getInvoiceById.

Response de excluir um desconto da assinatura

Propiedade
tipo
Obrigatório
Descrição

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

{

    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);
}
Suggest Edits

Listar faturas

 

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

Propiedade
tipo
Obrigatório
Descrição

invoices

Array de Invoce

Sim

Lista de objetos do tipo invoice

{
    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);
}

Suggest Edits

Cancelar fatura

 

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

Propiedade
tipo
Obrigatório
Descrição

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

{
    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);
}


Suggest Edits

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.

Suggest Edits

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.

Request de pagamento com criação de token

Propriedade
Tipo
Obrigatório
Descrição

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

Number

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

Propriedade
Tipo
Obrigatório
Descrição

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)

email

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

Propriedade
Tipo
Descrição

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.

 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);
Suggest Edits

Criar Token

 

Essa é a função que deve ser chamada para realizar a criação:

Request de criação de token

Propriedade
Tipo
Obrigatório
Descrição

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

Propriedade
Tipo
Descrição

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.

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);
Suggest Edits

Criar Pagamento com Token

 
Propriedade
Tipo
Obrigatório
Descreição

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

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);
Suggest Edits

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.

Nome
Tipo
Obrigatório
Descrição

paymentKey

string

Sim

Chave do pagamento recebido do request de pagamento

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);
Suggest Edits

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.

Suggest Edits

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.

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.

Requisição utilizada para realizar a solicitação do crédito pré-autorizado.

Parâmetro
Obrigatório
Tipo
Descrição

amount

Sim

number

Valor que deverá ser reservado do limite do cartão.

Retorno do método

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);
Suggest Edits

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

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.

Parâmetro
Obrigatório
Tipo
Descrição

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.

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);
Suggest Edits

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

Será possível cancelar somente créditos pré-aprovados que não foram capturados.

Request para cancelamento

Parâmetro
Obrigatório
Tipo
Descrição

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.

//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);
Suggest Edits

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.

Suggest Edits

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)

Parâmetro
Tipo

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);
}
Suggest Edits

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)

Parâmetro
Tipo

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);
}
Suggest Edits

Callbacks

 

Cada uma das operações do Multiloja possui dois callbacks sendo um para casos de sucesso e outro para casos de erro.

Callbacks da Operação de Listagem de Lojas

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:

Propriedade
Tipo

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

Callbacks da Operação de Ativação de Loja

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