NAV
JavaScript C# PHP

Manual de Integração com o CapptaGpPlus

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.

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 abaixo demonstra este fluxo:

Fluxo operação pagamento

  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 disponivel 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:

<script type="text/javascript" src="https://s3.amazonaws.com/cappta.api/js/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.

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.

var authenticationRequest = {
    authenticationKey: '795180024C04479982560F61B3C2C06E',
    merchantCnpj: '00000000000000',
    checkoutNumber: 1
};

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

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.

Callback de sucesso

Será executado o callback de sucesso quando a autenticação for bem sucedida, através dele será passado os seguintes paramêtros:

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.

Callback de erro

Será executado o callback de erro quando não for possivel autenticar com o CapptaGpPlus, através dele será passado os seguintes paramêtros:

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

Callback de transações pendentes

Será executado o callback de transações pendentes caso a última sessão de multiplos pagamentos tenha ficado em aberto.

Por exemplo: Foi informada a quantidade de 5 pagamentos para iniciar a sessão de multiplos 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 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

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

Pagamento Débito / Voucher

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

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

Request para pagamento débito / voucher

Parâmetro Obrigatório? Tipo Descrição
amount Sim float Valor do pagamento

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

Request para pagamento crédito

Parâmetro Obrigatório? Tipo Descrição
amount Sim float 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

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

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

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

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.

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

Request para cancelamento

Parâmetro Descrição
administrativePassword Senha solicitada no CapptaGpPlus necessária para liberar o acesso à cancelamentos de pagamentos
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 paramêtro, 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.
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.

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.

GET https://integracao.cappta.com.br/payment/checkoutGuid/administrativeCode

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

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

Inicializando uma sessão de multiplos pagamentos

O multiplos 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 multiplos 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 Multiplos Pagamentos.

Assim que o último pagamento da sessão multiplos pagamentos for autorizado, automaticamente todos os pagamentos serão confirmados, não há necessidade de enviar nenhum comando para isso. A sessão multiplos cartões é representada pelo fluxograma abaixo:

Fluxo multi-cartões

Dentro de uma sessão não será possível realizar cancelamentos e nem reimpressões, para isso será necessário desfazer ou confirmar os pagamentos anteriores para finalizar a sessão multiplos 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);

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.

Confirmando ou desfazendo os pagamentos

Para finalizar uma sessão multiplos 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

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.

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

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
pinpadValue string Informação digitada no Pinpad.

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.

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.

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

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

Um exemplo de plano

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.

Response de 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.

Voltar para 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

Propiedade tipo Descrição
plan_id String Id do plano 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

Voltar para plano

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

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

Obter plano por Id

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

Para retornar apenas um plano basta fazer a requisição para a função getPlanById passando oid do plano que deseja consultar.

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

Voltar para plano

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

Item 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

Voltar para plano

Adicionar item

{
    var request = {
        plan_id: "pln_N6d8RyrhX5FL9n17",
        value: 2990,
        cycles: 6,
        description: "Aula semanal adicional"
    };

    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.createPlanItem(request, success, error);
}

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á incluido.

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

Voltar para plano

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

Voltar para plano

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.

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 entrege 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. Mais detalhes


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

Voltar para 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

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

Voltar para assinatura

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

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

Voltar para assinatura





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 vobranç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

Voltar para assinatura

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

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





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 oid 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

Voltar para assinatura

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

Voltar para assinatura

Adicionar item da 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

Propiedade tipo Obrigatório Descrição
subscriptionId String Sim Id da assinatura.
item Item da assinatura Sim Item a ser incluido. 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 incluido.

Voltar para assinatura

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

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

Voltar para assinatura

Desconto da assinatura

Assim como os itens da assinatura, os descontos ajudam a personalizar uma assinatura. Os descontos podem ser de duas maneiras:

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

Voltar para assinatura

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

Para adicionar um desconto a uma assinatura basta informar o subscriptionId na qual ese 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

Voltar para assinatura

Remover desconto da assinatura

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

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

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

Voltar para assinatura

Fatura

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 ultiama atualização.
customer Customer Cliente que assinou a fatura. Para mais informações veja a sessão de cliente

Obter fatura por Id

{

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

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

Request para obter uma fatura

Propiedade tipo Obrigatório Descrição
invoice_id String Sim Id da fatura.

Response de excluir um desconto da assinatura

Propiedade tipo Descrição
invoice Invoce Objeto do tipo invoice. Para detalhamento sobre invoice clique aqui

Voltar para fatura por Id

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

Propiedade tipo Descrição
invoices Array de Invoce Lista de objetos do tipo invoice. Para detalhamento sobre invoice clique aqui

Voltar para fatura

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

Propiedade tipo Obrigatório Descrição
subscriptionId String Sim Id da assinatura.
DiscountId String Sim Id do item a ser excluido.

Response de excluir cancelar uma fatura

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

Voltar para fatura

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.

Códigos de motivo para operações negadas

Código Descrição
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

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

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 variavel authenticationRequest, logo no inicio do arquivo.

var authenticationRequest = {
    authenticationKey: '2C1CE88C-6A0C-4FA6-BF2D-519B1DB31DF4',
    merchantCnpj: '00000000000000',
    checkoutNumber: 1
};

Os valores a serem inseridos são estes abaixo: