Gerar transação

Como funciona

  1. Seu sistema envia as informações de pagamento em formato xml;
  2. A Gerencianet processa as informações e retorna um identificador para o pagamento em questão;
  3. Seu sistema redireciona o usuário para tela de pagamento da Gerencianet.

Se você possui poucos produtos ou serviços e valores bem definidos para cada um deles, a Gerencianet recomenda que você utilize a ferramenta para gerar botões de pagamento.

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.

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

Para criar um pagamento com a nossa API, você deve nos enviar os dados do pagamento, por meio da sua aplicação, em formato xml ou json, mediante uma requisição HTTP, conforme exemplo abaixo:

POST https://go.gerencianet.com.br/api/pagamento/xml HTTP/1.1

Content-Type: multipart/form-data; charset=utf-8

token=token_de_integracao

dados=seu_xml

Ambiente de testes

Para realizar testes na API de pagamentos, basta enviar as requisições para o ambiente de testes localizado em:

POST https://go.gerencianet.com.br/teste/api/pagamento/xml HTTP/1.1

Content-Type: multipart/form-data; charset=utf-8

token=token_de_integracao

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 em formato xml. O exemplo a seguir possui todos os parâmetros disponíveis.

  1. <?xml version="1.0" encoding="utf-8"?>
  2. <integracao>
  3. <itens>
  4. <item>
  5. <itemValor>50000</itemValor>
  6. <itemDescricao>Smartphone</itemDescricao>
  7. <itemQuantidade>1</itemQuantidade>
  8. </item>
  9. <item>
  10. <itemValor>500</itemValor>
  11. <itemDescricao>DVD</itemDescricao>
  12. <itemQuantidade>2</itemQuantidade>
  13. </item>
  14. </itens>
  15. <frete>1250</frete>
  16. <desconto>350</desconto>
  17. <vencimento>2014-12-12</vencimento>
  18. <tipo>produto</tipo>
  19. <descricao>Obrigado por comprar na nossa loja.</descricao>
  20. <solicitarEndereco>s</solicitarEndereco>
  21. <retorno>
  22. <identificador>564987654</identificador>
  23. <url>http://minhaloja.org/finalizado</url>
  24. </retorno>
  25. <cliente>
  26. <nome>Nome do cliente</nome>
  27. <cpf>99999999999</cpf>
  28. <email>emaildocliente@email.com</email>
  29. <nascimento>1970-01-01</nascimento>
  30. <celular>3199999999</celular>
  31. <logradouro>Rua exemplo</logradouro>
  32. <numero>123</numero>
  33. <complemento>Casa</complemento>
  34. <bairro>Bairro Exemplo</bairro>
  35. <cidade>Cidade Exemplo</cidade>
  36. <cep>99000000</cep>
  37. <estado>PA</estado>
  38. </cliente>
  39. </integracao>

Descrição dos parâmetros de entrada

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.
frete não Valor, em centavos, do frete. Este campo deve conter apenas números.

Por exemplo, se o frete custa R$32,00, o valor deverá ser “3200”.

tipo não Tipo da venda. Os valores possíveis são "produto" ou "servico".
solicitarEndereco não Especifica quando o sistema deve ou não solicitar o "endereço para entrega" na tela de pagamento. Os valores possíveis são "s" ou "n".
descricao não Mensagem opcional sobre a venda. Aparece na tela de pagamento como "Mensagem do Vendedor".
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”.

vencimento não Data de vencimento da cobrança no formato YYYY-MM-DD, formato oficial do W3C.
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.
url não URL para redirecionamento do seu cliente após o pagamento.
cliente não Tag que engloba os dados do cliente envolvido na transação. Não poderá ser repetida.
nome não Nome do cliente envolvido na transação.
cpf não CPF do cliente envolvido na transação. Deve conter 11 caracteres (apenas números)
email não E-mail válido do cliente envolvido na transação.
nascimento não Data de nascimento do cliente envolvido na transação no formato YYYY-MM-DD, formato oficial do W3C.
celular não

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

Exemplo: 3188888888.

logradouro não Logradouro (Rua, Avenida, Praça, etc.) do cliente envolvido na transação.
numero não Número da residência do cliente envolvido na transação.
bairro não Bairro do cliente envolvido na transação.
complemento não Complemento do endereço do cliente envolvido na transação.
cidade não Cidade do cliente envolvido na transação.
cep não CEP do cliente envolvido na transação. Deve conter 8 caracteres (apenas números).
estado não

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

Exemplo: MG

Resposta em caso de sucesso

Se os dados enviados estiverem corretos, a Gerencianet retornará um identificador para o pagamento. 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>12323</transacao>
  6. <link>https://go.gerencianet.com.br/?b=11111/#/teste/pagar/11111-11111-11111</link>
  7. </resposta>
  8. </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>10033</codigo>
  6. <erro>Token inválido</erro>
  7. </erros>
  8. </integracao>

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.
link Link da tela de pagamento para onde seu cliente deve ser redirecionado.
transacao Número da transação gerada pela requisição. Você poderá utilizar este número para consultar os detalhes da transação.
erros Tag que contém os erros ocorridos durante o processo de integração.
codigo Código do erro.
erros Descrição do erro.

