Gerar transação
Como funciona
O checkout transparente é um modelo de integração no qual o pagamento é feito totalmente 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 produtos e/ou serviços, a Gerencianet recomenda que você utilize o checkout transparente para potencializar suas vendas.
- Você adiciona o javascript do checkout transparente em seu HTML e aplica a API HTML;
- Os dados de cartão de crédito são enviados diretamente para a Gerencianet;
- Seu sistema envia as outras informações de pagamento em formato XML;
- A Gerencianet processa as informações e executa o pagamento, retornando um identificador e os dados concernentes à forma de pagamento escolhida;
Como integrar
- Acesse o menu Desenvolvedor/Checkout Transparente em sua conta Gerencianet.
- Copie o código referente a API Javascript e cole na página final do seu checkout onde seu cliente seleciona boleto ou cartão de crédito.
- Adicione os atributos da API HTML em seu html e envie os dados do cliente para seu backend.
- Com todos os dados em seu servidor você deve utilizar nossa API Backend do checkout transparente 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 formas de pagamento 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 Transparente. Copie o código exibido e cole na etapa onde as formas de pagamento serão selecionadas pelo seu cliente.
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 frete, 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-forma-pagamento | |||
Qualquer tag | sim | Os parâmetros possíveis são: 'radio', 'select', 'cartao-credito' e 'boleto'. A primeira cria as opções de formas de pagamento como radio buttons enquanto a segunda cria as opções de formas de pagamento como selects. As duas últimas são para quando se deseja limitar a forma de pagamento, seja ela cartão de crédito ou boleto, respectivamente. | Deve ser colocado em qualquer tag html. Esta tag é responsável por criar as opções de forma de pagamento disponíveis na Gerencianet. |
data-gn-toggle | |||
Na mesma tag do atributo data-gn-forma-pagamento | não | Não possui. | Deve ser colocada na mesma tag do atributo data-gn-forma-pagamento. Este atributo, quando presente, faz com que ao se selecionar uma forma de pagamento a outra esconda. Ex.: Ao selecionar cartão de crédito, todo conteúdo dentro da tag que possui o atributo data-gn-cartao será exibida e o conteúdo dentro de data-gn-boleto será ocultado. |
data-gn-boleto | |||
Qualquer tag | sim | Não possui. | Deve ser colocado em qualquer tag html. Esta tag é responsável por criar a opção de boleto. |
data-gn-boleto-imagem | |||
Qualquer tag filha de onde foi colocado o atributo data-gn-boleto | não | Não possui. | Deve ser colocado em qualquer tag html. Esta tag é responsável por mostrar a bandeira de boleto. |
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-parcelas | |||
Qualquer tag filha de onde foi colocado o atributo data-gn-cartao | sim | Não possui. | Deve ser colocado em qualquer tag html. Esta tag é responsável por mostrar a forma de parcelamento disponível para determinado valor de compra. |
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 |
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-forma-pagamento | gn-forma-pagamento | select ou div (com radios buttons) | Permite estilizar a forma de pagamento (cartão ou boleto).
Obs.: se o estilo da forma de pagamento for radio buttons então o id e classe serão aplicados na div-pai desses inputs. |
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. |
gn-cartao-parcelas | gn-cartao-parcelas | select | Permite estilizar o select box de parcelas retornadas pela API Javascript da Gerencianet |
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.
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 #método de pagamento escolhido (outro valor possível é "boleto") [metodo] => cartao-credito #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 ) #Dependente da forma de pagamento selecionada #este índice só existirá se a forma de pagamento escolhida for cartão [formaPagamento] => Array ( #dados do cartão [cartao] => Array ( [parcelas] => 3 [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/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/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.
- <?xml version="1.0" encoding="UTF-8"?>
- <integracao>
- <itens>
- <item>
- <itemDescricao>Smartphone</itemDescricao>
- <itemValor>50000</itemValor>
- <itemQuantidade>5</itemQuantidade>
- </item>
- </itens>
- <retorno>
- <identificador>SMART001</identificador>
- <urlNotificacao>http://minhaloja.com.br/notificacao</urlNotificacao>
- </retorno>
- <desconto>100</desconto>
- <frete>1200</frete>
- <tipo>produto</tipo>
- <cliente>
- <nome>Nome do cliente</nome>
- <cpf>99999999999</cpf>
- <email>emaildocliente@email.com</email>
- <nascimento>1970-01-01</nascimento>
- <celular>3199999999</celular>
- </cliente>
- <enderecoEntrega>
- <logradouro>Rua exemplo</logradouro>
- <numero>231</numero>
- <bairro>Bairro Exemplo</bairro>
- <cidade>Cidade Exemplo</cidade>
- <cep>99000000</cep>
- <estado>MG</estado>
- <complemento>Casa</complemento>
- </enderecoEntrega>
- <formaPagamento>
- #se for boleto
- <boleto>
- <vencimento>2014-07-18</vencimento>
- </boleto>
- #se for cartão de crédito
- <cartao>
- <parcelas>2</parcelas>
- <enderecoCobranca>
- <logradouro>Rua exemplo</logradouro>
- <numero>123</numero>
- <complemento>casa</complemento>
- <bairro>Bairro exemplo</bairro>
- <cidade>Cidade Exemplo</cidade>
- <estado>MG</estado>
- <cep>99000000</cep>
- </enderecoCobranca>
- </cartao>
- </formaPagamento>
- </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.
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 "ApiCheckoutGerencianet.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 = ApiCheckoutGerencianet::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:
- <?xml version="1.0" encoding="utf-8"?>
- <integracao>
- <status>2</status>
- <resposta>
- <transacao>99999</transacao>
- <total>3750</total>
- <tipo>boleto</tipo>
- <codigoBarra>99999.99999 99999.999999 99999.999999 9 99999999999999</codigoBarra>
- <linkBoleto>link_do_boleto</linkBoleto>
- <vencimentoBoleto>1970-01-01</vencimentoBoleto>
- </resposta>
- </integracao>
Se a forma de pagamento escolhida for cartão de crédito:
- <?xml version="1.0" encoding="utf-8"?>
- <integracao>
- <status>2</status>
- <resposta>
- <transacao>99999</transacao>
- <total>3909</total>
- <tipo>cartao-credito</tipo>
- <quantidadeParcelas>2</quantidadeParcelas>
- <valorDaParcela>1951</valorDaParcela>
- </resposta>
- </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:
- <?xml version="1.0" encoding="utf-8"?>
- <integracao>
- <status>1</status>
- <erros>
- <codigo>10093</codigo>
- <erro>O pagamento deste token de pagamento já foi efetuado.</erro>
- </erros>
- </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). |
tipo | Informa qual a forma de pagamento selecionada pelo cliente. Poderá ser boleto ou cartao-credito. |
codigoBarra | Informa o código de barra do boleto gerado. |
linkBoleto | Exibe o link para acessar o boleto gerado. |
vencimentoBoleto | Data em que o boleto gerado irá vencer. |
quantidadeParcelas | Retorna a quantidade de parcelas selecionada pelo cliente. |
valorDaParcela | Retorna o valor de cada parcela de acordo com a quantidade selecionada pelo cliente. |
erros | Tag que contém os erros ocorridos durante o processo de integração. |
codigo | Código do erro. |
erros | Descrição do erro. |
Loja de exemplo
A Gerencianet oferece uma loja de exemplo criada em PHP para facilitar o entendimento e uso do checkout transparente. Você poderá visualizar e interagir com esta loja pelo link: lojaexemplo.gerencianet.com.br.
Você também poderá contribuir com o código da loja exemplo ou fazer o download do mesmo pelo github