Playground: Transações

Para acessar o ambiente de testes você precisa de uma conta Gerencianet. <a href="https://gerencianet.com.br/#abrirconta" title="Cadastro ao nosso sistema, seja nosso cliente" target="_blank">Crie sua conta</a>. O Playground (também chamado de "sandbox") é um ambiente de desenvolvimento/testes no qual o integrador, independente da operação a ser realizada, pode utilizar para conhecer o mecanismo e o fluxo de pagamento em um ambiente 100% de teste e descomplicado. [Conheça mais](https://dev.gerencianet.com.br/docs/playground) sobre o Playground oferecido pela Gerencianet. A criação de uma cobrança via integração com a API da Gerencianet possui duas etapas: 1. Primeiro [gera a transação (ou cobrança)](https://dev.gerencianet.com.br/docs/playground-transacoes#charge) através do endpoint <code>POST /v1/charge</code>; 2. Por fim, [associa a transação gerada à uma forma de pagamento](https://dev.gerencianet.com.br/docs/playground-transacoes#charge_id_pay) através do endpoint <code>POST /v1/charge/:id/pay</code>. Após utilizar o endpoint <code>POST /v1/charge</code>, a transação já estará criada e, a partir deste momento, será possível associá-la à forma de pagamento como boleto bancário ou cartão de crédito. A seguir, confira todos os endpoints presentes em nosso Playground, dentro da modalidade de "Transações": <ul><li><div class=""><span class="post">POST</span> <a href="https://dev.gerencianet.com.br/docs/playground-transacoes#charge">/v1/charge</a> <em>(criar nova transação)</em></div></li><li><div class=""><span class="get">GET</span> <a href="https://dev.gerencianet.com.br/docs/playground-transacoes#charge_id">/v1/charge/:id</a> <em>(retornar informações de transação existente)</em></div></li><li><div class=""><span class="put">PUT</span> <a href="https://dev.gerencianet.com.br/docs/playground-transacoes#charge_id_metadata">/v1/charge/:id/metadata</a> <em>(incluir "notification_url" e "custom_id" em uma transação existente)</em></div></li><li><div class=""><span class="put">PUT</span> <a href="https://dev.gerencianet.com.br/docs/playground-transacoes#charge_id_billet">/v1/charge/:id/billet</a> <em>(alterar data de vencimento de uma transação existente)</em></div></li><li><div class=""><span class="put">PUT</span> <a href="https://dev.gerencianet.com.br/docs/playground-transacoes#charge_id_cancel">/v1/charge/:id/cancel</a> <em>(cancelar uma transação existente)</em></div></li><li><div class=""><span class="post">POST</span> <a href="https://dev.gerencianet.com.br/docs/playground-transacoes#charge_id_pay">/v1/charge/:id/pay</a> <em>(associa método de pagamento à uma transação já criada)</em></div></li><li><div class=""><span class="post">POST</span> <a href="https://dev.gerencianet.com.br/docs/playground-transacoes#charge_id_billet_resend">/v1/charge/:id/billet/resend</a> <em>(reenvio do boleto bancário para o email desejado)</em></div></li><li><div class=""><span class="post">POST</span> <a href="https://dev.gerencianet.com.br/docs/playground-transacoes#charge_id_history">/v1/charge/:id/history</a> <em>(acrescentar descrição ao histórico de uma transação)</em></div></li><li><div class=""><span class="post">POST</span> <a href="https://dev.gerencianet.com.br/docs/playground-transacoes#charge_id_link">/v1/charge/:id/link</a> <em>(retorna um link para uma tela de pagamento da Gerencianet)</em></div></li><li><div class=""><span class="put">PUT</span> <a href="https://dev.gerencianet.com.br/docs/playground-transacoes#charge_id_link">/v1/charge/:id/link</a> <em>(alterar determinados parâmetros/atributos de um link de pagamento existente</em></div></li></ul> <br> <hr> <div class="distancia_top"><a name="charge"><span class="post">POST</span></a><strong class="text-endpoint">/v1/charge</strong></div> Permite criar uma nova transação; retorna um código identificador da transação denominado <code>charge_id</code>. Somente após a geração da transação (isto é, depois de gerada a cobrança) é que será associada a um método de pagamento (boleto bancário ou cartão de crédito). Na imagem a seguir, é possível observar a tela de nosso ambiente de testes no qual constam os recursos atrelados ao método <code>POST /v1/charge</code> que estão disponíveis para utilização: [block:image] { "images": [ { "image": [ "https://files.readme.io/50475e5-post-v1-charge.png", "post-v1-charge.png", 1386, 366, "#eff0f0" ] } ] } [/block] A seguir, um JSON simples que pode ser utilizado para criar uma cobrança (ainda sem forma de pagamento definida) no Playground. 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: [block:code] { "codes": [ { "code": "{\n \"items\": [\n {\n \"name\": \"Meu Produto\",\n \"value\": 8900,\n \"amount\": 1\n }\n ]\n}", "language": "json", "name": "Dados de Entrada" }, { "code": "{\n \"code\": 200, // retorno HTTP \"200\" informando que o pedido foi bem sucedido\n \"data\": {\n \"charge_id\": numero_charge_id, // número da ID referente à transação gerada\n \"status\": \"new\", // cobrança gerada, aguardando definição da forma de pagamento\n \"total\": 8900, // valor total da transação (em centavos, sendo 8900 = R$89,00)\n \"custom_id\": null, // identificador próprio opcional\n \"created_at\": \"2016-06-24 14:58:46\" // data e hora da criação da transação\n }\n}", "language": "json", "name": "Dados de Saída" }, { "code": "{\n \"id\": \"/Charge\",\n \"type\": \"object\",\n \"properties\": {\n \"items\": {\n \"id\": \"/MarketplaceItem\",\n \"type\": \"array\",\n \"minItems\": 1,\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 255,\n \"pattern\": \"^[^<>]+$\"\n },\n \"value\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"amount\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"exclusiveMinimum\": false\n },\n \"marketplace\": {\n \"type\": \"object\",\n \"properties\": {\n \"repasses\": {\n \"id\": \"/Repass\",\n \"type\": \"array\",\n \"minItems\": 1,\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"payee_code\": {\n \"type\": \"string\",\n \"pattern\": \"^[a-fA-F0-9]{32}$\"\n },\n \"percentage\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 10000\n }\n },\n \"required\": [\n \"payee_code\",\n \"percentage\"\n ]\n }\n }\n },\n \"required\": [\n \"repasses\"\n ]\n }\n },\n \"required\": [\n \"name\",\n \"value\"\n ]\n }\n },\n \"shippings\": {\n \"id\": \"/Shipping\",\n \"type\": \"array\",\n \"minItems\": 1,\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"maxLength\": 255\n },\n \"value\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"payee_code\": {\n \"type\": \"string\",\n \"pattern\": \"^[a-fA-F0-9]{32}$\"\n }\n },\n \"required\": [\n \"name\",\n \"value\"\n ]\n }\n },\n \"metadata\": {\n \"type\": \"object\",\n \"properties\": {\n \"custom_id\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"maxLength\": \"255\"\n },\n \"notification_url\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"format\": \"uri\",\n \"maxLength\": \"255\"\n }\n }\n }\n },\n \"required\": [\n \"items\"\n ]\n}", "language": "json", "name": "Schema" } ] } [/block] Esse JSON define que a cobrança deve possuir um produto de nome “Meu Produto”, valor R$ 89,00 e quantidade 1, ou seja, o valor total dessa cobrança será R$ 89,00. <br> <hr> <div class="distancia_top"><a name="charge_id"><span class="get">GET</span></a><strong class="text-endpoint">/v1/charge/:id</strong></div> Permite retornar informações de uma transação existente. Na imagem a seguir, é possível observar a tela de nosso ambiente de testes no qual constam os recursos atrelados ao método <code>GET /v1/charge/:id</code> que estão disponíveis para utilização: [block:image] { "images": [ { "image": [ "https://files.readme.io/2187fb4-get-charge-id.png", "get-charge-id.png", 1388, 122, "#f1f1f1" ] } ] } [/block] A seguir, um JSON simples que pode ser utilizado para buscar informações de alguma transação no Playground. Além disso, é possível observar a saída prevista disponível para este método: [block:code] { "codes": [ { "code": "Parâmetro de entrada: informe a \"charge_id\" da transação desejada", "language": "text", "name": "Dados de Entrada" }, { "code": "{\n \"code\": 200, // retorno HTTP \"200\" informando que o pedido foi bem sucedido\n \"data\": {\n \"charge_id\": numero_charge_id, // número da ID referente à transação gerada\n \"total\": 8900, // valor total da transação (em centavos, sendo 8900 = R$89,00)\n \"status\": \"new\", // cobrança gerada, aguardando definição da forma de pagamento\n \"custom_id\": null, // identificador próprio opcional\n \"created_at\": \"2016-06-24 14:58:46\", // data e hora da criação da transação\n \"notification_url\": null,\n \"items\": [\n {\n \"name\": \"Teste do meu produto\", // nome de seu item, produto ou serviço\n \"value\": 8900, // valor, em centavos. Por exemplo: 8900 (equivale a R$ 89,00)\n \"amount\": 1 // quantidade do item ou produto\n }\n ],\n \"history\": [ // histórico da transação numero_id\n {\n \"message\": \"Cobrança criada\", // histórico inicial da transação que foi criada\n \"created_at\": \"2016-06-24 14:58:46\" // data e hora da transação criada\n }\n ]\n }\n}", "language": "json", "name": "Dados de Saída" } ] } [/block] Ao informar o parâmetro de entrada <code>charge_id</code>, serão retornadas informações da transação existente. <br> <hr> <div class="distancia_top"><a name="charge_id_metadata"><span class="put">PUT</span></a><strong class="text-endpoint">/v1/charge/:id/metadata</strong></div> Permite incluir informações como <code>notification_url</code> e <code>custom_id</code> à uma transação existente: - <code>notification_url</code>: é um endereço de sua URL válida que receberá as notificações de mudanças de status das transações - <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. Na imagem a seguir, é possível observar a tela de nosso ambiente de testes no qual constam os recursos atrelados ao método <code>PUT /v1/charge/:id/metadata</code> que estão disponíveis para utilização: [block:image] { "images": [ { "image": [ "https://files.readme.io/42dd9a9-put-charge-metadata.png", "put-charge-metadata.png", 1386, 395, "#eeefef" ] } ] } [/block] A seguir, um JSON simples que pode ser utilizado para alterar a URL de notificação e o custom_id de uma transação já existente no Playground. 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 desejada: [block:code] { "codes": [ { "code": "{\n \"notification_url\": null,\n \"custom_id\": null\n}", "language": "json", "name": "Dados de Entrada" }, { "code": "", "language": "json", "name": "Dados de Saída" }, { "code": "{\n \"type\": \"object\",\n \"minProperties\": 1,\n \"id\": \"/ChargeMetadataUpdate\",\n \"properties\": {\n \"notification_url\": {\n \"type\": \"string\",\n \"format\": \"uri\",\n \"minLength\": \"1\",\n \"maxLength\": \"255\"\n },\n \"custom_id\": {\n \"type\": \"string\",\n \"minLength\": \"1\",\n \"maxLength\": \"255\",\n \"pattern\": \"^[a-zA-Z0-9\\\\_\\\\-\\\\s]+$\"\n }\n }\n}", "language": "json", "name": "Schema" } ] } [/block] Esse JSON permite alterar a URL de notificação e o custom_id de uma determinada transação. <br> <hr> <div class="distancia_top"><a name="charge_id_billet"><span class="put">PUT</span></a><strong class="text-endpoint">/v1/charge/:id/billet</strong></div> Permite efetuar a alteração da data de vencimento de uma transação em que a forma de pagamento é boleto bancário (<code>banking_billet</code>) e que ainda não foi paga. O formato da data de vencimento deve seguir o seguinte padrão: <code>YYYY-MM-DD</code>. Na imagem a seguir, é possível observar a tela de nosso ambiente de testes no qual constam os recursos atrelados ao método <code>PUT /v1/charge/:id/billet</code> que estão disponíveis para utilização: [block:image] { "images": [ { "image": [ "https://files.readme.io/bde9517-put-charge-id-billet.png", "put-charge-id-billet.png", 1385, 393, "#eff0f0" ] } ] } [/block] A seguir, um JSON simples que pode ser utilizado para alterar a data de vencimento de um boleto no Playground. 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 desejada: [block:code] { "codes": [ { "code": "{\n \"expire_at\": \"2018-12-30\"\n}", "language": "json", "name": "Dados de Entrada" }, { "code": "{\n \"code\": 200 // retorno HTTP \"200\" informando que o pedido foi bem sucedido\n}", "language": "json", "name": "Dados de Saída" }, { "code": "{\n \"id\": \"/ChargeBilletUpdate\",\n \"type\": \"object\",\n \"properties\": {\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 },\n \"required\": [\n \"expire_at\"\n ]\n}", "language": "json", "name": "Schema" } ] } [/block] Esse JSON realiza a alteração da data de vencimento de um boleto no Playground, alterando o vencimento do referido boleto para 30/12/2018. <br> <hr> <div class="distancia_top"><a name="charge_id_cancel"><span class="put">PUT</span></a><strong class="text-endpoint">/v1/charge/:id/cancel</strong></div> Através deste *endpoint* é possível cancelar uma transação criada. Somente transações com status <code>new</code> (novo) ou <code>waiting</code> (aguardando) podem ser canceladas. A partir do momento que uma transação é cancelada, existe apenas uma condição para que esse status seja alterado novamente: se o cliente imprimir o boleto antes do integrador cancelar a transação, ele poderá realizar o pagamento normalmente em uma agência bancária. Neste caso, o integrador e o pagador recebem a confirmação do pagamento como já acontece normalmente e o status da cobrança é alterado de <code>canceled</code> (cancelado) para <code>paid</code> (pago). Na imagem a seguir, é possível observar a tela de nosso ambiente de testes no qual constam os recursos atrelados ao método <code>PUT /v1/charge/:id/cancel</code> que estão disponíveis para utilização: [block:image] { "images": [ { "image": [ "https://files.readme.io/ffdc8c0-put-charge-id-cancel.png", "put-charge-id-cancel.png", 1385, 123, "#f1f1f1" ] } ] } [/block] A seguir, um JSON simples que pode ser utilizado para cancelar uma transação criada em Playground. Além disso, é possível observar a saída prevista disponível para este método. Lembrando que também é preciso informar o parâmetro de entrada <code>charge_id</code> da transação desejada: [block:code] { "codes": [ { "code": "Parâmetro de entrada: informe a \"charge_id\" da transação desejada", "language": "text", "name": "Dados de Entrada" }, { "code": "{\n \"code\": 200 // retorno HTTP \"200\" informando que o pedido foi bem sucedido\n}", "language": "json", "name": "Dados de Saída" } ] } [/block] Esse JSON realiza o cancelamento de uma determinada transação criada no Playground. <br> <hr> <div class="distancia_top"><a name="charge_id_pay"><span class="post">POST</span></a><strong class="text-endpoint">/v1/charge/:id/pay</strong></div> Permite associar um método de pagamento à uma transação já criada. Após gerar uma transação através do endpoint <code>POST /v1/charge</code>, esta fica classificada com o status de <code>new</code> (novo), ou seja, uma nova transação foi gerada, porém, nenhum método de pagamento foi atribuído a ela. Para definir uma forma de pagamento para a transação criada, o integrador pode escolher entre <code>banking_billet</code> ou <code>credit_card</code> (boleto bancário e cartão de crédito, respectivamente). - *Boleto Bancário*: a transação passa por um ciclo de alteração de status, sendo criada inicialmente com o status de <code>new</code> (novo) e, ao definir a forma de pagamento, o status passará a ser <code>waiting</code> (aguardando). Isso significa que o boleto foi gerado com sucesso, mas ainda não foi pago. Ao escolher boleto, a resposta do consumo já terá a linha digitável, código de barras e link para acesso ao boleto; - *Cartão de Crédito*: a principal diferença para o boleto está relacionada à necessidade de utilização de um código denominado “payment_token”. No Playground, você pode gerar seu token clicando no botão *“Gerar payment token”* e colá-lo dentro do atributo <code>payment_token</code>. Já no ambiente de produção, a obtenção do "payment_token" se dá pelo consumo de um código Javascript disponível em sua conta. Na imagem a seguir, é possível observar a tela de nosso ambiente de testes no qual constam os recursos atrelados ao método <code>POST /v1/charge/:id/pay</code> que estão disponíveis para utilização: [block:image] { "images": [ { "image": [ "https://files.readme.io/dc9a82b-post-charge-id-pay.png", "post-charge-id-pay.png", 1387, 434, "#edefef" ] } ] } [/block] A seguir, um JSON simples que pode ser utilizado para associar um método de pagamento à uma transação já criada em Playground - o integrador pode escolher entre <code>banking_billet</code> ou <code>credit_card</code>. 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 desejada: [block:code] { "codes": [ { "code": "{\n \"payment\": {\n \"credit_card\": {\n \"customer\": {\n \"name\": \"Gorbadoc Oldbuck\",\n \"cpf\": \"94271564656\",\n \"email\": \"email_do_cliente@servidor.com.br\",\n \"birth\": \"1990-08-29\",\n \"phone_number\": \"5144916523\"\n },\n \"installments\": 1,\n \"payment_token\": \"\",\n \"billing_address\": {\n \"street\": \"Avenida Juscelino Kubitschek\",\n \"number\": \"909\",\n \"neighborhood\": \"Bauxita\",\n \"zipcode\": \"35400000\",\n \"city\": \"Ouro Preto\",\n \"complement\": \"\",\n \"state\": \"MG\"\n }\n }\n }\n}", "language": "json", "name": "Dados de Entrada (cartão)" }, { "code": "{\n \"payment\": {\n \"banking_billet\": {\n \"customer\": {\n \"name\": \"Gorbadoc Oldbuck\",\n \"cpf\": \"94271564656\",\n \"email\": \"email_do_cliente@servidor.com.br\",\n \"phone_number\": \"5144916523\",\n \"address\": {\n \"street\": \"Avenida Juscelino Kubitschek\",\n \"number\": \"909\",\n \"neighborhood\": \"Bauxita\",\n \"zipcode\": \"35400000\",\n \"city\": \"Ouro Preto\",\n \"complement\": \"\",\n \"state\": \"MG\"\n }\n },\n \"expire_at\": \"2018-12-30\",\n \"configurations\": {\n \"fine\": 200,\n \"interest\": 33\n },\n \"message\": \"Este é um espaço de até 80 caracteres para informar algo a seu cliente\"\n }\n }\n}", "language": "json", "name": "Dados de Entrada (boleto)" }, { "code": "{\n \"code\": 200, // retorno HTTP \"200\" informando que o pedido foi bem sucedido\n \"data\": {\n \"installments\": 1, // número de parcelas em que o pagamento deve ser dividido\n \"installment_value\": 8900, // valor da parcela. Por exemplo: 8900 (equivale a R$ 89,00)\n \"charge_id\": numero_charge_id, // número da ID referente à transação gerada\n \"status\": \"waiting\", // forma de pagamento selecionada, aguardando a confirmação do pagamento (\"waiting\" equivale a \"aguardando\")\n \"total\": 8900, // valor, em centavos. Por exemplo: 8900 (equivale a R$ 89,00)\n \"payment\": \"credit_card\" // forma de pagamento associada à esta transação (\"credit_card\" equivale a \"cartão de crédito\")\n }\n}", "language": "json", "name": "Dados de Saída (cartão)" }, { "code": "{\n \"code\": 200, // retorno HTTP \"200\" informando que o pedido foi bem sucedido\n \"data\": {\n \"barcode\": \"linha_digitavel_do_boleto\", // linha digitável do boleto\n \"link\": \"link_para_acesso_ao_boleto\", // link do boleto gerado\n \"expire_at\": \"2018-12-30\", // data de vencimento do boleto no seguinte formato: 2018-12-30 (ou seja, equivale a 30/12/2018)\n \"charge_id\": numero_charge_id, // número da ID referente à transação gerada\n \"status\": \"waiting\", // forma de pagamento selecionada, aguardando a confirmação do pagamento (\"waiting\" equivale a \"aguardando\")\n \"total\": 8900, // valor, em centavos. Por exemplo: 8900 (equivale a R$ 89,00)\n \"payment\": \"banking_billet\" // forma de pagamento associada à esta transação (\"banking_billet\" equivale a \"boleto bancário\")\n }\n}", "language": "json", "name": "Dados de Saída (boleto)" }, { "code": "{\n \"type\": \"object\",\n \"id\": \"/Pay\",\n \"properties\": {\n \"payment\": {\n \"type\": \"object\",\n \"maxProperties\": 1,\n \"minProperties\": 1,\n \"properties\": {\n \"banking_billet\": {\n \"type\": \"object\",\n \"id\": \"/Billet\",\n \"properties\": {\n \"customer\": {\n \"type\": \"object\",\n \"id\": \"/BasicCustomer\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 255,\n \"pattern\": \"^[ ]*(.+[ ]+)+.+[ ]*$\"\n },\n \"cpf\": {\n \"type\": \"string\",\n \"minLength\": 11,\n \"maxLength\": 11\n },\n \"email\": {\n \"type\": \"string\",\n \"maxLength\": 255,\n \"pattern\": \"^[A-Za-z0-9_\\\\-]+(?:[.][A-Za-z0-9_\\\\-]+)*@[A-Za-z0-9_]+(?:[-.][A-Za-z0-9_]+)*\\\\.[A-Za-z0-9_]+$\"\n },\n \"phone_number\": {\n \"type\": \"string\",\n \"pattern\": \"^[1-9]{2}9?[0-9]{8}$\"\n },\n \"birth\": {\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 \"address\": {\n \"type\": \"object\",\n \"id\": \"/Address\",\n \"properties\": {\n \"street\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 200\n },\n \"number\": {\n \"type\": [\n \"string\",\n \"integer\"\n ],\n \"minLength\": 1,\n \"maxLength\": 55\n },\n \"neighborhood\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 255\n },\n \"zipcode\": {\n \"type\": \"string\",\n \"pattern\": \"^[0-9]{8}$\"\n },\n \"city\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 255\n },\n \"complement\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"minLength\": 0,\n \"maxLength\": 45\n },\n \"state\": {\n \"type\": \"string\",\n \"pattern\": \"^(?:A[CLPM]|BA|CE|DF|ES|GO|M[ATSG]|P[RBAEI]|R[JNSOR]|S[CEP]|TO)$\"\n }\n },\n \"required\": [\n \"street\",\n \"number\",\n \"neighborhood\",\n \"zipcode\",\n \"city\",\n \"state\"\n ]\n },\n \"juridical_person\": {\n \"type\": \"object\",\n \"id\": \"/JuridicalPerson\",\n \"properties\": {\n \"corporate_name\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 255,\n \"pattern\": \"^[ ]*(.+[ ]+)+.+[ ]*$\"\n },\n \"cnpj\": {\n \"type\": \"string\",\n \"minLength\": 14,\n \"maxLength\": 14\n }\n },\n \"required\": [\n \"corporate_name\",\n \"cnpj\"\n ]\n }\n },\n \"required\": [\n \"phone_number\"\n ]\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 \"discount\": {\n \"type\": \"object\",\n \"id\": \"/Discount\",\n \"properties\": {\n \"type\": {\n \"type\": \"string\",\n \"enum\": [\n \"percentage\",\n \"currency\"\n ]\n },\n \"value\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"required\": [\n \"type\",\n \"value\"\n ]\n },\n \"instructions\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"maxItems\": 4,\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 90\n }\n },\n \"configurations\": {\n \"type\": \"object\",\n \"minProperties\": 1,\n \"properties\": {\n \"fine\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 1000\n },\n \"interest\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 330\n }\n }\n },\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 3,\n \"maxLength\": 80\n }\n },\n \"required\": [\n \"customer\",\n \"expire_at\"\n ]\n },\n \"credit_card\": {\n \"type\": \"object\",\n \"id\": \"/CreditCard\",\n \"properties\": {\n \"customer\": {\n \"type\": \"object\",\n \"id\": \"/FullCustomer\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 255,\n \"pattern\": \"^[ ]*(.+[ ]+)+.+[ ]*$\"\n },\n \"cpf\": {\n \"type\": \"string\",\n \"minLength\": 11,\n \"maxLength\": 11\n },\n \"email\": {\n \"type\": \"string\",\n \"maxLength\": 255,\n \"pattern\": \"^[A-Za-z0-9_\\\\-]+(?:[.][A-Za-z0-9_\\\\-]+)*@[A-Za-z0-9_]+(?:[-.][A-Za-z0-9_]+)*\\\\.[A-Za-z0-9_]+$\"\n },\n \"phone_number\": {\n \"type\": \"string\",\n \"pattern\": \"^[1-9]{2}9?[0-9]{8}$\"\n },\n \"birth\": {\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 \"address\": {\n \"type\": \"object\",\n \"id\": \"/Address\",\n \"properties\": {\n \"street\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 200\n },\n \"number\": {\n \"type\": [\n \"string\",\n \"integer\"\n ],\n \"minLength\": 1,\n \"maxLength\": 55\n },\n \"neighborhood\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 255\n },\n \"zipcode\": {\n \"type\": \"string\",\n \"pattern\": \"^[0-9]{8}$\"\n },\n \"city\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 255\n },\n \"complement\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"minLength\": 0,\n \"maxLength\": 45\n },\n \"state\": {\n \"type\": \"string\",\n \"pattern\": \"^(?:A[CLPM]|BA|CE|DF|ES|GO|M[ATSG]|P[RBAEI]|R[JNSOR]|S[CEP]|TO)$\"\n }\n },\n \"required\": [\n \"street\",\n \"number\",\n \"neighborhood\",\n \"zipcode\",\n \"city\",\n \"state\"\n ]\n },\n \"juridical_person\": {\n \"type\": \"object\",\n \"id\": \"/JuridicalPerson\",\n \"properties\": {\n \"corporate_name\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 255,\n \"pattern\": \"^[ ]*(.+[ ]+)+.+[ ]*$\"\n },\n \"cnpj\": {\n \"type\": \"string\",\n \"minLength\": 14,\n \"maxLength\": 14\n }\n },\n \"required\": [\n \"corporate_name\",\n \"cnpj\"\n ]\n }\n },\n \"required\": [\n \"email\",\n \"phone_number\",\n \"birth\"\n ]\n },\n \"installments\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 12,\n \"exclusiveMinimum\": false,\n \"exclusiveMaximum\": false\n },\n \"discount\": {\n \"type\": \"object\",\n \"id\": \"/Discount\",\n \"properties\": {\n \"type\": {\n \"type\": \"string\",\n \"enum\": [\n \"percentage\",\n \"currency\"\n ]\n },\n \"value\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"required\": [\n \"type\",\n \"value\"\n ]\n },\n \"billing_address\": {\n \"type\": \"object\",\n \"id\": \"/Address\",\n \"properties\": {\n \"street\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 200\n },\n \"number\": {\n \"type\": [\n \"string\",\n \"integer\"\n ],\n \"minLength\": 1,\n \"maxLength\": 55\n },\n \"neighborhood\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 255\n },\n \"zipcode\": {\n \"type\": \"string\",\n \"pattern\": \"^[0-9]{8}$\"\n },\n \"city\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 255\n },\n \"complement\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"minLength\": 0,\n \"maxLength\": 45\n },\n \"state\": {\n \"type\": \"string\",\n \"pattern\": \"^(?:A[CLPM]|BA|CE|DF|ES|GO|M[ATSG]|P[RBAEI]|R[JNSOR]|S[CEP]|TO)$\"\n }\n },\n \"required\": [\n \"street\",\n \"number\",\n \"neighborhood\",\n \"zipcode\",\n \"city\",\n \"state\"\n ]\n },\n \"payment_token\": {\n \"type\": \"string\",\n \"pattern\": \"^[a-fA-F0-9]{40}$\"\n },\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 3,\n \"maxLength\": 80\n }\n },\n \"required\": [\n \"customer\",\n \"billing_address\",\n \"payment_token\"\n ]\n }\n }\n }\n },\n \"required\": [\n \"payment\"\n ]\n}", "language": "json", "name": "Schema" } ] } [/block] Esse JSON associa uma determinada transação a uma forma de pagamento, podendo ser boleto bancário ou cartão de crédito. No caso da aba <em>"Dados de Entrada (boleto)"</em>, está sendo gerado um boleto com vencimento para 30/12/2018, estamos usando uma mensagem de até 80 caracteres para informar algo ao cliente, e se o boleto for pago após o vencimento, será cobrado 2% de multa e 0,033% de juros por dia. No caso da aba <em>"Dados de Entrada (cartão)"</em>, o <code>payment_token</code> é o token de pagamento necessário quando o pagamento é via cartão. No Playground, ele é obtido apenas clicando no botão <em>"Gerar payment token"</em> e colando dentro do atributo <code>payment_token</code>. Caso estivesse em ambiente de produção, seria obtido através de código Javascript disponível para cada conta Gerencianet - para boleto o "payment_token" não é necessário. <br> <hr> <div class="distancia_top"><a name="charge_id_billet_resend"><span class="post">POST</span></a><strong class="text-endpoint">/v1/charge/:id/billet/resend</strong></div> Permite o reenvio do boleto bancário para o e-mail desejado. Na imagem a seguir, é possível observar a tela de nosso ambiente de testes no qual constam os recursos atrelados ao método <code>POST /v1/charge/:id/billet/resend</code> que estão disponíveis para utilização: [block:image] { "images": [ { "image": [ "https://files.readme.io/a082275-post-charge-billet-resend.png", "post-charge-billet-resend.png", 1386, 396, "#eff0f0" ] } ] } [/block] A seguir, um JSON simples que pode ser utilizado para reenviar por email um boleto bancário criado em Playground. 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 desejada: [block:code] { "codes": [ { "code": "{\n \"email\": \"email_do_cliente@servidor.com.br\"\n}", "language": "json", "name": "Dados de Entrada" }, { "code": "{\n \"code\": 200 // retorno HTTP \"200\" informando que o pedido foi bem sucedido\n}", "language": "json", "name": "Dados de Saída" }, { "code": "{\n \"id\": \"/ChargeBilletResend\",\n \"type\": \"object\",\n \"properties\": {\n \"email\": {\n \"type\": \"string\",\n \"maxLength\": 255,\n \"pattern\": \"^[A-Za-z0-9_\\\\-]+(?:[.][A-Za-z0-9_\\\\-]+)*@[A-Za-z0-9_]+(?:[-.][A-Za-z0-9_]+)*\\\\.[A-Za-z0-9_]+$\"\n }\n },\n \"required\": [\n \"email\"\n ]\n}", "language": "json", "name": "Schema" } ] } [/block] Esse JSON define que o endereço "email_do_cliente@servidor.com.br" receberá uma segunda via de um determinado boleto bancário que foi criado em Playground. <br> <hr> <div class="distancia_top"><a name="charge_id_history"><span class="post">POST</span></a><strong class="text-endpoint">/v1/charge/:id/history</strong></div> O histórico de uma transação representa todas as ações que ocorreram com esta transação até o presente momento. É possível adicionar mensagens personalizadas a este histórico utilizando o endpoint <code>/v1/charge/:id/history</code>. As mensagens personalizadas não influenciam na transação em si, apenas em seu histórico. Para tal, você deve informar a <code>charge_id</code> da transação desejada. Essa descrição deve possuir no mínimo um caractere e no máximo 255 caracteres. Na imagem a seguir, é possível observar a tela de nosso ambiente de testes no qual constam os recursos atrelados ao método <code>POST /v1/charge/:id/history</code> que estão disponíveis para utilização: [block:image] { "images": [ { "image": [ "https://files.readme.io/8b7a75b-post-charge-history.png", "post-charge-history.png", 1386, 397, "#eff0f0" ] } ] } [/block] A seguir, um JSON simples que pode ser utilizado para acrescentar uma descrição a uma determinada transação no Playground. 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 desejada: [block:code] { "codes": [ { "code": "{\n \"description\": \"Camisa Polo tamanho G cor azul\"\n}", "language": "json", "name": "Dados de Entrada" }, { "code": "{\n \"code\": 200 // retorno HTTP \"200\" informando que o pedido foi bem sucedido\n}", "language": "json", "name": "Dados de Saída" }, { "code": "{\n \"type\": \"object\",\n \"id\": \"/ChargeHistory\",\n \"properties\": {\n \"description\": {\n \"type\": \"string\",\n \"maxLength\": \"255\",\n \"minLength\": \"1\"\n }\n },\n \"required\": [\n \"description\"\n ]\n}", "language": "json", "name": "Schema" } ] } [/block] Esse JSON acrescenta a descrição "Camisa Polo tamanho G cor azul" em uma determinada transação no Playground. <br> <hr> <div class="distancia_top"><a name="charge_id_link"><span class="post">POST</span></a><strong class="text-endpoint">/v1/charge/:id/link</strong></div> Permite retornar um link para uma tela de pagamento da Gerencianet. Em outras palavras, o integrador gera uma cobrança e, em seguida, ao invés de definir o pagamento via boleto bancário ou cartão de crédito, o integrador pode solicitar um link escolhendo inclusive se a tela de pagamento deve aceitar boleto, cartão ou ambos. Além disso, o integrador define um vencimento para a tela de pagamento, ou seja, após a data definida pelo integrador, o link da tela de pagamento não terá mais validade. O integrador pode definir o desconto para boleto ou cartão, e pode ainda informar se deseja coletar ou não o endereço do cliente. Essa tela de pagamento não é uma definição de pagamento como boleto ou cartão, mas sim um intermediário. É útil quando o integrador não deseja implementar sua própria tela de pagamento, por exemplo. Na imagem a seguir, é possível observar a tela de nosso ambiente de testes no qual constam os recursos atrelados ao método <code>POST /v1/charge/:id/link</code> que estão disponíveis para utilização: [block:image] { "images": [ { "image": [ "https://files.readme.io/5719d04-post-charge-link.png", "post-charge-link.png", 1385, 396, "#eeefef" ], "caption": "" } ] } [/block] A seguir, um JSON simples que pode ser utilizado para retornar um link para uma tela de pagamento da Gerencianet. Para utilização, você deve previamente criar uma transação e, no campo <code>id</code>, fornecer o <code>charge_id</code> da transação que foi criada anteriormente. Assim, será retornado um link que permitirá ao cliente ir para uma tela de pagamento previamente configurada pelo integrador. 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 desejada e criada previamente: [block:code] { "codes": [ { "code": "{\n \"message\": \"Escreva aqui, se quiser, uma mensagem ao seu cliente, limite de 80 caracteres\",\n \"expire_at\": \"2018-12-20\",\n \"request_delivery_address\": false,\n \"payment_method\": \"all\"\n}", "language": "json", "name": "Dados de Entrada" }, { "code": "{\n \"code\": 200, // retorno HTTP \"200\" informando que o pedido foi bem sucedido\n \"data\": {\n \"charge_id\": numero_charge_id, // número da ID referente à transação gerada\n \"status\": \"new\", // cobrança gerada, aguardando definição da forma de pagamento\n \"total\": 6990, // valor total da transação (em centavos, sendo 6990 = R$69,90)\n \"custom_id\": null, // identificador próprio opcional\n \"payment_url\": \"https://pagamento.gerencianet.com.br/9726f54f-19c5-4265-9628-f69d32359348\", // link\n \"payment_method\": \"all\", // formas de pagamento permitidas (all = cartão e boleto)\n \"created_at\": \"2016-10-03 11:46:50\" // data e hora da criação da transação\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 \"format\": \"date\"\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 retornará um link que dará acesso a uma tela de pagamento. Note que esse link da tela de pagamento terá validade até 20/12/2018, não estamos solicitando o endereço de entrega de nosso cliente e a forma de pagamento permitida é boleto e cartão (que também poderia ter utilizado <code>banking_billet</code> para permitir só pagamento via boleto ou <code>credit_card</code> para somente cartão). Existem outras possibilidades, como por exemplo, concessão de desconto de acordo com a forma de pagamento, bastaria usar os atributos <code>billet_discount</code> - veja na aba "Schema" todos os atributos possíveis de serem utilizados. <br> <hr> <div class="distancia_top"><a name="charge_id_link"><span class="put">PUT</span></a><strong class="text-endpoint">/v1/charge/:id/link</strong></div> Permite atualizar (alterar) determinados parâmetros/atributos de um link de pagamento criado através do <code>POST /v1/charge/:id/link</code>, desde que não tenha ocorrido a confirmação do pagamento. Algumas informações que são passíveis de serem atualizadas: forma de pagamento, inserção de desconto e de mensagem ao cliente, data de vencimento do link de pagamento e mudança de solicitação (ou não) do endereço de entrega do comprador. Na imagem a seguir, é possível observar a tela de nosso ambiente de testes no qual constam os recursos atrelados ao método <code>PUT /v1/charge/:id/link</code> que estão disponíveis para utilização: [block:image] { "images": [ { "image": [ "https://files.readme.io/08b9e87-PUT_charge-id-link.png", "PUT_charge-id-link.png", 1387, 397, "#eff0f0" ] } ] } [/block] A seguir, um JSON simples que pode ser utilizado para atualizar (alterar) determinados parâmetros/atributos de um link de pagamento criado através do <code>POST /v1/charge/:id/link</code>, desde que não tenha ocorrido a confirmação do 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 desejada: [block:code] { "codes": [ { "code": "{\n \"expire_at\": \"2018-12-30\",\n \"request_delivery_address\": false,\n \"payment_method\": \"all\"\n}", "language": "json", "name": "Dados de Entrada" }, { "code": "{\n \"code\": 200 // retorno HTTP \"200\" informando que o pedido foi bem sucedido\n}", "language": "json", "name": "Dados de Saída" }, { "code": "{\n \"id\": \"/ChargeLinkUpdate\",\n \"type\": \"object\",\n \"properties\": {\n \"billet_discount\": {\n \"type\": [\n \"integer\",\n \"null\"\n ],\n \"minimum\": 1,\n \"maximum\": 99999999\n },\n \"card_discount\": {\n \"type\": [\n \"integer\",\n \"null\"\n ],\n \"minimum\": 1,\n \"maximum\": 99999999\n },\n \"message\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\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 \"expire_at\"\n ]\n}", "language": "json", "name": "Schema" } ] } [/block]

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

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 da API

Autenticação e Endpoints

Fluxos de Processos

Últimas Novidades

Dúvidas?