Redirecionando seu cliente

Após gerar a transação você deve redirecionar o comprador para o link descrito na tag link do XML de resposta, como no exemplo a seguir:

Exemplos

Via Curl
  1. $url = "https://go.gerencianet.com.br/api/pagamento/xml";
  2. $token = "token";
  3.  
  4. $xml = "<?xml version='1.0' encoding='utf-8'?>
  5. <integracao>
  6. <itens>
  7. <item>
  8. <itemValor>500</itemValor>
  9. <itemDescricao>Solicitacao de pagamento xml</itemDescricao>
  10. </item>
  11. </itens>
  12. <cliente>
  13. <nome>nome_cliente</nome>
  14. <cpf>cpf_cliente</cpf>
  15. <email>email_cliente</email>
  16. <nascimento>dt_nascimento_cliente</nascimento>
  17. <celular>cel_cliente</celular>
  18. <logradouro>logradouro_cliente</logradouro>
  19. <numero>numero_cliente</numero>
  20. <bairro>bairro_cliente</bairro>
  21. <cidade>cidade_cliente</cidade>
  22. <cep>cep_cliente</cep>
  23. <estado>estado_cliente</estado>
  24. </cliente>
  25. </integracao>";
  26.  
  27. $xml = str_replace(array("\n", "\r", "\t"), '', $xml);
  28.  
  29. $ch = curl_init();
  30. curl_setopt($ch, CURLOPT_URL, $url);
  31. curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  32. curl_setopt($ch, CURLOPT_MAXREDIRS, 2);
  33. curl_setopt($ch, CURLOPT_AUTOREFERER, true);
  34. $data = array("token" => $token, "dados" => $xml);
  35.  
  36. curl_setopt($ch, CURLOPT_POST, true);
  37.  
  38. curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
  39. curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 30);
  40. curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
  41. $response = curl_exec($ch);
  42.  
  43. curl_close($ch);
  44.  
  45. echo "<xmp>".$response."</xmp>";
