Gerar assinatura

Como funciona

O checkout transparente de assinatura é um modelo de integração no qual a assinatura é totalmente realizada em seu site, eliminando redirecionamentos para páginas intermediárias de terceiros. É simples e fácil de integrar!

Se você possui um site de vendas de serviços, a Gerencianet recomenda que você utilize o checkout transparente de assinatura para potencializar suas vendas.

Seu cliente
  1. Você adiciona o javascript do checkout transparente em seu HTML e aplica a API HTML;
  2. Os dados de cartão de crédito são enviados diretamente para a Gerencianet;
  3. Seu sistema envia as outras informações de pagamento em formato XML;
  4. A Gerencianet processa as informações e executa o pagamento, retornando um identificador e os dados concernentes à forma de pagamento escolhida;

Como integrar

  1. Acesse o menu Desenvolvedor/Checkout de Assinaturas em sua conta Gerencianet.
  2. Copie o código referente a API Javascript e cole na página final do seu checkout onde seu cliente informa os dados do cartão de crédito.
  3. Adicione os atributos da API HTML em seu html e envie os dados do cliente para seu backend.
  4. Com todos os dados em seu servidor você deve utilizar nossa API Backend do checkout de assinaturas para enviar o XML dos dados do cliente, seu token de integração e o token de pagamento para a Gerencianet. Se utiliza PHP, você poderá usar a biblioteca auxiliar PHP da API Backend para facilitar a comunicação.

API Javascript

A API Javascript é responsável por fornecer acesso à API HTML, interpretar suas funções de callback, requisitar as bandeiras de cartão e submeter os dados criptografados do cartão de crédito de seu cliente diretamente para Gerencianet. A API Javascript da Gerencianet pode ser adquirida no menu Desenvolvedor/Checkout de Assinaturas. Copie o código exibido e cole na etapa onde as bandeiras de cartão de crédito serão selecionadas pelo seu cliente.

Atenção: o código deverá ser colocado na página onde as bandeiras de cartão de crédito serão selecionadas.

API HTML

Esta API utiliza atributos colocados em campos do seu HTML. A API Javascript da Gerencianet percorrerá o HTML à procura destes atributos e se encontrados eles serão enviados ao seu servidor no momento do pagamento.

Todos os atributos utilizados (exceto os dados de cartão de crédito) serão enviados para o endereço especificado dentro do atributo action de seu formulário. Outros inputs que possuem o atributo name também serão enviados para o seu servidor. Clique no botão exibir tabela de atributos para exibir a lista de atributos com uma explicação detalhada de sua funcionalidade.

