Criando link de pagamento na API Gerencianet - Maykon Silveira

Como Criar um link de pagamento na API Gerencianet treinamento completo - Maykon Silveira



Criando link de pagamento

 

Passo a passo para gerar uma cobrança de link de pagamento na API Gerencianet


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, informando o item/produto/serviço, valor, quantidade, etc;

  2. 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·
 
<?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

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.

 

 

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:

{
  "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_billetcredit_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:

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

 

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

{  
   "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 , Como Criar um link de pagamento na API Gerencianet treinamento completo, Como Gerar Bolix API Gerencianet, Glossário com os termos mais comuns relacionados a API e Integrações no gerencianet, Cursos online completos e gratuitos, curso php 8, curso node.js, curso de react, curso de react.js, curso de arduino, curso de html, curso de css, curso javascript, Maykon Silveira, criando api com Maykon Silveira, curso de sheep php, sheep php, Gerando Boletos com QRCODE PIX no gerencianet treinamento completo


Maykon Silveira

Maykon Silveira

CEO / FOUNDER / WEBTEC TECHNOLOGIES
Programador: PHP - HTML - CSS - JAVASCRIPT - MYSQLI - ANDROID - APPLE - MOBILE
Criador de Games: XBOX - PLAYSTATION - MOBILE - COMPUTADORES - EDIÇÃO DE VÍDEOS
Marketing: GOOGLE ADWORDS- FACEBOOK ADS - YOUTUBE
Experiência na área de programação desde 2007.

Alguns Depoimentos dos Alunos Maykon Silveira EAD

Vejam o que os alunos da EAD Maykon Silveira estão falando sobre os cursos.

Política de Privacidade Termos e Condições