Gerar transação
Como funciona
- Seu sistema envia as informações de pagamento em formato xml;
- A Gerencianet processa as informações e retorna um identificador para o pagamento em questão;
- 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.
- <?xml version="1.0" encoding="utf-8"?>
- <integracao>
- <itens>
- <item>
- <itemValor>50000</itemValor>
- <itemDescricao>Smartphone</itemDescricao>
- <itemQuantidade>1</itemQuantidade>
- </item>
- <item>
- <itemValor>500</itemValor>
- <itemDescricao>DVD</itemDescricao>
- <itemQuantidade>2</itemQuantidade>
- </item>
- </itens>
- <frete>1250</frete>
- <desconto>350</desconto>
- <vencimento>2014-12-12</vencimento>
- <tipo>produto</tipo>
- <descricao>Obrigado por comprar na nossa loja.</descricao>
- <solicitarEndereco>s</solicitarEndereco>
- <retorno>
- <identificador>564987654</identificador>
- <url>http://minhaloja.org/finalizado</url>
- </retorno>
- <cliente>
- <nome>Nome do cliente</nome>
- <cpf>99999999999</cpf>
- <email>emaildocliente@email.com</email>
- <nascimento>1970-01-01</nascimento>
- <celular>3199999999</celular>
- <logradouro>Rua exemplo</logradouro>
- <numero>123</numero>
- <complemento>Casa</complemento>
- <bairro>Bairro Exemplo</bairro>
- <cidade>Cidade Exemplo</cidade>
- <cep>99000000</cep>
- <estado>PA</estado>
- </cliente>
- </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) |
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:
- <?xml version="1.0" encoding="utf-8"?>
- <integracao>
- <status>2</status>
- <resposta>
- <transacao>12323</transacao>
- <link>https://go.gerencianet.com.br/?b=11111/#/teste/pagar/11111-11111-11111</link>
- </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>10033</codigo>
- <erro>Token inválido</erro>
- </erros>
- </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
- $url = "https://go.gerencianet.com.br/api/pagamento/xml";
- $token = "token";
- $xml = "<?xml version='1.0' encoding='utf-8'?>
- <integracao>
- <itens>
- <item>
- <itemValor>500</itemValor>
- <itemDescricao>Solicitacao de pagamento xml</itemDescricao>
- </item>
- </itens>
- <cliente>
- <nome>nome_cliente</nome>
- <cpf>cpf_cliente</cpf>
- <email>email_cliente</email>
- <nascimento>dt_nascimento_cliente</nascimento>
- <celular>cel_cliente</celular>
- <logradouro>logradouro_cliente</logradouro>
- <numero>numero_cliente</numero>
- <bairro>bairro_cliente</bairro>
- <cidade>cidade_cliente</cidade>
- <cep>cep_cliente</cep>
- <estado>estado_cliente</estado>
- </cliente>
- </integracao>";
- $xml = str_replace(array("\n", "\r", "\t"), '', $xml);
- $ch = curl_init();
- curl_setopt($ch, CURLOPT_URL, $url);
- curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
- curl_setopt($ch, CURLOPT_MAXREDIRS, 2);
- curl_setopt($ch, CURLOPT_AUTOREFERER, true);
- $data = array("token" => $token, "dados" => $xml);
- curl_setopt($ch, CURLOPT_POST, true);
- curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
- curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 30);
- curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
- $response = curl_exec($ch);
- curl_close($ch);
- echo "<xmp>".$response."</xmp>";
Via Guzzle
- $url = "https://go.gerencianet.com.br/api/pagamento/xml";
- $token = "token";
- $xml = "<?xml version='1.0' encoding='utf-8'?>
- <integracao>
- <itens>
- <item>
- <itemValor>500</itemValor>
- <itemDescricao>Solicitacao de pagamento xml</itemDescricao>
- </item>
- </itens>
- <cliente>
- <nome>nome_cliente</nome>
- <cpf>cpf_cliente</cpf>
- <email>email_cliente</email>
- <nascimento>dt_nascimento_cliente</nascimento>
- <celular>cel_cliente</celular>
- <logradouro>logradouro_cliente</logradouro>
- <numero>numero_cliente</numero>
- <bairro>bairro_cliente</bairro>
- <cidade>cidade_cliente</cidade>
- <cep>cep_cliente</cep>
- <estado>estado_cliente</estado>
- </cliente>
- </integracao>";
- Guzzle\Http\StaticClient::mount();
- $client = new \Guzzle\Http\Client($url);
- $request = $client->post('', null, array("token" => $token, "dados" => $xml));
- $response = $request->send();
- echo "<xmp>".$response."</xmp>";
- String url = "https://go.gerencianet.com.br/api/pagamento/xml";
- String token = "token";
- String xml = "<?xml version='1.0' encoding='utf-8'?>"
- + "<integracao>"
- + "<itens>"
- + "<item>"
- + "<itemValor>500</itemValor>"
- + "<itemDescricao>Solicitacao de pagamento xml</itemDescricao>"
- + "</item>"
- + "</itens>"
- + "<cliente>"
- + "<nome>nome_cliente</nome>"
- + "<cpf>cpf_cliente</cpf>"
- + "<email>email_cliente</email>"
- + "<nascimento>dt_nascimento_cliente</nascimento>"
- + "<celular>cel_cliente</celular>"
- + "<logradouro>logradouro_cliente</logradouro>"
- + "<numero>numero_cliente</numero>"
- + "<bairro>bairro_cliente</bairro>"
- + "<cidade>cidade_cliente</cidade>"
- + "<cep>cep_cliente</cep>"
- + "<estado>estado_cliente</estado>"
- + "</cliente>"
- + "</integracao>";
- HttpClient client = new DefaultHttpClient();
- HttpPost post = new HttpPost(url);
- List<NameValuePair> urlParameters;
- urlParameters = new ArrayList<>();
- urlParameters.add(new BasicNameValuePair("token", token));
- urlParameters.add(new BasicNameValuePair("dados", xml));
- post.setEntity(new UrlEncodedFormEntity(urlParameters));
- HttpResponse response = client.execute(post);
- System.out.println("Response Code : " + response.getStatusLine().getStatusCode());
- BufferedReader rd = new BufferedReader(
- new InputStreamReader(response.getEntity().getContent()));
- StringBuilder result = new StringBuilder();
- String line = "";
- while ((line = rd.readLine()) != null) {
- result.append(line);
- }
- System.out.println(result.toString());
- String url = "http://go.gerencianet.com.br/api/pagamento/xml";
- String token = "token";
- String xml = "<?xml version='1.0' encoding='utf-8'?>" +
- "<integracao>" +
- "<itens>" +
- "<item>" +
- "<itemValor>500</itemValor>" +
- "<itemDescricao>Solicitacao de pagamento xml</itemDescricao>" +
- "</item>" +
- "</itens>" +
- "<cliente>" +
- "<nome>nome_cliente</nome>" +
- "<cpf>cpf_cliente</cpf>" +
- "<email>email_cliente</email>" +
- "<nascimento>dt_nascimento_cliente</nascimento>" +
- "<celular>cel_cliente</celular>" +
- "<logradouro>logradouro_cliente</logradouro>" +
- "<numero>numero_cliente</numero>" +
- "<bairro>bairro_cliente</bairro>" +
- "<cidade>cidade_cliente</cidade>" +
- "<cep>cep_cliente</cep>" +
- "<estado>estado_cliente</estado>" +
- "</cliente>" +
- "</integracao>";
- WebClient client = new WebClient();
- NameValueCollection postData = new NameValueCollection() { { "token", token }, { "dados", xml } };
- byte[] response = client.UploadValues(url, postData);
- Console.WriteLine("Output: " + System.Text.Encoding.Default.GetString(response));
- import requests
- url = "http://go.gerencianet.com.br/api/pagamento/xml"
- token = "token"
- params = ("<?xml version='1.0' encoding='utf-8'?>" +
- "<integracao>" +
- "<itens>" +
- "<item>" +
- "<itemValor>500</itemValor>" +
- "<itemDescricao>Solicitacao de pagamento xml</itemDescricao>" +
- "</item>" +
- "</itens>" +
- "<cliente>" +
- "<nome>nome_cliente</nome>" +
- "<cpf>cpf_cliente</cpf>" +
- "<email>email_cliente</email>" +
- "<nascimento>dt_nascimento_cliente</nascimento>" +
- "<celular>cel_cliente</celular>" +
- "<logradouro>logradouro_cliente</logradouro>" +
- "<numero>numero_cliente</numero>" +
- "<bairro>bairro_cliente</bairro>" +
- "<cidade>cidade_cliente</cidade>" +
- "<cep>cep_cliente</cep>" +
- "<estado>estado_cliente</estado>" +
- "</cliente>" +
- "</integracao>")
- response = requests.post(url = url, data = {'token': token, 'dados': params})
- print response.text
- require 'httparty'
- url = "http://go.gerencianet.com.br/api/pagamento/xml"
- token = "token"
- xml = "<?xml version='1.0' encoding='utf-8'?>
- <integracao>
- <itens>
- <item>
- <itemValor>500</itemValor>
- <itemDescricao>Solicitacao de pagamento xml</itemDescricao>
- </item>
- </itens>
- <cliente>
- <nome>nome_cliente</nome>
- <cpf>cpf_cliente</cpf>
- <email>email_cliente</email>
- <nascimento>dt_nascimento_cliente</nascimento>
- <celular>cel_cliente</celular>
- <logradouro>logradouro_cliente</logradouro>
- <numero>numero_cliente</numero>
- <bairro>bairro_cliente</bairro>
- <cidade>cidade_cliente</cidade>
- <cep>cep_cliente</cep>
- <estado>estado_cliente</estado>
- </cliente>
- </integracao>"
- 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.