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:

Primeiramente, crie a transação, informando o item/produto/serviço, valor, quantidade, etc;
Agora, para criar o link de pagamento, informe o charge_id 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.

Bolix

Caso você tenha ativado o Bolix em sua conta Gerencianet, as cobranças geradas pelo link de pagamento já vão vir com o pix no boleto.
Mais detalhes sobre o Bolix e como ativá-lo aqui

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 charge_id, 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 new, 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 POST para a rota /v1/charge.

Caso queira, pode explorar e conhecer mais sobre este recurso usando nosso Playground.

O exemplo abaixo mostra como isto pode ser feito, utilizando as SDK's disponíveis:

PHP·

NodeJS·

Ruby·

Python·

.NET·

Java·

Delphi·

<?php
 
require __DIR__.'/../../vendor/autoload.php'; // caminho relacionado a SDK
 
use Gerencianet\Exception\GerencianetException;
use Gerencianet\Gerencianet;
 
$clientId = 'informe_seu_client_id'; // insira seu Client_Id, conforme o ambiente (Des ou Prod)
$clientSecret = 'informe_seu_client_secret'; // insira seu Client_Secret, conforme o ambiente (Des ou Prod)
 
$options = [
  'client_id' => $clientId,
  'client_secret' => $clientSecret,
  'sandbox' => true // altere conforme o ambiente (true = Homologação e false = producao)
];
 
$item_1 = [
    'name' => 'Item 1', // nome do item, produto ou serviço
    'amount' => 1, // quantidade
    'value' => 1000 // valor (1000 = R$ 10,00) (Obs: É possível a criação de itens com valores negativos. Porém, o valor total da fatura deve ser superior ao valor mínimo para geração de transações.)
];
 
$item_2 = [
    'name' => 'Item 2', // nome do item, produto ou serviço
    'amount' => 2, // quantidade
    'value' => 2000 // valor (2000 = R$ 20,00)
];
 
$items =  [
    $item_1,
    $item_2
];

// Exemplo para receber notificações da alteração do status da transação.
// $metadata = ['notification_url'=>'sua_url_de_notificacao_.com.br']
// Outros detalhes em: https://dev.gerencianet.com.br/docs/notificacoes

// Como enviar seu $body com o $metadata
// $body  =  [
//    'items' => $items,
//    'metadata' => $metadata
// ];

$body  =  [
    'items' => $items
];

try {
    $api = new Gerencianet($options);
    $charge = $api->createCharge([], $body);
 
    print_r($charge);
} catch (GerencianetException $e) {
    print_r($e->code);
    print_r($e->error);
    print_r($e->errorDescription);
} catch (Exception $e) {
    print_r($e->getMessage());
}

a) Estrutura hierárquica dos atributos do Schema que podem ser utilizados:

"id": "/Charge"
    "items"
        "name"
        "value"
        "amount"
        "marketplace"
            "payee_code"
            "percentage"
    "shippings"
        "name"
        "value"
        "payee_code"
    "metadata"
        "custom_id"
        "notification_url"

Para verificar mais detalhes, acesse aqui e explore em nosso Playground.

b) Atributos que podem ser utilizados para criar uma transação:

Atributo	Descrição	Obrigatório	Tipo
`items`	Item que está sendo vendido. Uma mesma transação pode possuir ilimitados itens. Atributos de items `name` // Nome do item, produto ou serviço. Mínimo de 1 caractere e máximo de 255 caracteres (String).* `value` // Valor, em centavos. Ex: R$ 10,00 = 1000. Integer.* `amount` // Quantidade. Integer (padrão: 1)	Sim	Array
`shippings`	Determina o(s) valor(es) de frete(s) de uma transação. Uma mesma transação pode possuir ilimitados valores de frete. Atributos de shippings `name` // Rótulo do frete. Máximo de 255 caracteres. String.* `value` // Valor do frete, em centavos (1990 equivale a R$19,90). Integer.* `payeeCode`, // código da conta Gerencianet que receberá o repasse do valor total do frete - refere-se ao "identificador da conta" Gerencianet (onde localizar meu identificador?) (String)	Não	Array
`metadata`	Define dados específicos da transação. Atributos de metadata `custom_id` // 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. Máximo de 255 caracteres. String/null. `notification_url` // Endereço de sua URL válida que receberá as notificações de mudanças de status das transações. Máximo de 255 caracteres. String/null.	Não	Object

* valor obrigatório