Pode ser utilizado em Obrigatório Parâmetros Descrição
data-gn-logo
span ou div não Não possui Se deseja informar seus clientes que o meio de pagamento utilizado é a Gerencianet você poderá utilizar este atributo para exibir a logo. Você também poderá estiliza-lo utilizando a classe gn-logo.
data-gn-total
input, select sim Não possui Deve ser colocado no campo onde o total da compra (incluindo desconto, tarifas, quantidades dos itens, etc) é inserido. O valor deste campo deve ser inteiro.
Obs.:Se o valor total não puder ser modificado pelo usuário ele pode ser colocado em um input do tipo 'hidden'.
data-gn-submit
form sim Aceita os parâmetros opcionais: 'sync' e 'async' indicando se a requisição deve ser feita de modo síncrono ou assíncrono respectivamente. Deve ser colocado na tag form do formulário que será submetido ao servidor. A utilização do atributo action também se faz necessária neste caso. Este atributo é identificado pela API Javascript para interceptar o submit do formulário. Se deseja submeter o formulário manualmente você poderá chamar a função abaixo que enviará o formulário com o atributo data-gn-submit.
$gn.submit()
data-gn-callback-sucesso
No mesmo form do atributo data-gn-submit sim Nome da função que deve ser executada em caso de sucesso. Deve ser colocado na tag form do formulário que será submetido ao servidor. Este atributo indica a função javascript que deve ser executada se houver sucesso na requisição ao seu servidor. A função especificada deverá aceitar como parâmetro a resposta enviada pelo seu servidor.
data-gn-callback-erro
No mesmo form do atributo data-gn-submit não Nome da função que deve ser executada em caso de erro. Deve ser colocado na tag form do formulário que será submetido ao servidor. Esta tag indica a função javascript que deve ser executada se houver erro na requisição que envia os dados do cartão de crédito de seu cliente diretamente a Gerencianet e também é responsável por tratar erros de requisição ao seu servidor após submeter o formulário. A função especificada deverá receber um parâmetro para interpretar a resposta de erro enviada.
data-gn-cliente-nome
input não Não possui. Deve ser colocado no campo onde o cliente final coloca o nome. Se no seu site não houver um campo separado para o sobrenome, esta tag deve conter o nome completo do seu cliente final.
data-gn-cliente-sobrenome
input não Não possui. Deve ser colocado no campo onde o cliente final coloca o sobrenome. Deve ser colocada no site em conjunto com o atributo data-gn-cliente-nome.
data-gn-cliente-cpf
input não Não possui. Deve ser colocado no campo onde o cliente final informa o CPF.
data-gn-cliente-nascimento
input, select não Não possui. Deve ser colocado no campo onde o cliente final informa o nascimento no formato dd/mm/YYYY.
data-gn-cliente-email
input não Não possui. Deve ser colocado no campo onde o cliente final informa o email.
data-gn-cliente-celular
input não Não possui. Deve ser colocado no campo onde o cliente final informa o número celular com DDD.
data-gn-endereco-entrega-logradouro
input, textarea não Não possui. Deve ser colocado no campo onde o cliente final informa o logradouro do endereço de entrega.
data-gn-endereco-entrega-numero
input, textarea não Não possui. Deve ser colocado no campo onde o cliente final informa o número do endereço de entrega.
data-gn-endereco-entrega-complemento
input, textarea não Não possui. Deve ser colocado no campo onde o cliente final informa o complemento do endereço de entrega.
data-gn-endereco-entrega-bairro
input, textarea não Não possui. Deve ser colocado no campo onde o cliente final informa o bairro do endereço de entrega.
data-gn-endereco-entrega-cidade
input, select não Não possui. Deve ser colocado no campo onde o cliente final informa a cidade do endereço de entrega.
data-gn-endereco-entrega-cep
input não Não possui. Deve ser colocado no campo onde o cliente final informa o CEP do endereço de entrega.
data-gn-endereco-entrega-estado
input, select não Não possui. Deve ser colocado no campo onde o cliente final informa o estado do endereço de entrega no formato de sigla. Ex.: MG
data-gn-cartao
Qualquer tag sim Não possui. Deve ser colocado em qualquer tag html. Esta tag é responsável por criar a opção de cartão de crédito.
data-gn-cartao-bandeiras
Qualquer tag filha de onde foi colocado o atributo data-gn-cartao sim Os parâmetros possíveis são: 'radio', 'radio-imagem', 'radio-nome' e 'select'. A primeira cria as opções de formas de pagamento como radio buttons com o nome e a imagem da bandeira, a segunda cria como radio buttons mostrando apenas a imagem da bandeira, a terceira cria radio buttons apenas com o nome da bandeira do cartão e a última cria as bandeiras de cartão como selects. Deve ser colocado em qualquer tag html. Esta tag é responsável por mostrar as bandeiras de cartão de crédito.
data-gn-cartao-numero
input sim Não possui. Deve ser colocado no campo onde o cliente final informa o número do cartão de crédito.
data-gn-cartao-mes
input, select sim Não possui. Deve ser colocado no campo onde o cliente final informa o mês de vencimento do cartão de crédito no formato 'mm'. Ex.: 02
data-gn-cartao-ano
input, select sim Não possui. Deve ser colocado no campo onde o cliente final informa o ano de vencimento do cartão de crédito no formato 'YYYY'. Ex.: 2014
data-gn-cartao-codigoSeguranca
input sim Não possui. Deve ser colocado no campo onde o cliente final informa o código de segurança do cartão de crédito.
data-gn-endereco-cobranca-logradouro
input, textarea não Não possui. Deve ser colocado no campo onde o cliente final informa o logradouro do endereço de cobrança.
data-gn-endereco-cobranca-numero
input, textarea não Não possui. Deve ser colocado no campo onde o cliente final informa o número do endereço de cobrança.
data-gn-endereco-cobranca-complemento
input, textarea não Não possui. Deve ser colocado no campo onde o cliente final informa o complemento do endereço de cobrança.
data-gn-endereco-cobranca-bairro
input, textarea não Não possui. Deve ser colocado no campo onde o cliente final informa o bairro do endereço de cobrança.
data-gn-endereco-cobranca-cidade
input, select não Não possui. Deve ser colocado no campo onde o cliente final informa a cidade do endereço de cobrança.
data-gn-endereco-cobranca-cep
input não Não possui. Deve ser colocado no campo onde o cliente final informa o CEP do endereço de cobrança.
data-gn-endereco-cobranca-estado
input, select não Não possui. Deve ser colocado no campo onde o cliente final informa o estado do endereço de cobrança no formato de sigla. Ex.: MG
Voltar para o topo da tabela

