Criando link de pagamento

Saiba como criar um link para uma tela de pagamento da Gerencianet para seus clientes efetuarem os pagamentos. Para criar, é bem simples e requer apenas dois passos: 1. Primeiramente, [crie a transação](https://dev.gerencianet.com.br/docs/link-pagamento-criando#section-1-crie-a-transa-o), informando o item/produto/serviço, valor, quantidade, etc; 2. Agora, para [criar o link de pagamento](https://dev.gerencianet.com.br/docs/link-pagamento-criando#section-2-criando-um-link-de-pagamento), informe o <code>charge_id</code> da transação criada anteriormente. O restante desta página apresenta os procedimentos detalhados, mas você precisa instalar uma de nossas bibliotecas em seu servidor para executar os códigos de exemplo. [Certifique-se de que a SDK da Gerencianet foi instalada](https://dev.gerencianet.com.br/docs#section-2-bibliotecas). <hr> # 1. Crie a transação Primeiramente, precisamos gerar a transação (também chamada de "cobrança"). É neste momento que será informado o nome do item/produto/serviço, valor da transação, quantidade, dentre outras informações possíveis. Após criá-la, será retornado o <code>charge_id</code>, que é o identificador único da transação e que será utilizado para associar à forma de pagamento. Assim que essa transação é criada, ela recebe o status <code>new</code>, que significa que a cobrança foi gerada e está aguardando definição da forma de pagamento. Essa cobrança somente terá seu status alterado quando o integrador definir sua forma de pagamento. Para gerar uma transação, você deve enviar uma requisição <code>POST</code> para a rota <code>/v1/charge</code>. Caso queira, pode explorar e conhecer mais sobre este recurso <a href="https://dev.gerencianet.com.br/docs/playground-transacoes#charge" target="_blank">usando nosso Playground</a>. O exemplo abaixo mostra como isto pode ser feito, utilizando as SDK's disponíveis: [block:code] { "codes": [ { "code": "<?php\n \nrequire __DIR__.'/../../vendor/autoload.php'; // caminho relacionado a SDK\n \nuse Gerencianet\\Exception\\GerencianetException;\nuse Gerencianet\\Gerencianet;\n \n$clientId = 'informe_seu_client_id'; // insira seu Client_Id, conforme o ambiente (Des ou Prod)\n$clientSecret = 'informe_seu_client_secret'; // insira seu Client_Secret, conforme o ambiente (Des ou Prod)\n \n$options = [\n 'client_id' => $clientId,\n 'client_secret' => $clientSecret,\n 'sandbox' => true // altere conforme o ambiente (true = desenvolvimento e false = producao)\n];\n \n$item_1 = [\n 'name' => 'Item 1', // nome do item, produto ou serviço\n 'amount' => 1, // quantidade\n 'value' => 1000 // valor (1000 = R$ 10,00)\n];\n \n$item_2 = [\n 'name' => 'Item 2', // nome do item, produto ou serviço\n 'amount' => 2, // quantidade\n 'value' => 2000 // valor (2000 = R$ 20,00)\n];\n \n$items = [\n $item_1,\n $item_2\n];\n\n// Exemplo para receber notificações da alteração do status da transação.\n// $metadata = ['notification_url'=>'sua_url_de_notificacao_.com.br']\n// Outros detalhes em: https://dev.gerencianet.com.br/docs/notificacoes\n\n// Como enviar seu $body com o $metadata\n// $body = [\n// 'items' => $items,\n//\t\t'metadata' => $metadata\n// ];\n\n$body = [\n 'items' => $items\n];\n\ntry {\n $api = new Gerencianet($options);\n $charge = $api->createCharge([], $body);\n \n print_r($charge);\n} catch (GerencianetException $e) {\n print_r($e->code);\n print_r($e->error);\n print_r($e->errorDescription);\n} catch (Exception $e) {\n print_r($e->getMessage());\n}", "language": "php" }, { "code": "'use strict';\n \nvar Gerencianet = require('gn-api-sdk-node');\n \nvar clientId = 'your_client_id';\nvar clientSecret = 'your_client_secret';\n \nvar options = {\n client_id: clientId,\n client_secret: clientSecret,\n sandbox: true\n}\n \nvar body = {\n items: [{\n name: 'Product 1',\n value: 1000,\n amount: 2\n }],\n shippings: [{\n name: 'Default Shipping Cost',\n value: 100\n }]\n}\n \nvar gerencianet = new Gerencianet(options);\n \ngerencianet\n .createCharge({}, body)\n .then(console.log)\n .catch(console.log)\n .done();", "language": "javascript", "name": "NodeJS" }, { "code": "require \"gerencianet\"\nrequire_relative \"./credentials\"\n\noptions = {\n client_id: CREDENTIALS::CLIENT_ID,\n client_secret: CREDENTIALS::CLIENT_SECRET,\n sandbox: true\n}\n\nbody = {\n items: [{\n name: \"Product 1\",\n value: 1000,\n amount: 2\n }],\n shippings: [{\n name: \"Default Shipping Cost\",\n value: 100\n }]\n}\n\ngerencianet = Gerencianet.new(options)\nputs gerencianet.create_charge(body: body)", "language": "ruby" }, { "code": "from gerencianet import Gerencianet\n \noptions = {\n 'client_id': 'client_id',\n 'client_secret': 'client_secret',\n 'sandbox': True\n}\n \ngn = Gerencianet(options)\n \nbody = {\n 'items': [{\n 'name': \"Product 1\",\n 'value': 1000,\n 'amount': 2\n }],\n 'shippings': [{\n 'name': \"Default Shipping Cost\",\n 'value': 100\n }]\n}\n \ngn.create_charge(body=body)", "language": "python" }, { "code": "dynamic endpoints = new Endpoints(\"client_id\", \"client_secret\", true);\n \nvar body = new\n{\n items = new[] {\n new {\n name = \"Product 1\",\n value = 1000,\n amount = 2\n }\n },\n shippings = new[] {\n new {\n name = \"Default Shipping Cost\",\n value = 100\n }\n }\n};\n \nvar response = endpoints.CreateCharge(null, body);\nConsole.WriteLine(response);", "language": "asp", "name": ".NET" }, { "code": "/* Para que a SDK Java funcione corretamente, é necessário que a instanciação do módulo seja feita através da criação de um objeto do tipo Gerencianet.\n\nSempre que quisermos chamar uma função da API, basta invocar o método call do objeto Gerencianet, passando como parâmetro o nome do método, os parâmetros da requisição (sempre será um HashMap<String, String>), e o \"body\", que consiste nas propriedades a serem passadas como argumento na chamada de um função da SDK. O \"body\" pode ser declarado de duas formas: um JSONObject ou um Map<String, Object>.\n\nEsta estrutura é necessária para representar o corpo da requisição http que é enviada à um determinado endpoint. Se o \"body\" for um JSONObject, o retorno do método call será um JSONObject, se for um Map<String, Object>, o retorno do método call será um Map<String, Object>\n\nA seguir, disponibilizamos links de nosso Github mostrando duas formas diferentes de retorno: JSONObject\ne Map<String, Object>\n\n\nJSONObject\n\nhttps://github.com/gerencianet/gn-api-sdk-java-examples/blob/master/src/main/java/br/com/gerencianet/charge/json/CreateCharge.java\n\n\nMap<String, Object>\n\nhttps://github.com/gerencianet/gn-api-sdk-java-examples/blob/master/src/main/java/br/com/gerencianet/charge/map/CreateCharge.java\n\n*/", "language": "java" }, { "code": "interface\nfunction CreateCharge: String;\n\nimplementation\nuses uGerenciaClient, uGerenciaNetClientUtilities;\n{... your code ... }\n\nfunction CreateCharge: String;\nvar \nBody : String;\n\nbegin \n EnableService( 'GerenciaNet.dll' ); \n ConfigureService( ToPAnsiChar( 'client_id' ),ToPAnsiChar( 'client_secret' ),'sandbox','config.json',''); \n GerenciaNetAuthorize(); \n\n Body := \n '{'+\n '\"items\":'+\n '['+\n '{'+\n '\"name\":\"test article\",'+\n '\"value\":1900,'+\n '\"amount\":2'+\n '},'+\n '{'+\n '\"name\":\"test article 2\",'+\n '\"value\":3000,'+\n '\"amount\":1'+\n '}'+\n ']'+\n '}';\n\n Result := ExecuteGerenciaNetRequest( 'createCharge','','',Body );\nend;", "language": "json", "name": "Delphi" }, { "code": "// No código de exemplo de uso da SDK de Go, definimos as credenciais de acesso à API (Client_Id e Client_Secret) e o ambiente a ser usado (sandbox como 'true' ou 'false') dentro de um arquivo específico (configs.go), que está localizado no diretório \"_examples/configs\". Essas credenciais são exportadas através da variável 'Credentials'.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"github.com/gerencianet/gn-api-sdk-go/gerencianet\"\n\t\"github.com/gerencianet/gn-api-sdk-go/_examples/configs\"\n)\n\nfunc main(){\n\t\n\tcredentials := configs.Credentials\n\tgn := gerencianet.NewGerencianet(credentials)\n\n\tbody := map[string]interface{} {\n\t\t\"items\": []map[string]interface{}{\n\t\t\t{\n\t\t\t\t\"name\": \"Product 1\",\n\t\t\t\t\"value\": 1000,\n\t\t\t\t\"amount\": 2,\n\t\t\t},\n\t\t},\n\t\t\"shippings\": []map[string]interface{} {\n\t\t\t{\n\t\t\t\t\"name\": \"Default Shipping Cost\",\n\t\t\t\t\"value\": 100,\n\t\t\t},\n\t\t},\n\t}\n\n\tres, err := gn.CreateCharge(body)\n\n\tif err != nil {\n\t\tfmt.Println(err)\n\t} else {\n\t\tfmt.Println(res)\n\t}\n}", "language": "go" } ] } [/block] <br> ## a) Estrutura hierárquica dos atributos do Schema que podem ser utilizados: <pre>"id": "/Charge" "items" "name" "value" "amount" "marketplace" "payee_code" "percentage" "shippings" "name" "value" "payee_code" "metadata" "custom_id" "notification_url"</pre> Para verificar mais detalhes, <a href="https://dev.gerencianet.com.br/docs/playground-transacoes#charge" target="_blank">acesse aqui</a> e explore em nosso Playground. <br> ## b) Atributos que podem ser utilizados para criar uma transação: [block:parameters] { "data": { "h-0": "Atributo", "h-1": "Descrição", "h-2": "Obrigatório", "h-3": "Tipo", "0-0": "<code>items</code>", "1-0": "<code>shippings</code>", "2-0": "<code>metadata</code>", "0-1": "Item que está sendo vendido. Uma mesma transação pode possuir ilimitados itens.\n\n<span class=\"tab1\"><em>Atributos de items</em></span>\n\n<div class=\"tab2\"><code>name<strong class=\"atributo-obrigatorio\">*</strong></code> // Nome do item, produto ou serviço. <strong class=\"descricao-atributo\"><span class=\"atributo\">Mínimo de 1 caractere e máximo de 255 caracteres (String).</span></strong></div>\n\n<div class=\"tab2\"><code>value<strong class=\"atributo-obrigatorio\">*</strong></code> // Valor, em centavos. Ex: R$ 10,00 = 1000. <strong class=\"descricao-atributo\"><span class=\"atributo\">Integer.</span></strong></div>\n\n<div class=\"tab2\"><code>amount</code> // Quantidade. <strong class=\"descricao-atributo\"><span class=\"atributo\">Integer (padrão: 1)</span></strong></div>\n\n<div class=\"tab2\"><code>marketplace</code> // Referente às configurações de repasses. <span class=\"atributo\">Atributos:</span></div> <div class=\"tab2\">\n<code>*payee_code*</code> (<a href=\"http://image.prntscr.com/image/cabe13e1e5b64449b942cf31139150ba.png\" target=\"_blank\">código identificador da conta Gerencianet</a> - String).\n<code>*percentage*</code> (porcentagem de repasse, sendo que 9000 equivale a 90% - Integer).</span></div>", "1-1": "Determina o(s) valor(es) de frete(s) de uma transação. Uma mesma transação pode possuir ilimitados valores de frete.\n\n<span class=\"tab1\"><em>Atributos de shippings</em></span>\n\n<div class=\"tab2\"><code>name<strong class=\"atributo-obrigatorio\">*</strong></code> // Rótulo do frete. <strong class=\"descricao-atributo\"><span class=\"atributo\">Máximo de 255 caracteres. String.</span></strong></div>\n\n<div class=\"tab2\"><code>value<strong class=\"atributo-obrigatorio\">*</strong></code> // Valor do frete, em centavos (1990 equivale a R$19,90). <strong class=\"descricao-atributo\"><span class=\"atributo\">Integer.</span></strong></div>\n\n<div class=\"tab2\"><code>payeeCode</code> // <a href=\"http://image.prntscr.com/image/cabe13e1e5b64449b942cf31139150ba.png\" target=\"_blank\">Código identificador da conta Gerencianet</a>, único por conta. <strong class=\"descricao-atributo\"><span class=\"atributo\">Padrão: Identificador da sua própria conta. String.</span></strong></div>", "2-1": "Define dados específicos da transação.\n\n<span class=\"tab1\"><em>Atributos de metadata</em></span>\n\n<div class=\"tab2\"><code>custom_id</code> // Permite associar uma transação Gerencianet a uma ID específica de seu sistema ou aplicação, permitindo identificá-la caso você possua uma identificação específica e queira mantê-la. <strong class=\"descricao-atributo\"><span class=\"atributo\">Máximo de 255 caracteres. String/null.</span></strong></div>\n\n<div class=\"tab2\"><code>notification_url</code> // Endereço de sua URL válida que receberá as notificações de mudanças de status das transações. <strong class=\"descricao-atributo\"><span class=\"atributo\">Máximo de 255 caracteres. String/null.</span></strong></div>", "0-2": "Sim", "1-2": "Não", "2-2": "Não", "0-3": "Array", "1-3": "Array", "2-3": "Object" }, "cols": 4, "rows": 3 } [/block] <strong class="atributo-obrigatorio-texto">* valor obrigatório</strong> <br> Agora que a transação já foi criada e você já possui o <code>charge_id</code>, é preciso associá-lo para obter o link de pagamento. <br> <hr> # 2. Criando um link de pagamento Para criar um link de pagamento, você precisa ter [gerado a transação](https://dev.gerencianet.com.br/docs/link-pagamento-criando#section-1-crie-a-transa-o), ou seja, que você já tenha o identificador <code>charge_id</code> da cobrança, pois será necessário informá-lo. Em seguida, basta enviar uma requisição <code>POST</code> para a rota <code>/v1/charge/:id/link</code> para gerar um link de pagamento, onde o <code>:id</code> corresponde ao <code>charge_id</code> da transação criada. Caso queira, pode explorar e conhecer mais sobre este recurso <a href="https://dev.gerencianet.com.br/docs/playground-transacoes#charge_id_link" target="_blank">usando nosso Playground</a>. O exemplo abaixo mostra como isto pode ser feito, utilizando as SDK's disponíveis: [block:code] { "codes": [ { "code": "<?php\n\nrequire __DIR__.'/../../vendor/autoload.php'; // caminho relacionado a SDK\n\nuse Gerencianet\\Exception\\GerencianetException;\nuse Gerencianet\\Gerencianet;\n\n$clientId = 'informe_seu_client_id'; // insira seu Client_Id, conforme o ambiente (Des ou Prod)\n$clientSecret = 'informe_seu_client_secret'; // insira seu Client_Secret, conforme o ambiente (Des ou Prod)\n \n$options = [\n 'client_id' => $clientId,\n 'client_secret' => $clientSecret,\n 'sandbox' => true // altere conforme o ambiente (true = desenvolvimento e false = producao)\n];\n\n// $charge_id refere-se ao ID da transação gerada anteriormente\n$params = [\n 'id' => $charge_id\n];\n\n$body = [\n 'billet_discount' => 5000, // desconto, em reais, caso o pagador escolha boleto (5000 equivale a R$ 50,00)\n 'card_discount' => 3000, // desconto, em reais, caso o pagador escolha cartão (3000 equivale a R$ 30,00)\n 'message' => '', // mensagem para o pagador com até 80 caracteres\n 'expire_at' => '2018-12-20', // data de vencimento da tela de pagamento e do próprio boleto\n 'request_delivery_address' => false, // solicitar endereço de entrega do comprador?\n 'payment_method' => 'all' // formas de pagamento disponíveis\n];\n\ntry {\n $api = new Gerencianet($options);\n $response = $api->linkCharge($params, $body);\n print_r($response);\n} catch (GerencianetException $e) {\n print_r($e->code);\n print_r($e->error);\n print_r($e->errorDescription);\n} catch (Exception $e) {\n print_r($e->getMessage());\n}", "language": "php" }, { "code": "'use strict';\n\nvar moment = require('moment');\nvar Gerencianet = require('gn-api-sdk-node');\nvar credentials = require('./credentials');\n\nvar options = {\n client_id: credentials.client_id,\n client_secret: credentials.client_secret,\n sandbox: true\n};\n\nvar expireAt = moment()\n .add(3, 'days')\n .format('YYYY-MM-DD');\n\nvar params = {\n id: 0\n};\n\nvar body = {\n billet_discount: 0,\n card_discount: 0,\n message: '',\n expire_at: expireAt,\n request_delivery_address: false,\n payment_method: 'all'\n};\n\nvar gerencianet = new Gerencianet(options);\n\ngerencianet\n .linkCharge(params, body)\n .then(console.log)\n .catch(console.log)\n .done();", "language": "javascript", "name": "NodeJS" }, { "code": "require \"gerencianet\"\nrequire \"date\"\nrequire_relative \"./credentials\"\n\noptions = {\n client_id: CREDENTIALS::CLIENT_ID,\n client_secret: CREDENTIALS::CLIENT_SECRET,\n sandbox: true\n}\n\nexpireAt = Date.today + 3\n\nparams = {\n id: 1000\n}\n\nbody = {\n billet_discount: 0,\n card_discount: 0,\n message: \"\",\n expire_at: expireAt.strftime,\n request_delivery_address: false,\n payment_method: \"all\"\n}\n\ngerencianet = Gerencianet.new(options)\nputs gerencianet.link_charge(params: params, body: body)", "language": "ruby" }, { "code": "# encoding: utf-8\n\nfrom gerencianet import Gerencianet\nfrom credentials import CREDENTIALS\n\ngn = Gerencianet(CREDENTIALS)\n\nbody = {\n 'items': [{\n 'name': \"Product 1\",\n 'value': 1000,\n 'amount': 2\n }],\n 'shippings': [{\n 'name': \"Default Shipping Cost\",\n 'value': 100\n }]\n}\n\nlink = {\n 'billet_discount': 0,\n 'card_discount': 0,\n 'message': '',\n 'expire_at': '2017-12-12',\n 'request_delivery_address': false,\n 'payment_method': 'all'\n}\n\n\ncharge = gn.create_charge(body=body)\n\nparams = {\n 'id': charge['data']['charge_id']\n}\n\nresponse = gn.link_charge(params=params, body=link)\nprint(response)", "language": "python" }, { "code": "using System;\n\nnamespace Gerencianet.SDK.Examples\n{\n class LinkCharge\n {\n public static void Execute()\n {\n dynamic endpoints = new Endpoints(Credentials.Default.ClientId, Credentials.Default.ClientSecret, Credentials.Default.Sandbox);\n\n var param = new\n {\n id = 1000\n };\n\n var body = new\n {\n billet_discount = 0,\n card_discount = 0,\n message = \"\",\n expire_at = DateTime.Now.AddDays(3).ToString(\"yyyy-MM-dd\"),\n request_delivery_address = false,\n payment_method = \"all\"\n };\n\n try\n {\n var response = endpoints.LinkCharge(param, body);\n Console.WriteLine(response);\n }\n catch (GnException e)\n {\n Console.WriteLine(e.ErrorType);\n Console.WriteLine(e.Message);\n }\n }\n }\n}", "language": "asp", "name": ".NET" }, { "code": "/* Para que a SDK Java funcione corretamente, é necessário que a instanciação do módulo seja feita através da criação de um objeto do tipo Gerencianet.\n\nSempre que quisermos chamar uma função da API, basta invocar o método call do objeto Gerencianet, passando como parâmetro o nome do método, os parâmetros da requisição (sempre será um HashMap<String, String>), e o \"body\", que consiste nas propriedades a serem passadas como argumento na chamada de um função da SDK. O \"body\" pode ser declarado de duas formas: um JSONObject ou um Map<String, Object>.\n\nEsta estrutura é necessária para representar o corpo da requisição http que é enviada à um determinado endpoint. Se o \"body\" for um JSONObject, o retorno do método call será um JSONObject, se for um Map<String, Object>, o retorno do método call será um Map<String, Object>\n\nA seguir, disponibilizamos links de nosso Github mostrando duas formas diferentes de retorno: JSONObject\ne Map<String, Object>\n\n\nJSONObject\n\nhttps://github.com/gerencianet/gn-api-sdk-java-examples/blob/master/src/main/java/br/com/gerencianet/charge/json/Link.java\n\n\nMap<String, Object>\n\nhttps://github.com/gerencianet/gn-api-sdk-java-examples/blob/master/src/main/java/br/com/gerencianet/charge/map/Link.java\n\n*/", "language": "java" }, { "code": "interface\nfunction LinkCharge(Id: String): String;\n\nimplementation\nuses uGerenciaClient, uGerenciaNetClientUtilities;\n{... your code ... }\n\nfunction LinkCharge(Id: String): String;\nvar\n Params: String;\n Body : String;\nbegin\n EnableService( 'GerenciaNet.dll' ); \n ConfigureService( ToPAnsiChar( 'client_id' ),ToPAnsiChar( 'client_secret' ),'sandbox','config.json',''); \n GerenciaNetAuthorize();\n\n Params := CreateRequestParams( [ 'id='+Id ] ).Text;\n Body := '{\"billet_discount\": 10,'+\n '\"card_discount\": 10,'+\n '\"message\": \"link test\",'+\n '\"expire_at\": \"2018-12-12\",'+\n '\"request_delivery_address\": false,'+\n '\"payment_method\": \"all\"}';\n Result := ExecuteGerenciaNetRequest( 'linkCharge',Params, '', Body );\nend;", "language": "json", "name": "Delphi" }, { "code": "// No código de exemplo de uso da SDK de Go, definimos as credenciais de acesso à API (Client_Id e Client_Secret) e o ambiente a ser usado (sandbox como 'true' ou 'false') dentro de um arquivo específico (configs.go), que está localizado no diretório \"_examples/configs\". Essas credenciais são exportadas através da variável 'Credentials'.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"github.com/gerencianet/gn-api-sdk-go/gerencianet\"\n\t\"github.com/gerencianet/gn-api-sdk-go/_examples/configs\"\n)\n\nfunc main(){\n\t\n\tcredentials := configs.Credentials\n\tgn := gerencianet.NewGerencianet(credentials)\n\n\tbody := map[string]interface{} {\n\t\t\"billet_discount\": 1,\n\t\t\"card_discount\": 1,\n\t\t\"message\": \"teste\",\n\t\t\"expire_at\": \"2018-12-12\",\n\t\t\"request_delivery_address\": false,\n\t\t\"payment_method\": \"all\",\n\t}\n\n\tres, err := gn.ChargeLink(1, body) // no lugar do 1 coloque o charge_id certo\n\n\tif err != nil {\n\t\tfmt.Println(err)\n\t} else {\n\t\tfmt.Println(res)\n\t}\n}", "language": "go" } ] } [/block] <br> [block:callout] { "type": "warning", "body": "Para se criar um \"link de pagamento\" (<code>chargeLink</code>), uma \"transação\" (<code>createCharge</code>) previamente criada deverá ser informada. Logo, se houver uma tentativa de pagamento e, por alguma razão, não houver sucesso na confirmação do pagamento (ex: cartão recusado, cliente deseja pagar por outra forma, etc), uma nova transação deverá ser gerada e associada a um novo link de pagamento, pois a transação anterior estará com status de <code>waiting</code> ou <code>unpaid</code>, o que significa que devido a tentativa de pagamento, ela já foi atrelada a um método de pagamento.", "title": "IMPORTANTE" } [/block] <br> ## a) Atributos que podem ser utilizados para criar um link de pagamento: [block:parameters] { "data": { "h-0": "Atributo", "h-1": "Descrição", "h-2": "Obrigatório", "h-3": "Tipo", "0-0": "<code>billet_discount</code>", "1-0": "<code>card_discount</code>", "3-0": "<code>message</code>", "4-0": "<code>expire_at</code>", "5-0": "<code>request_delivery_address</code>", "6-0": "<code>payment_method</code>", "4-2": "Sim", "5-2": "Sim", "6-2": "Sim", "0-2": "Não", "1-2": "Não", "3-2": "Não", "0-3": "Integer", "1-3": "Integer", "3-3": "String", "4-3": "String", "5-3": "Boolean", "6-3": "Object", "6-1": "Define as formas de pagamento que devem ficar disponíveis na tela para seu cliente escolher, podendo ser:\n\n- <code>banking_billet</code> (boleto bancário);\n- <code>credit_card</code> (cartão de crédito) ou;\n- <code>all</code> (permitir pagamento via boleto e cartão).", "5-1": "Define se a tela de pagamento deve solicitar que o pagador informe um endereço de entrega. Há dois possíveis valores:\n\n- <code>true</code> (equivale a \"sim\") ou;\n- <code>false</code> (equivale a \"não\").", "4-1": "Define a data de vencimento da tela de pagamento e do próprio boleto, caso esta seja a forma de pagamento escolhida.\n<strong class=\"descricao-atributo\"><span class=\"atributo\">Formato: YYYY-MM-DD</span></strong>", "3-1": "Define uma mensagem para o pagador. A mensagem aparece na tela de pagamento, nos e-mails relacionados à cobrança e no boleto, caso esta seja a forma de pagamento escolhida.\n<strong class=\"descricao-atributo\"><span class=\"atributo\">Mínimo de 3 e máximo de 80 caracteres.</span></strong>", "1-1": "Define um desconto, em reais, caso o pagador escolha cartão de crédito como forma de pagamento (informar valor Inteiro).\n<strong class=\"descricao-atributo\"><span class=\"atributo\">5000 equivale a R$ 50,00</span></strong>", "0-1": "Define um desconto, em reais, caso o pagador escolha boleto bancário como forma de pagamento (informar valor inteiro, em reais).\n<strong class=\"descricao-atributo\"><span class=\"atributo\">5000 equivale a R$ 50,00</span></strong>", "2-0": "<code>conditional_discount</code>", "2-1": "Define desconto condicional que é válido até uma data específica. Se o pagamento não for efetuado até aquela data, o desconto é invalidado.\n\n<span class=\"tab1\">*Atributos de conditional_discount*</span>\n\n<div class=\"tab2\">\n<strong class=\"descricao-atributo\"><span class=\"atributo\">type<strong class=\"atributo-obrigatorio\">*</strong></span>, // Tipo do desconto (String). Valores permitidos:\n<code>currency</code>: o desconto será informado em centavos;\n<code>percentage</code>: o desconto será informado em porcentagem.</strong>\n</div>\n\n<div class=\"tab2\">\n<strong class=\"descricao-atributo\"><span class=\"atributo\">value<strong class=\"atributo-obrigatorio\">*</strong></span>, // Valor do desconto (Integer). Se o tipo do desconto for <code>currency</code>, o valor desta tag deverá ser informada pelo integrador em centavos (ou seja, 500 equivale a R$ 5,00). Caso o tipo do desconto seja <code>percentage</code>, o valor deverá ser multiplicado por 100 (ou seja, 1500 equivale a 15%). Exemplos:\n1) <code>currency</code> // deve ser informado em centavos, ou seja, se o desconto será de R$ 5,99, o integrador deve informar <code>599</code>;\n2) <code>percentage</code> // deve ser informado em centavos, ou seja, se o desconto é de 15%, o integrador deve informar <code>1500</code>.</strong></div>\n\n<div class=\"tab2\">\n<strong class=\"descricao-atributo\"><span class=\"atributo\">until_date<strong class=\"atributo-obrigatorio\">*</strong></span>, // Data máxima que o desconto será concedido. (String). </strong><strong class=\"descricao-atributo\"><span class=\"atributo\">Formato: YYYY-MM-DD</span></strong></div>", "2-2": "Não", "2-3": "Object" }, "cols": 4, "rows": 7 } [/block] <br> Ao consumir o endpoint <code>/charge/:id/link</code>, ou através do Playground, a cobrança ganha o status <code>link</code>. Desta forma, o integrador consegue distinguir cobranças comuns que ainda não tiveram forma de pagamento definida (status <code>new</code>) de cobranças que foram associadas a um link de pagamento (status <code>link</code>). O integrador só precisa redirecionar o pagador para o link retornado na tag <code>payment_url</code> e todo o resto será realizado na tela de pagamento da Gerencianet. A seguir, através da aba "Dados de Entrada", um JSON simples que pode ser utilizado para criar o link de pagamento. Além disso, é possível observar a saída prevista e o schema de validação com todas as tags (obrigatórias e opcionais) disponíveis para este método. Lembrando que também é preciso informar o parâmetro de entrada <code>charge_id</code> da transação criada: [block:code] { "codes": [ { "code": "{\n \"message\": \"Escreva aqui, se quiser, uma mensagem ao seu cliente, limite de 80 caracteres\",\n \"payment_method\": \"all\",\n \"expire_at\": \"2016-12-20\",\n \"request_delivery_address\": false,\n \"billet_discount\": 5000,\n \"card_discount\": 3000\n}", "language": "json", "name": "Dados de Entrada" }, { "code": "{\n \"code\": 200,\n \"data\": {\n \"charge_id\": 148003,\n \"status\": \"link\",\n \"total\": 5990,\n \"custom_id\": null,\n \"payment_url\": \"https://pagamento.gerencianet.com.br/:identificador\",\n \"payment_method\": \"all\",\n \"created_at\": \"2016-12-14 11:31:37\"\n }\n}", "language": "json", "name": "Dados de Saída" }, { "code": "{\n \"id\": \"/ChargeLink\",\n \"type\": \"object\",\n \"properties\": {\n \"billet_discount\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 99999999\n },\n \"card_discount\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 99999999\n },\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 3,\n \"maxLength\": 80\n },\n \"expire_at\": {\n \"type\": \"string\",\n \"pattern\": \"^[12][0-9]{3}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$\"\n },\n \"request_delivery_address\": {\n \"type\": \"boolean\"\n },\n \"payment_method\": {\n \"enum\": [\n \"banking_billet\",\n \"credit_card\",\n \"all\"\n ]\n }\n },\n \"required\": [\n \"request_delivery_address\",\n \"expire_at\",\n \"payment_method\"\n ]\n}", "language": "json", "name": "Schema" } ] } [/block] Esse JSON, presente na aba "Dados de Entrada", define as seguintes informações ao criar o link de pagamento: - <code>message</code>: define uma mensagem para o pagador. A mensagem aparece na tela de pagamento, nos e-mails relacionados à cobrança e no boleto, caso esta seja a forma de pagamento escolhida (máximo de 80 caracteres); - <code>payment_method</code>: define as formas de pagamento que devem ficar disponíveis na tela (<code>banking_billet</code>, <code>credit_card</code> ou <code>all</code>); - <code>expire_at</code>: define a data de vencimento da tela de pagamento e do próprio boleto, caso esta seja a forma de pagamento escolhida; - <code>request_delivery_address</code>: define se a tela de pagamento deve solicitar que o pagador informe um endereço de entrega (<code>true</code> ou <code>false</code>); - <code>billet_discount</code>: define um desconto, em centavos, caso o pagador escolha boleto bancário como forma de pagamento (informar valor Inteiro); - <code>card_discount</code>: define um desconto, em centavos, caso o pagador escolha cartão de crédito como forma de pagamento (informar valor Inteiro). <br> [block:callout] { "type": "info", "title": "Relação de todos os possíveis status de uma transação", "body": "Todas as transações possuem status, que representa a \"situação\" dessa transação. Portanto, é importante conhecer os possíveis status na API para fornecer as devidas tratativas em seu sistema.\n\nConfira <a href=\"https://dev.gerencianet.com.br/docs/transacoes\" target=\"_blank\" title=\"Link Interno\">neste link</a> todos os detalhes dos possíveis status das transações." } [/block] [block:callout] { "type": "warning", "body": "As notificações permitem que você seja informado quando uma transação tiver seu status alterado. Dessa forma, você poderá identificar quando uma cobrança for paga, por exemplo.\n\nConfira <a href=\"https://dev.gerencianet.com.br/docs/notificacoes-recebendo\" target=\"_blank\" title=\"Link Interno\">neste link</a> todos os detalhes sobre como implementar a sua URL de notificação.", "title": "Callbacks (notificações) das transações da API para seu sistema" } [/block] <br> ## b) Estrutura hierárquica dos atributos do Schema que podem ser utilizados: <pre>"id": "/ChargeLink" "billet_discount" "card_discount" "conditional_discount" "type" "percentage", "currency" "value" "until_date" "message" "expire_at" "request_delivery_address" "payment_method" "banking_billet" "credit_card" "all"</pre> Para verificar mais detalhes, <a href="https://dev.gerencianet.com.br/docs/playground-transacoes#charge_id_link" target="_blank" title="Link Interno">acesse aqui</a> e explore em nosso Playground. <br> ## c) Personalizando sua tela de pagamento: É possível definir uma cor e um logo para sua tela. Para isso, <a href="https://gerencianet.com.br/#login" target="_blank" title="Logue em sua conta Gerencianet">logue em sua conta Gerencianet</a> e acesse o menu <code>Minha Conta > Tela de Pagamento</code>. Mesmo que prefira utilizar sua própria tela, as informações definidas aqui serão utilizadas também nos e-mails disparados pela API. Então recomendamos que faça a personalização de qualquer forma. ## d) Testando em ambiente de testes (Playground): Para criar um link de pagamento, primeiro é necessário criar uma cobrança na API, consumindo o endpoint <code>POST /v1/charge</code>. Este endpoint retorna, dentre outras informações, um identificador para a cobrança. O status inicial de uma cobrança é <code>new</code>: [block:code] { "codes": [ { "code": "{ \n \"items\": [\n {\n \"name\": \"Produto exemplo\",\n \"value\": 1000,\n \"amount\": 1\n }\n ]\n}", "language": "json", "name": "Entrada" } ] } [/block] <br> Logo abaixo, os dados de saída previstos de acordo com a entrada realizada acima: [block:code] { "codes": [ { "code": "{ \n \"code\":200,\n \"data\":{ \n \"charge_id\":121062,\n \"status\":\"new\",\n \"total\":1000,\n \"custom_id\":null,\n \"created_at\":\"2016-10-31 10:43:57\"\n }\n}", "language": "json", "name": "Saída" } ] } [/block] <br> Conhecendo o identificador da cobrança, basta consumir o endpoint <code>POST /v1/charge/:id/link</code> para gerar um link de pagamento. <br> <hr> # 3. Outros endpoints e métodos Existem outros endpoints e métodos relacionados a link de pagamento que estão disponíveis na API e podem ser explorados pelo integrador. Confira a relação completa: - [Alterar determinados parâmetros/atributos de um link de pagamento existente](https://dev.gerencianet.com.br/v1/docs/link-outros-endpoints#section-1-alterar-determinados-par-metros-atributos-de-um-link-de-pagamento-existente) - [Cancelar determinada transação](https://dev.gerencianet.com.br/v1/docs/link-outros-endpoints#section-2-cancelar-determinada-transa-o) - [Alterar URL de notificação (notification_url) e/ou custom_id de transação](https://dev.gerencianet.com.br/v1/docs/link-outros-endpoints#section-3-alterar-url-de-notifica-o-notification_url-e-ou-custom_id-de-transa-o) - [Acrescentar informações ao histórico da transação](https://dev.gerencianet.com.br/v1/docs/link-outros-endpoints#section-4-acrescentar-informa-es-ao-hist-rico-da-transa-o) - [Retornar informações sobre transação](https://dev.gerencianet.com.br/v1/docs/link-outros-endpoints#section-5-retornar-informa-es-sobre-transa-o) <br> <hr> # 4. Vídeo: Criando transação via Playground (ambiente de testes/sandbox) Pensando em oferecer novos meios de transmitir informações, a Gerencianet disponibiliza o vídeo a seguir com o objetivo de explicar, de maneira clara e objetiva, como criar uma transação via playground (sandbox). [block:html] { "html": "<iframe width=\"560\" height=\"315\" src=\"https://www.youtube.com/embed/ylqJUpHqwfY\" frameborder=\"0\" allowfullscreen></iframe>" } [/block] <br> [block:callout] { "type": "info", "title": "Curso Completo de Integração com a API Gerencianet", "body": "Para acesso as demais aulas, de outros assuntos, acesse a página <a href=\"https://dev.gerencianet.com.br/docs/curso-online-gerencianet\" title=\"Link Interno\">Curso Online de Integrações</a>." } [/block]

Documentação API Gerencianet - Boleto Registrado e Pagamentos Online

** Atualização TLS

Visão Geral da API

Ambiente de Testes

Instalação da API (SDK's)

Pagar com Boleto

Pagar com Cartão

Assinaturas (Recorrência)

Carnês

Link de Pagamento

Marketplace

Checkout via Lightbox

Notificações (callbacks)

Sistemas Integrados

Módulos e Plugins

Exemplos de Integrações

Vídeos sobre Integrações

Outros Recursos

Autenticação e Endpoints

Fluxos de Processos

Últimas Novidades

Dúvidas?