Agora que a transação já foi criada e você já possui o charge_id, é preciso associá-lo para obter o link de pagamento.

2. Criando um link de pagamento

Para criar um link de pagamento, você precisa ter gerado a transação, ou seja, que você já tenha o identificador charge_id da cobrança, pois será necessário informá-lo.

Em seguida, basta enviar uma requisição POST para a rota /v1/charge/:id/link para gerar um link de pagamento, onde o :id corresponde ao charge_id da transação criada.

Caso queira, pode explorar e conhecer mais sobre este recurso usando nosso Playground.

O exemplo abaixo mostra como isto pode ser feito, utilizando as SDK's disponíveis:

PHP·

NodeJS·

Ruby·

Python·

.NET·

Java·

Delphi·

<?php

require __DIR__.'/../../vendor/autoload.php'; // caminho relacionado a SDK

use Gerencianet\Exception\GerencianetException;
use Gerencianet\Gerencianet;

$clientId = 'informe_seu_client_id'; // insira seu Client_Id, conforme o ambiente (Des ou Prod)
$clientSecret = 'informe_seu_client_secret'; // insira seu Client_Secret, conforme o ambiente (Des ou Prod)
 
$options = [
  'client_id' => $clientId,
  'client_secret' => $clientSecret,
  'sandbox' => true // altere conforme o ambiente (true = Homologação e false = producao)
];

// $charge_id refere-se ao ID da transação gerada anteriormente
$params = [
  'id' => $charge_id
];

$body = [
  'billet_discount' => 5000, // desconto, em reais, caso o pagador escolha boleto (5000 equivale a R$ 50,00)
  'card_discount' => 3000, // desconto, em reais, caso o pagador escolha cartão (3000 equivale a R$ 30,00)
  'message' => '', // mensagem para o pagador com até 80 caracteres
  'expire_at' => '2018-12-20', // data de vencimento da tela de pagamento e do próprio boleto
  'request_delivery_address' => false, // solicitar endereço de entrega do comprador?
  'payment_method' => 'all' // formas de pagamento disponíveis
];

try {
  $api = new Gerencianet($options);
  $response = $api->chargeLink($params, $body);
  print_r($response);
} catch (GerencianetException $e) {
  print_r($e->code);
  print_r($e->error);
  print_r($e->errorDescription);
} catch (Exception $e) {
  print_r($e->getMessage());
}

IMPORTANTE

Para se criar um "link de pagamento" (chargeLink), uma "transação" (createCharge) 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 waiting ou unpaid, o que significa que devido a tentativa de pagamento, ela já foi atrelada a um método de pagamento.

a) Atributos que podem ser utilizados para criar um link de pagamento:

Atributo	Descrição	Obrigatório	Tipo
`billet_discount`	Define um desconto, em reais, caso o pagador escolha boleto bancário como forma de pagamento (informar valor inteiro, em reais). 5000 equivale a R$ 50,00	Não	Integer
`card_discount`	Define um desconto, em reais, caso o pagador escolha cartão de crédito como forma de pagamento (informar valor Inteiro). 5000 equivale a R$ 50,00	Não	Integer
`conditional_discount`	Define desconto condicional que é válido até uma data específica. Se o pagamento não for efetuado até aquela data, o desconto é invalidado. Atributos de conditional_discount type, // Tipo do desconto (String). Valores permitidos: `currency`: o desconto será informado em centavos; `percentage`: o desconto será informado em porcentagem. value, // Valor do desconto (Integer). Se o tipo do desconto for `currency`, 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 `percentage`, o valor deverá ser multiplicado por 100 (ou seja, 1500 equivale a 15%). Exemplos: 1) `currency` // deve ser informado em centavos, ou seja, se o desconto será de R$ 5,99, o integrador deve informar `599`; 2) `percentage` // deve ser informado em centavos, ou seja, se o desconto é de 15%, o integrador deve informar `1500`. *until_date, // Data máxima que o desconto será concedido. (String). Formato: YYYY-MM-DD**	Não	Object
`message`	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ínimo de 3 e máximo de 80 caracteres.	Não	String
`expire_at`	Define a data de vencimento da tela de pagamento e do próprio boleto, caso esta seja a forma de pagamento escolhida. Formato: YYYY-MM-DD	Sim	String
`request_delivery_address`	Define se a tela de pagamento deve solicitar que o pagador informe um endereço de entrega. Há dois possíveis valores: `true` (equivale a "sim") ou; `false` (equivale a "não").	Sim	Boolean
`payment_method`	Define as formas de pagamento que devem ficar disponíveis na tela para seu cliente escolher, podendo ser: `banking_billet` (boleto bancário); `credit_card` (cartão de crédito) ou; `all` (permitir pagamento via boleto e cartão).	Sim	Object