Estilizando elementos HTML

A API HTML permite que você estilize os códigos html gerados automaticamente pela API Javascript. A tabela a seguir exibe os ids e classes para facilitar a estilização.

ID Classe Atribuido na Tag Descrição
gn-cartao-bandeiras gn-cartao-bandeiras select ou div (com radios buttons) Permite estilizar as bandeiras retornadas pela API Javascript da Gerencianet.

Obs.: se o estilo das bandeiras forem radio buttons então o id e classe serão aplicados na div-pai desses inputs.

Recebendo POST da API HTML

Após a submissão do formulário, os dados serão recebidos em seu servidor na forma de POST. Juntamente com os dados informados em seu formulário, o seu servidor receberá o token de pagamento do cliente.

A estrutura do POST é elaborada pela API Javascript com base nos atributos existentes em seu HTML. O exemplo abaixo exibe uma estrutura completa em que todos os atributos da API HTML foram utilizados.

Atenção: os campos referentes a cartão de crédito (número, mês, ano, código de segurança e bandeira) serão enviados diretamente a Gerencianet.
POST http://seu_dominio.com.br/action_do_seu_formulario HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=utf-8

Array
(
    #token de pagamento do cliente que deverá ser enviado junto
    #dos dados de pagamento e do seu token de integração
    [tokenPagamento] => token_de_pagamento_do_cliente

    #dados do cliente que está pagando
    [cliente] => Array
        (
            [nome] => Comprador
            [sobrenome] => de Teste
            [cpf] => 99999999999
            [email] => comprador@email.com
            [nascimento] => 2010-02-20
            [celular] => 3199999999
        )

    #endereço de entrega do cliente
    [enderecoEntrega] => Array
        (
            [logradouro] => RUA EXEMPLO
            [numero] => 321
            [complemento] => TRABALHO
            [bairro] => BAIRRO EXEMPLO
            [cidade] => EXEMPLO
            [cep] => 99000000
            [estado] => MG
        )


    [enderecoCobranca] => Array
        (
            [logradouro] => RUA EXEMPLO
            [numero] => 321
            [complemento] => TRABALHO
            [bairro] => BAIRRO EXEMPLO
            [cidade] => EXEMPLO
            [cep] => 99000000
            [estado] => MG
        )

    #outros inputs presentes dentro do formulário
    #somente serão listados os inputs que possuem o atributo "name"
    [outros] => Array
        (
            [descricao] => Produto de teste
            [valor] => 6500
            [quantidade] => 1
            [frete] => 1000
            [desconto] => 100
        )
)

Token de integração

O token de integração é uma espécie de senha. Ele é solicitado em todas as requisições da API de pagamentos. É importante que você não divulgue seu token de integração. Caso isto aconteça, a Gerencianet recomenda que você gere um novo.

Para gerar um token de integração acesse sua conta Gerencianet e clique em Desenvolvedor e, em seguida, Token de integração.

Consumindo a API Backend

Após o recebimento dos dados, você deverá enviar à Gerencianet o seu token de integração, o token de pagamento do cliente (recebido no POST de seu formulário) e um XML contendo os dados do pagamento.

POST https://go.gerencianet.com.br/api/checkout/assinatura/pagar/xml HTTP/1.1
Content-Type: multipart/form-data; charset=utf-8

token=token_de_integracao
tokenPagamento=token_de_pagamento_do_cliente
dados=seu_xml

Ambiente de testes API Backend

Para realizar testes na API de pagamentos, basta enviar a requisição para o ambiente de testes localizado em:

POST https://go.gerencianet.com.br/teste/api/checkout/assinatura/pagar/xml HTTP/1.1
Content-Type: multipart/form-data; charset=utf-8

token=token_de_integracao
tokenPagamento=token_de_pagamento_do_cliente
dados=seu_xml

Requisições enviadas ao ambiente de testes NÃO GERAM PAGAMENTOS VÁLIDOS em sua conta.

Exemplo dos dados em formato XML