Via Guzzle
  1. $url = "https://go.gerencianet.com.br/api/pagamento/xml";
  2. $token = "token";
  3.  
  4. $xml = "<?xml version='1.0' encoding='utf-8'?>
  5. <integracao>
  6. <itens>
  7. <item>
  8. <itemValor>500</itemValor>
  9. <itemDescricao>Solicitacao de pagamento xml</itemDescricao>
  10. </item>
  11. </itens>
  12. <cliente>
  13. <nome>nome_cliente</nome>
  14. <cpf>cpf_cliente</cpf>
  15. <email>email_cliente</email>
  16. <nascimento>dt_nascimento_cliente</nascimento>
  17. <celular>cel_cliente</celular>
  18. <logradouro>logradouro_cliente</logradouro>
  19. <numero>numero_cliente</numero>
  20. <bairro>bairro_cliente</bairro>
  21. <cidade>cidade_cliente</cidade>
  22. <cep>cep_cliente</cep>
  23. <estado>estado_cliente</estado>
  24. </cliente>
  25. </integracao>";
  26.  
  27. Guzzle\Http\StaticClient::mount();
  28. $client = new \Guzzle\Http\Client($url);
  29. $request = $client->post('', null, array("token" => $token, "dados" => $xml));
  30. $response = $request->send();
  31.  
  32. echo "<xmp>".$response."</xmp>";
  1. String url = "https://go.gerencianet.com.br/api/pagamento/xml";
  2. String token = "token";
  3.  
  4. String xml = "<?xml version='1.0' encoding='utf-8'?>"
  5. + "<integracao>"
  6. + "<itens>"
  7. + "<item>"
  8. + "<itemValor>500</itemValor>"
  9. + "<itemDescricao>Solicitacao de pagamento xml</itemDescricao>"
  10. + "</item>"
  11. + "</itens>"
  12. + "<cliente>"
  13. + "<nome>nome_cliente</nome>"
  14. + "<cpf>cpf_cliente</cpf>"
  15. + "<email>email_cliente</email>"
  16. + "<nascimento>dt_nascimento_cliente</nascimento>"
  17. + "<celular>cel_cliente</celular>"
  18. + "<logradouro>logradouro_cliente</logradouro>"
  19. + "<numero>numero_cliente</numero>"
  20. + "<bairro>bairro_cliente</bairro>"
  21. + "<cidade>cidade_cliente</cidade>"
  22. + "<cep>cep_cliente</cep>"
  23. + "<estado>estado_cliente</estado>"
  24. + "</cliente>"
  25. + "</integracao>";
  26.  
  27. HttpClient client = new DefaultHttpClient();
  28. HttpPost post = new HttpPost(url);
  29.  
  30. List<NameValuePair> urlParameters;
  31. urlParameters = new ArrayList<>();
  32. urlParameters.add(new BasicNameValuePair("token", token));
  33. urlParameters.add(new BasicNameValuePair("dados", xml));
  34.  
  35. post.setEntity(new UrlEncodedFormEntity(urlParameters));
  36.  
  37. HttpResponse response = client.execute(post);
  38. System.out.println("Response Code : " + response.getStatusLine().getStatusCode());
  39.  
  40. BufferedReader rd = new BufferedReader(
  41. new InputStreamReader(response.getEntity().getContent()));
  42.  
  43. StringBuilder result = new StringBuilder();
  44. String line = "";
  45. while ((line = rd.readLine()) != null) {
  46. result.append(line);
  47. }
  48.  
  49. System.out.println(result.toString());
  1. String url = "http://go.gerencianet.com.br/api/pagamento/xml";
  2. String token = "token";
  3. String xml = "<?xml version='1.0' encoding='utf-8'?>" +
  4. "<integracao>" +
  5. "<itens>" +
  6. "<item>" +
  7. "<itemValor>500</itemValor>" +
  8. "<itemDescricao>Solicitacao de pagamento xml</itemDescricao>" +
  9. "</item>" +
  10. "</itens>" +
  11. "<cliente>" +
  12. "<nome>nome_cliente</nome>" +
  13. "<cpf>cpf_cliente</cpf>" +
  14. "<email>email_cliente</email>" +
  15. "<nascimento>dt_nascimento_cliente</nascimento>" +
  16. "<celular>cel_cliente</celular>" +
  17. "<logradouro>logradouro_cliente</logradouro>" +
  18. "<numero>numero_cliente</numero>" +
  19. "<bairro>bairro_cliente</bairro>" +
  20. "<cidade>cidade_cliente</cidade>" +
  21. "<cep>cep_cliente</cep>" +
  22. "<estado>estado_cliente</estado>" +
  23. "</cliente>" +
  24. "</integracao>";
  25.  
  26. WebClient client = new WebClient();
  27. NameValueCollection postData = new NameValueCollection() { { "token", token }, { "dados", xml } };
  28. byte[] response = client.UploadValues(url, postData);
  29.  
  30. Console.WriteLine("Output: " + System.Text.Encoding.Default.GetString(response));
  1. import requests
  2.  
  3. url = "http://go.gerencianet.com.br/api/pagamento/xml"
  4. token = "token"
  5.  
  6. params = ("<?xml version='1.0' encoding='utf-8'?>" +
  7. "<integracao>" +
  8. "<itens>" +
  9. "<item>" +
  10. "<itemValor>500</itemValor>" +
  11. "<itemDescricao>Solicitacao de pagamento xml</itemDescricao>" +
  12. "</item>" +
  13. "</itens>" +
  14. "<cliente>" +
  15. "<nome>nome_cliente</nome>" +
  16. "<cpf>cpf_cliente</cpf>" +
  17. "<email>email_cliente</email>" +
  18. "<nascimento>dt_nascimento_cliente</nascimento>" +
  19. "<celular>cel_cliente</celular>" +
  20. "<logradouro>logradouro_cliente</logradouro>" +
  21. "<numero>numero_cliente</numero>" +
  22. "<bairro>bairro_cliente</bairro>" +
  23. "<cidade>cidade_cliente</cidade>" +
  24. "<cep>cep_cliente</cep>" +
  25. "<estado>estado_cliente</estado>" +
  26. "</cliente>" +
  27. "</integracao>")
  28.  
  29. response = requests.post(url = url, data = {'token': token, 'dados': params})
  30. print response.text
  1. require 'httparty'
  2.  
  3. url = "http://go.gerencianet.com.br/api/pagamento/xml"
  4. token = "token"
  5. xml = "<?xml version='1.0' encoding='utf-8'?>
  6. <integracao>
  7. <itens>
  8. <item>
  9. <itemValor>500</itemValor>
  10. <itemDescricao>Solicitacao de pagamento xml</itemDescricao>
  11. </item>
  12. </itens>
  13. <cliente>
  14. <nome>nome_cliente</nome>
  15. <cpf>cpf_cliente</cpf>
  16. <email>email_cliente</email>
  17. <nascimento>dt_nascimento_cliente</nascimento>
  18. <celular>cel_cliente</celular>
  19. <logradouro>logradouro_cliente</logradouro>
  20. <numero>numero_cliente</numero>
  21. <bairro>bairro_cliente</bairro>
  22. <cidade>cidade_cliente</cidade>
  23. <cep>cep_cliente</cep>
  24. <estado>estado_cliente</estado>
  25. </cliente>
  26. </integracao>"
  27.  
  28. HTTParty.post(url, body: { token: token, dados: xml }, headers: { "User-Agent" => request.user_agent }).body

Histórico de requisições

Acompanhe o histórico de requisições realizadas à API de pagamentos em sua conta. O histórico de requisições é ideal para identificar erros durante a etapa de implementação da integração.