Ao consumir o endpoint /charge/:id/link, ou através do Playground, a cobrança ganha o status link. Desta forma, o integrador consegue distinguir cobranças comuns que ainda não tiveram forma de pagamento definida (status new) de cobranças que foram associadas a um link de pagamento (status link).

O integrador só precisa redirecionar o pagador para o link retornado na tag payment_url 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 charge_id da transação criada:

Dados de Entrada·

Dados de Saída·

Schema

{
  "message": "Escreva aqui, se quiser, uma mensagem ao seu cliente, limite de 80 caracteres",
  "payment_method": "all",
  "expire_at": "2016-12-20",
  "request_delivery_address": false,
  "billet_discount": 5000,
  "card_discount": 3000
}

Esse JSON, presente na aba "Dados de Entrada", define as seguintes informações ao criar o link de pagamento:

message: 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);
payment_method: define as formas de pagamento que devem ficar disponíveis na tela (banking_billet, credit_card ou all);
expire_at: define a data de vencimento da tela de pagamento e do próprio boleto, caso esta seja a forma de pagamento escolhida;
request_delivery_address: define se a tela de pagamento deve solicitar que o pagador informe um endereço de entrega (true ou false);
billet_discount: define um desconto, em centavos, caso o pagador escolha boleto bancário como forma de pagamento (informar valor Inteiro);
card_discount: define um desconto, em centavos, caso o pagador escolha cartão de crédito como forma de pagamento (informar valor Inteiro).

Relação de todos os possíveis status de uma transação

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.

Confira neste link todos os detalhes dos possíveis status das transações.

Callbacks (notificações) das transações da API para seu sistema

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.

Confira neste link todos os detalhes sobre como implementar a sua URL de notificação.

b) Estrutura hierárquica dos atributos do Schema que podem ser utilizados:

"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"

Para verificar mais detalhes, acesse aqui e explore em nosso Playground.

c) Personalizando sua tela de pagamento:

É possível definir uma cor e um logo para sua tela. Para isso, logue em sua conta Gerencianet e acesse o menu Cobranças > Configurações na aba Comunicação.

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 POST /v1/charge. Este endpoint retorna, dentre outras informações, um identificador para a cobrança. O status inicial de uma cobrança é new:

Entrada

{   
    "items":  [
        {
            "name": "Produto exemplo",
            "value": 1000,
            "amount": 1
         }
    ]
}

Logo abaixo, os dados de saída previstos de acordo com a entrada realizada acima:

Saída

{  
   "code":200,
   "data":{  
      "charge_id":121062,
      "status":"new",
      "total":1000,
      "custom_id":null,
      "created_at":"2016-10-31 10:43:57"
   }
}

Conhecendo o identificador da cobrança, basta consumir o endpoint POST /v1/charge/:id/link para gerar um link de pagamento.

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:

Criando link de pagamento na API Gerencianet - Maykon Silveira

Descrição:

Criando link de pagamento

Bolix

1. Crie a transação

a) Estrutura hierárquica dos atributos do Schema que podem ser utilizados:

b) Atributos que podem ser utilizados para criar uma transação:

2. Criando um link de pagamento

IMPORTANTE

a) Atributos que podem ser utilizados para criar um link de pagamento:

Relação de todos os possíveis status de uma transação

Callbacks (notificações) das transações da API para seu sistema

b) Estrutura hierárquica dos atributos do Schema que podem ser utilizados:

c) Personalizando sua tela de pagamento:

d) Testando em ambiente de testes (Playground):

3. Outros endpoints e métodos

Criando link de pagamento

Bolix

1. Crie a transação

a) Estrutura hierárquica dos atributos do Schema que podem ser utilizados:

b) Atributos que podem ser utilizados para criar uma transação:

2. Criando um link de pagamento

IMPORTANTE

a) Atributos que podem ser utilizados para criar um link de pagamento:

Relação de todos os possíveis status de uma transação

Callbacks (notificações) das transações da API para seu sistema

b) Estrutura hierárquica dos atributos do Schema que podem ser utilizados:

c) Personalizando sua tela de pagamento:

d) Testando em ambiente de testes (Playground):

3. Outros endpoints e métodos

Vídeos Relacionados