A seguir você encontra um exemplo de como os dados devem ser organizados no formato XML.

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <integracao>
  3. <itens>
  4. <item>
  5. <itemDescricao>TV por assinatura</itemDescricao>
  6. <itemValor>50000</itemValor>
  7. </item>
  8. <item>
  9. <itemDescricao>Pacote extra de canais</itemDescricao>
  10. <itemValor>2000</itemValor>
  11. <itemQuantidade>2</itemQuantidade>
  12. </item>
  13. </itens>
  14. <retorno>
  15. <identificador>TVASS001</identificador>
  16. <urlNotificacao>http://minhaloja.com.br/notificacao</urlNotificacao>
  17. </retorno>
  18. <periodicidade>1</periodicidade>
  19. <ocorrencias>12</ocorrencias>
  20. <desconto>100</desconto>
  21. <cliente>
  22. <nome>Nome do cliente</nome>
  23. <cpf>99999999999</cpf>
  24. <email>emaildocliente@email.com</email>
  25. <nascimento>1970-01-01</nascimento>
  26. <celular>3199999999</celular>
  27. </cliente>
  28. <enderecoEntrega>
  29. <logradouro>Rua exemplo</logradouro>
  30. <numero>231</numero>
  31. <bairro>Bairro Exemplo</bairro>
  32. <cidade>Cidade Exemplo</cidade>
  33. <cep>99000000</cep>
  34. <estado>MG</estado>
  35. <complemento>Casa</complemento>
  36. </enderecoEntrega>
  37. <enderecoCobranca>
  38. <logradouro>Rua exemplo</logradouro>
  39. <numero>123</numero>
  40. <complemento>casa</complemento>
  41. <bairro>Bairro exemplo</bairro>
  42. <cidade>Cidade Exemplo</cidade>
  43. <estado>MG</estado>
  44. <cep>99000000</cep>
  45. </enderecoCobranca>
  46. </integracao>

Descrição dos parâmetros de entrada

A seguir você encontra a descrição detalhada de cada parâmetro de entrada do formato XML.

Tag Obrigatória Descrição
itens sim Tag que engloba os itens envolvidos na transação.
item sim Tag que engloba os dados dos itens envolvidos na transação.
itemValor sim

Valor, em centavos, do item envolvido na transação. Este campo deve conter apenas números.

Por exemplo, se o item custa R$99,00, o valor deverá ser “9900”.

itemDescricao sim Descrição do item envolvido na transação.
itemQuantidade não Quantidade do item envolvido na transação. Se não enviado, será considerado quantidade igual a 1.
retorno não Tag que engloba os dados do seu sistema como: URL de redirecionamento após pagamento, seu identificador para a transação, etc.
identificador não Identificador personalizado que referencia a transação em seu sistema. Esta informação poderá ser utilizada no web service de notificações.
urlNotificacao não URL para recebimento de notificações referentes ao pagamento.
periodicidade sim Periodicidade da assinatura. Deve ser enviado um número inteiro como indicado a seguir:
  • 1 - indica que a cobrança será efetuada mensalmente
  • 2 - indica que a cobrança será efetuada bimestralmente
  • 3 - indica que a cobrança será efetuada trimestralmente
  • 6 - indica que a cobrança será efetuada semestralmente
  • 12- indica que a cobrança será efetuada anualmente
ocorrencias não Número de vezes que a cobrança será realizada.

Exemplo: se a periodicidade é igual a 1 e o número de ocorrências é igual a 6, a cobrança será efetuada todo mês durante os próximos 6 meses.

Importante: Se esta tag não for enviada a cobrança será efetuada indefinidamente até que seja cancelada pelo lojista ou pelo cliente final.

desconto não Valor, em centavos, do desconto. Este campo deve conter apenas números.

Por exemplo, se o desconto foi de R$13,25, o valor deverá ser “1325”.

cliente sim Tag que engloba os dados do cliente envolvido na transação. Não poderá ser repetida.
nome sim Nome do cliente envolvido na transação.
cpf sim CPF do cliente envolvido na transação. Deve conter 11 caracteres (apenas números).
email sim E-mail válido do cliente envolvido na transação.
nascimento sim Data de nascimento do cliente envolvido na transação no formato YYYY-MM-DD, formato oficial do W3C.
celular sim

Número do celular de seu cliente com DDD (apenas números).

Exemplo: 3188888888.

enderecoEntrega não Tag que engloba os dados do endereço de entrega. Não poderá ser repetida.
logradouro sim Logradouro (Rua, Avenida, Praça, etc.) do cliente envolvido na transação. É obrigatório se for enviado a tag endereçoEntrega.
numero sim Número da residência do cliente envolvido na transação. É obrigatório se for enviado a tag enderecoEntrega.
bairro sim Bairro do cliente envolvido na transação. É obrigatório se for enviado a tag endereçoEntrega.
complemento não Complemento do endereço do cliente envolvido na transação.
cidade sim Cidade do cliente envolvido na transação. É obrigatório se for enviado a tag endereçoEntrega.
cep sim CEP do cliente envolvido na transação. Deve conter 8 caracteres (apenas números). É obrigatório se for enviado a tag endereçoEntrega.
estado sim

Estado do cliente envolvido na transação. Deve conter apenas 2 caracteres, representando a sigla do estado. É obrigatório se for enviado a tag endereçoEntrega.

Exemplo: MG

enderecoCobranca sim Tag que engloba os dados do endereço de cobrança. Não poderá ser repetida.
logradouro sim Logradouro (Rua, Avenida, Praça, etc.) do cliente envolvido na transação.
numero sim Número da residência do cliente envolvido na transação.
bairro sim Bairro do cliente envolvido na transação.
complemento não Complemento do endereço do cliente envolvido na transação.
cidade sim Cidade do cliente envolvido na transação.
cep sim CEP do cliente envolvido na transação. Deve conter 8 caracteres (apenas números).
estado sim

Estado do cliente envolvido na transação. Deve conter apenas 2 caracteres, representando a sigla do estado.

Exemplo: MG

Voltar para o topo da tabela

Biblioteca auxiliar PHP da API Backend

A Gerencianet disponibiliza uma classe para ajudar na construção e envio do XML de pagamento. Você pode fazer download aqui. Para utiliza-lá, inclua a classe em seu código PHP e chame o método pagar como o exemplo abaixo:

<?php

require_once "ApiCheckoutAssinaturaGerencianet.php";

...

// $arrayComEstruturaDoXML - Um array que possui a mesma estrutura do XML de entrada.
// $tokenDeIntegracao - Seu token de integracao
// $tokenDePagamento - É token de pagamento enviado para seu backend pela API HTML (ou API Javascript)

$resposta = ApiCheckoutAssinaturaGerencianet::pagar($arrayComEstruturaDoXML, $tokenDeIntegracao, $tokenDePagamento);

A resposta retornada será um XML de sucesso ou de erro que será detalhado logo abaixo.

Resposta em caso de sucesso

Se os dados enviados estiverem corretos, a Gerencianet retornará um identificador para o pagamento na tag transacao. O retorno é realizado em formato XML como no exemplo a seguir:

  1. <?xml version="1.0" encoding="utf-8"?>
  2. <integracao>
  3. <status>2</status>
  4. <resposta>
  5. <transacao>99999</transacao>
  6. <total>3909</total>
  7. <periodicidade>12</quantidadeParcelas>
  8. <ocorrencias>ilimitada</ocorrencias>
  9. <identificador>88888</identificador>
  10. </resposta>
  11. </integracao>

Resposta em caso de erro

Caso ocorra algum erro na requisição à API de pagamentos, a resposta listará todos os erros encontrados como no exemplo a seguir:

  1. <?xml version="1.0" encoding="utf-8"?>
  2. <integracao>
  3. <status>1</status>
  4. <erros>
  5. <codigo>10093</codigo>
  6. <erro>O pagamento deste token de pagamento já foi efetuado.</erro>
  7. </erros>
  8. </integracao>

Códigos de erro mais comuns

Para ver os códigos de erro retornados pela API acesse o link.

Descrição dos parâmetros de saída

Tag Descrição
status Status da requisição. Em caso de sucesso, conterá o valor “2”. Caso ocorra alguma falha, apresentará o valor “1”.
resposta Tag que engloba a resposta enviada pela Gerencianet.
transacao Número da transação gerada pela requisição. Você poderá utilizar este número para consultar os detalhes da transação.
total Retorna o total da compra em inteiro (inclui frete, desconto e taxa de administração de risco).
periodicidade Periodicidade da cobrança em número de meses.
ocorrencias Número de ocorrências da assinatura ou 'ilimitada' (caso a tag ocorrencias não tenha sido enviada no consumo).
identificador Identificador da assinatura no sistema Gerencianet. Este identificador pode ser usado para associar as notificações das cobranças geradas nos meses seguintes à assinatura gerada.
erros Tag que contém os erros ocorridos durante o processo de integração.
codigo Código do erro.
erros Descrição do erro.