&nbsp;

Ruby·

.NET·

Java·

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

Ruby·

.NET·

Java·

<?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:

Pagamento com cartão API Gerencianet Treinamento Completo - Maykon Silveira

Pagamento com cartão

Passo a passo para gerar uma cobrança de cartão de crédito na API Gerencianet

Atualmente disponibilizamos dois procedimentos para a criação de uma transação do tipo cartão de crédito, na primeira delas o titulo é criado em um passo único, assim fora convencionado como One Step. A segunda opção de criação da transação se da em dois passos, sendo assim convencionada como Two Steps. Ambos os fluxos estão detalhados a seguir:

1. Criação de transação por cartão de crédito em One Step (Um passo)

Importante

Para que a criação de transações via One Step ocorra normalmente é necessário atualizar sua SDK. Todos os arquivos necessários para tal estão disponíveis através de nosso repositório e em nossa documentação.

No caso de transações com cartão de crédito, será realizada uma etapa anterior a criação onde ocorre a transmissão (via JavaScript, no browser), de forma segura, dos dados do cartão e retornando um payment_token, e na segunda etapa seu backend envia o restante das informações da transação e o payment_token obtido na primeira etapa.

É importante frisar que não é possível efetuar pagamento com cartão de crédito sem obter o payment_token da transação, por isso, é imprescindível a realização dos procedimentos do item 1.1 deste documento (obter o payment_token), e só depois passar para o item 1.2 (que é de fato o pagamento com cartão).

1.1. Obtenção do payment_token

Inicialmente, vamos realizar a primeira etapa, que é a obtenção do payment_token. Para tal, você necessitará de um código JavaScript específico de sua conta Gerencianet. Para gerá-lo, siga os passos :

Efetue login em sua conta Gerencianet e acesse API (Lateral a esquerda)
Copie seu Identificador de Conta (veja onde)
Cole no campo abaixo e clique no botão Gerar

É importante frisar que é obtido via JavaScript, no browser, de forma segura, os dados do cartão e retorna um payment_token, que é a representação dos dados enviados.

Lembre-se que, após informar seu identificador de conta, serão gerados 2 (dois) códigos JavaScript distintos.

Copie e utilize o código referente ao ambiente desejado, atentando-se às diferenças do ambiente de "Homologação" e "Produção".

Para aplicações web, você deve copiar o script, específico da sua conta, e utilizar a nossa biblioteca Javascript, conforme o snippet abaixo. Se você possui um app mobile, confira como proceder acessando nossa página no GitHub para Android e/ou iOS.

Adicionalmente, esclarecemos que uma conta Gerencianet não possui um payment_token - ele é diferente e criado para cada cobrança gerada por cartão de crédito. Ele representa os dados do cartão do pagador e é obtido pela função getPaymentToken. Além disso, cabe frisar que o payment_token pode ser utilizado uma única vez, portanto, não é possível utilizá-lo para cobrar de forma recorrente.

a) Obtendo um "payment_token" ( getPaymentToken )

$gn.ready(function (checkout) {

  checkout.getPaymentToken(
    {
      brand: 'visa', // bandeira do cartão
      number: '4012001038443335', // número do cartão
      cvv: '123', // código de segurança
      expiration_month: '05', // mês de vencimento
      expiration_year: '2021' // ano de vencimento
    },
    function (error, response) {
      if (error) {
        // Trata o erro ocorrido
        console.error(error);
      } else {
        // Trata a resposta
        console.log(response);
      }
    }
  );

});

b) Obtendo informações sobre parcelamentos ( getInstallments )

$gn.ready(function (checkout) {

  checkout.getInstallments(
    50000, // valor total da cobrança
    'visa', // bandeira do cartão
    function (error, response) {
      if (error) {
        // Trata o erro ocorrido
        console.log(error);
      } else {
        // Trata a respostae
        console.log(response);
      }
    }
  );

});

c) Atributos relacionados ao envio de dados do cartão:

$gn.ready ( callback )

Parâmetro	Descrição	Tipo
`callback`	Função de inicialização que possibilita a chamada das funções getPaymentToken e getInstallments. Parâmetro(s) de callback `object` // Objeto que recebe as instâncias das outras funções.	Function

getPaymentToken ( card_data, callback )

Parâmetro	Descrição
`card_data`	Objeto que contém os dados do cartão. As propriedades desse objeto são: `brand` // Bandeira do cartão `number` // Número do cartão sem formatação `cvv` // Código de segurança do cartão `expiration_month` // Mês de expiração do cartão no formato "MM" `expiration_year` // Ano de expiração do cartão no formato "YYYY"	Object
`callback`	Função que recebe a resposta da Gerencianet. Parâmetro(s) de callback: `error` // Se não foi possível gerar o payment_token, os erros serão retornados neste parâmetro. `response` // Recebe os dados que representam o cartão de crédito: payment_token e card_mask	Function

getInstallments ( total, brand, callback )

Parâmetro	Descrição	Tipo
`total`	Valor total da cobrança, incluindo fretes, em centavos. Por exemplo: R$ 230,90 equivale a 23090.	Integer
`brand`	Bandeira do cartão que deseja-se obter os valores de parcelas. Possíveis valores: `visa` // Bandeira Visa `mastercard` // Bandeira MasterCard `amex` // Bandeira AmericanExpress `elo` // Bandeira Elo `hipercard` // Bandeira Hipercard	String
`callback`	Função que recebe a resposta da Gerencianet. Parâmetro(s) de callback: `error` // Se não foi possível obter dados sobre o pagamento, os erros serão retornados neste parâmetro. `response` // Recebe os dados relacionados ao tipo de pagamento consultado.	Function

1.2. Pagando com cartão

Agora que o payment_token já foi obtido através do código Javascript, vamos prosseguir com o pagamento com cartão de crédito.

Nesta etapa, seu backend envia o restante das informações da transação e o payment_token obtido na primeira etapa.

Ao pagar uma transação por cartão de crédito, o status é alterado de new para waiting. Isso significa que a transação está associada a uma forma de pagamento e que está aguardando a confirmação do pagamento.

Assim que o pagamento for confirmado, a transação terá o status alterado de waiting para paid. Mas, se por alguma razão não for possível confirmar o pagamento, o status será alterado para unpaid.

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

PHP·

.net·

NodeJs·

Go·

Ruby·

Java·

<?php

require __DIR__.'/../../autoload.php'; //Caminho da 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)
];
$paymentToken = '83d52dbd590d9ebc991938c711ddd31f65df89a5'; // payment_token obtido no procedimento através do Javascript único por conta Gerencianet

$item_1 = [
   'name' => 'Item 1', // nome do item, produto ou serviço
   'amount' => 1, // quantidade
   'value' => 3000 // 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.)
];
$items = [
   $item_1
];
$metadata = array('notification_url'=>'https://SuaUrl/16rpx6y1');
$customer = [
   'name' => 'Gorbadoc Oldbuck', // nome do cliente
   'cpf' => '04267484171', // cpf do cliente
   'phone_number' => '5144916523', // telefone do cliente
   'email' => '[email protected]', // endereço de email do cliente
   'birth' => '1977-01-15' // data de nascimento do cliente
];
$billingAddress = [
  'street' => 'Av JK',
  'number' => 909,
  'neighborhood' => 'Bauxita',
  'zipcode' => '35400000',
  'city' => 'Ouro Preto',
  'state' => 'MG'
];
$discount = [
   'type' => 'currency',
   'value' => 599
];

$credit_card = [
  'customer' => $customer,
  'installments' => 1, // número de parcelas em que o pagamento deve ser dividido
  'discount' =>$discount,
  'billing_address' => $billingAddress,
  'payment_token' => $paymentToken,
  'message' => 'teste\nteste\nteste\nteste'
];
$payment = [
   'credit_card' => $credit_card // forma de pagamento (credit_card = cartão)
];
$body = [
   'items' => $items,
   'metadata' =>$metadata,
   'payment' => $payment
];
try {
       $api = new Gerencianet($options);
       $pay_charge = $api->oneStep([],$body);
       echo '<pre>';
       print_r($pay_charge);
       echo '<pre>';
} 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:

"items"
    "name"
    "value"
    "amount"
    "marketplace"
        "payee_code"
        "percentage"
"shippings"
    "name"
    "value"
    "payee_code"
"metadata"
    "custom_id"
    "notification_url"
"payment"
    "credit_card"
        "customer"
            "name"
            "cpf"
            "email"
            "phone_number"
            "birth"
            "address"
                "street"
                "number"
                "neighborhood"
                "zipcode"
                "city"
                "complement"
                "state"
            "juridical_person"
                "corporate_name"
                "cnpj"
        "installments"
        "discount"
            "type"
                "percentage",
                "currency"
            "value"
        "billing_address"
            "street"
            "number"
            "neighborhood"
            "zipcode"
            "city"
            "complement"
            "state"
        "payment_token"
        "message"

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

Objeto Payment

Atributo	Descrição	Obrigatório	Tipo
`credit_card`	Objeto contendo as informações necessárias para o pagamento via cartão de crédito, como por exemplo, o número de parcelas e os dados do cliente.	Sim	Objeto Credit_Card

Objeto Credit_Card

Atributo	Descrição	Obrigatório	Tipo
`customer`	Dados pessoais do pagador. Atributos de customer `name` // nome (String)* `cpf` // CPF do cliente (sem pontos, vírgulas ou hífen) (String)* `email` // Endereço de email válido do cliente (String)* `phone_number` // Telefone válido do cliente, sem caracteres especiais (String)* `birth` // Data de Nascimento do cliente (data válida em formato YYYY-MM-DD) (String)* `address` // Endereço de Entrega (Object) (mais informações) `juridical_person` // Dados de pessoa jurídica (Object) (mais informações)	Sim	Object
`installments`	Número de parcelas em que o pagamento deve ser dividido. Mínimo 1 e máximo 12. Integer.	Não	Integer
`discount`	Define dados de desconto sobre a cobrança. Atributos de 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`.	Não	Object
`billing_address`	Endereço de cobrança (mais informações) Atributos de billing_address `street` // nome da rua (Object)* `number` // número (String/Integer)* `neighborhood` // Bairro (String)* `zipcode` // CEP (sem pontos ou hífen) (String)* `city` // cidade (String)* `complement` // complemento (String/null) `state` // estado (2 caracteres) (Object)*	Sim	Object
`payment_token`	Token único de pagamento obtido na primeira etapa da geração da transação.	Sim	String
`message`	Permite incluir no boleto uma "observação", ou em outras palavras, uma mensagem para o cliente. Essa mensagem poderá ser vista nos e-mails relacionados à cobrança, no boleto ou carnê. Até 4 linhas contendo 100 caracteres em cada linha. String. O operador `\n` é utilizado para efetuar a quebra de linha.	Não	String

* valor obrigatório

2. Criação de transação por cartão de crédito em Two Steps (Dois passos)

Nesta opção é necessário que o body da requisição contenha todos os atributos mínimos obrigatórios para a emissão do titulo.
Abaixo temos os exemplos de implementação utilizando as SDK's disponíveis:

2.1. Crie a transação, informando o item/produto/serviço, valor, quantidade, etc;

2.2. Associe à forma de pagamento via cartão, informando o charge_id da transação criada e os dados do cliente;

2.3. Obtenção do payment_token (via JavaScript, único por transação);

2.4. Pagando com cartão.

Por se tratar de pagamento via cartão e envolver dados sensíveis, como dados do cartão de crédito, os procedimentos descritos nos itens 3.1 e 3.2, ou seja, obtenção do payment_token e pagando com cartão, respectivamente, são necessários.

2.1. Criar transação

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.

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·

Ruby·

.NET·

Java·

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

2.2. Associe à forma de pagamento via cartão

Com a transação criada, vamos associá-la à forma de pagamento desejada, que neste caso, será cartão de crédito. Para tal, deverá ser informado a charge_id obtido no consumo anterior em que foi gerada a transação.

No caso de transações com cartão de crédito, será realizado em duas etapas, sendo a primeira a transmissão (via JavaScript, no browser), de forma segura, os dados do cartão e retornando um payment_token, e na segunda etapa seu backend envia o restante das informações da transação e o payment_token obtido na primeira etapa.

IMPORTANTE - SOBRE O PAYMENT_TOKEN

É importante frisar que não é possível efetuar pagamento com cartão de crédito sem obter o payment_token da transação, por isso, é imprescindível a realização dos procedimentos do item 2.1 deste documento (obter o payment_token), e só depois passar para o item 2.2 (que é de fato o pagamento com cartão).

Para associar à forma de pagamento, você deve enviar uma requisição POST para a rota /v1/charge/:id/pay, onde :id é o charge_id da transação desejada.

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

2.3. Obtenção do payment_token

Efetue login em sua conta Gerencianet e acesse API (Lateral a esquerda)
Copie seu Identificador de Conta (veja onde)
Cole no campo abaixo e clique no botão Gerar

É importante frisar que é obtido via JavaScript, no browser, de forma segura, os dados do cartão e retorna um payment_token, que é a representação dos dados enviados.

IMPORTANTE

Lembre-se que, após informar seu identificador de conta, serão gerados 2 (dois) códigos JavaScript distintos.

Copie e utilize o código referente ao ambiente desejado, atentando-se às diferenças do ambiente de "Homologação" e "Produção".

Para aplicações web, você deve copiar o script acima, específico da sua conta, e utilizar a nossa biblioteca Javascript, conforme o snippet abaixo. Se você possui um app mobile, confira como proceder acessando nossa página no GitHub para Android e/ou iOS.

a) Obtendo um "payment_token" ( getPaymentToken )

$gn.ready(function(checkout) {
 
  var callback = function(error, response) {
    if(error) {
      // Trata o erro ocorrido
      console.error(error);
    } else {
      // Trata a resposta
      console.log(response);
    }
  };
 
  checkout.getPaymentToken({
    brand: 'visa', // bandeira do cartão
    number: '4012001038443335', // número do cartão
    cvv: '123', // código de segurança
    expiration_month: '05', // mês de vencimento
    expiration_year: '2021' // ano de vencimento
  }, callback);
 
});

b) Obtendo informações sobre parcelamentos ( getInstallments )

$gn.ready(function(checkout){
 
  checkout.getInstallments(50000,'visa', function(error, response){
    if(error) {
      // Trata o erro ocorrido
      console.log(error);
    } else {
      // Insere o parcelamento no site
    }
  });
 
});

c) Atributos relacionados ao envio de dados do cartão:

$gn.ready ( callback )

Parâmetro	Descrição	Tipo
`callback`	Função de inicialização que possibilita a chamada das funções getPaymentToken e getInstallments. Parâmetro(s) de callback `object` // Objeto que recebe as instâncias das outras funções.	Function

getPaymentToken ( card_data, callback )

Parâmetro	Descrição	Tipo
`card_data`	Objeto que contém os dados do cartão. As propriedades desse objeto são: `brand` // Bandeira do cartão `number` // Número do cartão sem formatação `cvv` // Código de segurança do cartão `expiration_month` // Mês de expiração do cartão no formato "MM" `expiration_year` // Ano de expiração do cartão no formato "YYYY"	Object
`callback`	Função que recebe a resposta da Gerencianet. Parâmetro(s) de callback: `error` // Se não foi possível gerar o payment_token, os erros serão retornados neste parâmetro. `response` // Recebe os dados que representam o cartão de crédito: payment_token e card_mask	Function

getInstallments ( total, brand, callback )

Parâmetro	Descrição	Tipo
`total`	Valor total da cobrança, incluindo fretes, em centavos. Por exemplo: R$ 230,90 equivale a 23090.	Integer
`brand`	Bandeira do cartão que deseja-se obter os valores de parcelas. Possíveis valores: `visa` // Bandeira Visa `mastercard` // Bandeira MasterCard `amex` // Bandeira AmericanExpress `elo` // Bandeira Elo `hipercard` // Bandeira Hipercard	String
`callback`	Função que recebe a resposta da Gerencianet. Parâmetro(s) de callback: `error` // Se não foi possível obter dados sobre o pagamento, os erros serão retornados neste parâmetro. `response` // Recebe os dados relacionados ao tipo de pagamento consultado.	Function

2.4. Pagando com cartão

Agora que a transação já foi criada e o payment_token já foi obtido através do código Javascript da primeira etapa, vamos prosseguir com o pagamento com cartão de crédito.

Nesta etapa, seu backend envia o restante das informações da transação e o payment_token obtido na primeira etapa.

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

PHP·

Ruby·

.NET·

Java·

<?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
];
 
$paymentToken = '6426f3abd8688639c6772963669bbb8e0eb3c319'; // payment_token obtido na 1ª etapa (através do Javascript único por conta Gerencianet)
 
$customer = [
  'name' => 'Gorbadoc Oldbuck', // nome do cliente
  'cpf' => '94271564656' , // cpf do cliente
  'email' => '[email protected]' , // endereço de email do cliente
  'phone_number' => '5144916523' // telefone do cliente
  'birth' => '1990-05-20' // data de nascimento do cliente
];
 
$billingAddress = [
  'street' => 'Street 3',
  'number' => 10,
  'neighborhood' => 'Bauxita',
  'zipcode' => '35400000',
  'city' => 'Ouro Preto',
  'state' => 'MG',
];
 
$creditCard = [
  'installments' => 1, // número de parcelas em que o pagamento deve ser dividido
  'billing_address' => $billingAddress,
  'payment_token' => $paymentToken,
  'customer' => $customer
];
 
$body = [
  'payment' => $payment
];
 
$payment = [
  'credit_card' => $creditCard // forma de pagamento (credit_card = cartão)
];
 
try {
    $api = new Gerencianet($options);
    $charge = $api->payCharge($params, $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": "/Pay",
    "payment"
        "credit_card"
            "customer"
                "name"
                "cpf"
                "email"
                "phone_number"
                "birth"
                "address"
                    "street"
                    "number"
                    "neighborhood"
                    "zipcode"
                    "city"
                    "complement"
                    "state"
                "juridical_person"
                    "corporate_name"
                    "cnpj"
            "installments"
            "discount"
                "type"
                    "percentage",
                    "currency"
                "value"
            "billing_address"
                "street"
                "number"
                "neighborhood"
                "zipcode"
                "city"
                "complement"
                "state"
            "payment_token"
            "message"

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

b) Atributos relacionados ao pagamento com cartão de crédito:

Parâmetros da url

Atributo	Descrição	Obrigatório	Tipo
`id`	Identificador da transação (`charge_id`)	Sim	Objeto ID

Objeto ID

Atributo	Descrição	Obrigatório	Tipo
`payment`	Tag raiz	Sim	Objeto Payment

Objeto Payment

Atributo	Descrição	Obrigatório	Tipo
`credit_card`	Objeto contendo as informações necessárias para o pagamento via cartão de crédito, como por exemplo, o número de parcelas e os dados do cliente.	Sim	Objeto Credit_Card

Objeto Credit_Card

Atributo	Descrição	Obrigatório	Tipo
`customer`	Dados pessoais do pagador. Atributos de customer `name` // nome (String)* `cpf` // CPF do cliente (sem pontos, vírgulas ou hífen) (String)* `email` // Endereço de email válido do cliente (String)* `phone_number` // Telefone válido do cliente, sem caracteres especiais (String) `birth` // Data de Nascimento do cliente (data válida em formato YYYY-MM-DD) (String)* `address` // Endereço de Entrega (Object) (mais informações) `juridical_person` // Dados de pessoa jurídica (Object) (mais informações)	Sim	Object
`installments`	Número de parcelas em que o pagamento deve ser dividido. Mínimo 1 e máximo 12. Integer.	Não	Integer
`discount`	Define dados de desconto sobre a cobrança. Atributos de 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`.	Não	Object
`billing_address`	Endereço de cobrança (mais informações) Atributos de billing_address `street` // nome da rua (Object)* `number` // número (String/Integer)* `neighborhood` // Bairro (String)* `zipcode` // CEP (sem pontos ou hífen) (String)* `city` // cidade (String)* `complement` // complemento (String/null) `state` // estado (2 caracteres) (Object)*	Sim	Object
`payment_token`	Token único de pagamento obtido na primeira etapa da geração da transação.	Sim	String
`message`	Permite incluir no boleto uma "observação", ou em outras palavras, uma mensagem para o cliente. Essa mensagem poderá ser vista nos e-mails relacionados à cobrança, no boleto ou carnê. Até 4 linhas contendo 100 caracteres em cada linha. String. O operador `\n` é utilizado para efetuar a quebra de linha.	Não	String

* valor obrigatório

Pagamento realizado como Pessoa Jurídica (PJ)

O cliente associado à transação pode ser uma Pessoa Jurídica. Nesse caso, devem ser informados a Razão Social e o CNPJ da empresa pagadora dentro do atributo juridical_person.

Veja detalhes neste link sobre como gerar um pagamento cuja forma de pagamento seja "cartão de crédito" para um cliente que seja Pessoa Jurídica (PJ).

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.

3. Outros endpoints

Existem outros endpoints e métodos relacionados a pagamento via cartão de crédito que estão disponíveis na API e podem ser explorados pelo integrador. Confira a relação completa:

Gerar boleto bancário na API Gerencianet - Maykon Silveira

Gerar boleto bancário

Passo a passo para gerar boleto bancário na API Gerencianet

Atualmente disponibilizamos dois procedimentos para a criação de uma transação do tipo Boleto bancário, na primeira delas o titulo é criado em um passo único, assim fora convencionado como One Step. A segunda opção de criação da transação se da em dois passos, sendo assim convencionada como Two Steps. A geração de um boleto não envolve transmissão de dados sensíveis como número de cartão de crédito. Por isso, basta consumir o respectivo endpoint de pagamento para gerar o boleto registrado. Ambos os fluxos estão detalhados a seguir:

1. Criação de Boleto em One Step (Um passo)

Importante

Para que a criação de transações via One Step ocorra normalmente é necessário atualizar sua SDK. Todos os arquivos necessários para tal estão disponíveis através através de nosso repositório e em nossa documentação.

PHP·

.Net·

NodeJs·

Java·

Go·

Ruby·

<?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.)
   ];
   $items = [
       $item_1
   ];
   $metadata = array('notification_url'=>'sua_url_de_notificacao_.com.br'); //Url de notificações
   $customer = [
       'name' => 'Gorbadoc Oldbuck', // nome do cliente
       'cpf' => '94271564656', // cpf válido do cliente
       'phone_number' => '5144916523', // telefone do cliente
   ];
   $discount = [ // configuração de descontos
       'type' => 'currency', // tipo de desconto a ser aplicado
       'value' => 599 // valor de desconto 
   ];
   $configurations = [ // configurações de juros e mora
       'fine' => 200, // porcentagem de multa
       'interest' => 33 // porcentagem de juros
   ];
   $conditional_discount = [ // configurações de desconto condicional
       'type' => 'percentage', // seleção do tipo de desconto 
       'value' => 500, // porcentagem de desconto
       'until_date' => '2019-08-30' // data máxima para aplicação do desconto
   ];
   $bankingBillet = [
       'expire_at' => '2019-09-01', // data de vencimento do titulo
       'message' => 'teste\nteste\nteste\nteste', // mensagem a ser exibida no boleto
       'customer' => $customer,
       'discount' =>$discount,
       'conditional_discount' => $conditional_discount
   ];
   $payment = [
       'banking_billet' => $bankingBillet // forma de pagamento (banking_billet = boleto)
   ];
   $body = [
       'items' => $items,
       'metadata' =>$metadata,
       'payment' => $payment
   ];
   try {
     $api = new Gerencianet($options);
     $pay_charge = $api->oneStep([],$body);
     echo '<pre>';
     print_r($pay_charge);
     echo '<pre>';
     
    } 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:

"OneStep": "/Charge/one-step"
    "items"
        "name"
        "value"
        "amount"
        "marketplace"
            "payee_code"
            "percentage"
    "shippings"
        "name"
        "value"
        "payee_code"
    "metadata"
        "custom_id"
        "notification_url"
    "payment"
        "banking_billet"
            "customer"
                "name"
                "cpf"
                "email"
                "phone_number"
                "birth"
                "address"
                    "street"
                    "number"
                    "neighborhood"
                    "zipcode"
                    "city"
                    "complement"
                    "state"
                "juridical_person"
                    "corporate_name"
                    "cnpj"
            "expire_at"
            "discount"
                "type"
                    "percentage",
                    "currency"
                "value"
            "conditional_discount"
                "type"
                    "percentage",
                    "currency"
                "value"
                "until_date"
            "configurations"
                "fine"
                "interest"
            "message"

b) Atributos que podem ser utilizados para criar um titulo:

Objeto items

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

Objeto Payment

Atributo	Descrição	Obrigatório	Tipo
`banking_billet`	Forma de pagamento através de "boleto bancário"	Sim	Objeto Banking_Billet

Objeto Banking_Billet

Atributo	Descrição	Obrigatório	Tipo
`name`	Nome do cliente. Mínimo de 1 caractere e máximo de 255.	Sim Obs: Para Pessoa Jurídica não serão obrigatórios o nome e CPF, apenas os demais dados do cliente.	String
`cpf`	CPF válido do cliente (sem pontos, vírgulas ou hífen). Tamanho: 11 caracteres.	Sim Obs: Para Pessoa Jurídica não serão obrigatórios o nome e CPF, apenas os demais dados do cliente.	String
`email`	Email do cliente. Máximo de 255 caracteres. Ex.: [email protected]	Não	String
`phone_number`	Telefone do cliente. Formato: sem pontos ou vírgulas, com DDD de 2 caracteres (9º dígito é opcional). Ex.: 11988887777	Não	String
`birth`	Data de nascimento do cliente. Formato: YYYY-MM-DD	Não	String
`address`	Endereço do cliente. Atributos de address `street` // nome da rua (Object)* `number` // número (String/Integer)* `neighborhood` // Bairro (String)* `zipcode` // CEP (sem pontos ou hífen) (String)* `city` // cidade (String)* `complement` // complemento (String/null) `state` // estado (2 caracteres) (Object)*	Não	Object
`juridical_person`	Dados de pessoa jurídica Atributos de juridical_person `corporate_name` // Nome da razão social. Mínimo de 1 caractere e máximo de 255. String.* `cnpj` // CNPJ da empresa. Tamanho: 14 caracteres. String.*	Não	Object
`expire_at`	Data de vencimento do boleto. Formato: YYYY-MM-DD	Sim	String
`discount`	Define dados de desconto sobre a cobrança. Atributos de 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`.	Não	Object
`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
`configurations`	Permite incluir no boleto multa e juros caso seja pago após o vencimento. Atributos de configurations fine, // valor cobrado de multa após o vencimento. Por exemplo: se você quiser 2%, você deve informar `200`. Mínimo de 0 e máximo de 1000. Integer. Caso você possua configurações de multa ativada na Gerencianet e queira gerar emissões na API sem multa, utilize `0` como valor do atributo `fine` interest, // valor cobrado de juros por dia após a data de vencimento. Por exemplo: se você quiser 0,033%, você deve informar `33`. Mínimo de 0 e máximo de 330. Integer. Caso você possua configurações de multa ativada na Gerencianet e queira gerar emissões na API sem juros, utilize `0` como valor do atributo `interest`	Não	Object
`message`	Permite incluir no boleto uma "observação", ou em outras palavras, uma mensagem para o cliente. Essa mensagem poderá ser vista nos e-mails relacionados à cobrança, no boleto ou carnê. Até 4 linhas contendo 100 caracteres em cada linha. String. O operador `\n` é utilizado para efetuar a quebra de linha.	Não	String

valor obrigatório

2. Criação de Boleto em Two Steps (Dois passos)

Crie a transação, informando o item/produto/serviço, valor, quantidade, etc;
Associe à forma de pagamento via boleto, informando o charge_id da transação e os dados do cliente.

2.1. Criar transação

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.

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·

Ruby·

.NET·

Java·

<?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,a
//    '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

2.2. Associar à forma de pagamento via boleto

Com a transação gerada com sucesso, agora vamos associar com a forma de pagamento desejada - neste caso, será banking_billet (boleto bancário). Para tal, deverá ser informado o charge_id obtido ao criar a transação.

Neste momento, ao definir boleto bancário como forma de pagamento da transação, seu status será alterado de new para waiting. Isso significa que a forma de pagamento foi selecionada e está aguardando a confirmação do pagamento.

Para associar à forma de pagamento, você deve enviar uma requisição POST para a rota /v1/charge/:id/pay, onde :id é o charge_id da transação desejada.

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·

Ruby·

.NET·

Java·

<?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
];
 
$customer = [
  'name' => 'Gorbadoc Oldbuck', // nome do cliente
  'cpf' => '94271564656' , // cpf válido do cliente
  'phone_number' => '5144916523' // telefone do cliente
];
 
$bankingBillet = [
  'expire_at' => '2018-12-12', // data de vencimento do boleto (formato: YYYY-MM-DD)
  'customer' => $customer
];
 
$payment = [
  'banking_billet' => $bankingBillet // forma de pagamento (banking_billet = boleto)
];
 
$body = [
  'payment' => $payment
];
 
try {
    $api = new Gerencianet($options);
    $charge = $api->payCharge($params, $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": "/Pay",
    "payment"
        "banking_billet"
            "customer"
                "name"
                "cpf"
                "email"
                "phone_number"
                "birth"
                "address"
                    "street"
                    "number"
                    "neighborhood"
                    "zipcode"
                    "city"
                    "complement"
                    "state"
                "juridical_person"
                    "corporate_name"
                    "cnpj"
            "expire_at"
            "discount"
                "type"
                    "percentage",
                    "currency"
                "value"
            "conditional_discount"
                "type"
                    "percentage",
                    "currency"
                "value"
                "until_date"
            "configurations"
                "fine"
                "interest"
            "message"

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

b) Atributos que podem ser utilizados para gerar um boleto bancário:

Atributo	Descrição	Obrigatório	Tipo
`payment`	Tag raiz	Sim	Objeto Payment

Objeto Payment

Atributo	Descrição	Obrigatório	Tipo
`banking_billet`	Forma de pagamento através de "boleto bancário"	Sim	Objeto Banking_Billet

Objeto Banking_Billet

Atributo	Descrição	Obrigatório	Tipo
`name`	Nome do cliente. Mínimo de 1 caractere e máximo de 255.	Sim Obs: Para Pessoa Jurídica não serão obrigatórios o nome e CPF, apenas os demais dados do cliente.	String
`cpf`	CPF válido do cliente (sem pontos, vírgulas ou hífen). Tamanho: 11 caracteres.	Sim Obs: Para Pessoa Jurídica não serão obrigatórios o nome e CPF, apenas os demais dados do cliente.	String
`email`	Email do cliente. Máximo de 255 caracteres. Ex.: [email protected]	Não	String
`phone_number`	Telefone do cliente. Formato: sem pontos ou vírgulas, com DDD de 2 caracteres (9º dígito é opcional). Ex.: 11988887777	Não	String
`birth`	Data de nascimento do cliente. Formato: YYYY-MM-DD	Não	String
`address`	Endereço do cliente. Atributos de address `street` // nome da rua (Object)* `number` // número (String/Integer)* `neighborhood` // Bairro (String)* `zipcode` // CEP (sem pontos ou hífen) (String)* `city` // cidade (String)* `complement` // complemento (String/null) `state` // estado (2 caracteres) (Object)*	Não	Object
`juridical_person`	Dados de pessoa jurídica Atributos de juridical_person `corporate_name` // Nome da razão social. Mínimo de 1 caractere e máximo de 255. String.* `cnpj` // CNPJ da empresa. Tamanho: 14 caracteres. String.*	Não	Object
`expire_at`	Data de vencimento do boleto. Formato: YYYY-MM-DD	Sim	String
`discount`	Define dados de desconto sobre a cobrança. Atributos de 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`.	Não	Object
`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
`configurations`	Permite incluir no boleto multa e juros caso seja pago após o vencimento. Atributos de configurations fine, // valor cobrado de multa após o vencimento. Por exemplo: se você quiser 2%, você deve informar `200`. Mínimo de 0 e máximo de 1000. Integer. Caso você possua configurações de multa ativada na Gerencianet e queira gerar emissões na API sem multa, utilize `0` como valor do atributo `fine` interest, // valor cobrado de juros por dia após a data de vencimento. Por exemplo: se você quiser 0,033%, você deve informar `33`. Mínimo de 0 e máximo de 330. Integer. Caso você possua configurações de multa ativada na Gerencianet e queira gerar emissões na API sem juros, utilize `0` como valor do atributo `interest`	Não	Object
`message`	Permite incluir no boleto uma "observação", ou em outras palavras, uma mensagem para o cliente. Essa mensagem poderá ser vista nos e-mails relacionados à cobrança, no boleto ou carnê. Até 4 linhas contendo 100 caracteres em cada linha. String. O operador `\n` é utilizado para efetuar a quebra de linha.	Não	String

valor obrigatório

Pagamento realizado como Pessoa Jurídica (PJ)

O cliente associado à transação pode ser uma Pessoa Jurídica. Nesse caso, devem ser informados a Razão Social e o CNPJ da empresa pagadora dentro do atributo juridical_person.

Veja detalhes neste link sobre como gerar um pagamento cuja forma de pagamento seja "boleto bancário" para um cliente que seja Pessoa Jurídica (PJ).

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 de uma transação 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 um boleto for pago, por exemplo.

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

3. Outros endpoints

Existem outros endpoints e métodos relacionados a pagamento via boleto bancário que estão disponíveis na API e podem ser explorados pelo integrador. Confira a relação completa:

Como Gerar Bolix API Gerencianet - Maykon Silveira

Gerar Bolix

Passo a passo para gerar Bolix na API Gerencianet, o Bolix permite gerar cobranças com o pix no boleto, possibilitando mais de uma forma de pagamento aos clientes

O Bolix, pix no boleto, permite gerar transações do tipo boleto e carnê para seu cliente com o acréscimo do Pix como forma de pagamento.
O Bolix quando emitido na forma de boleto pode ser gerado via API em um passo, também conhecido como One Step ou em dois passos, o Two Steps.
Também é disponibilizado a emissão do Bolix como carnê, que consiste em um conjunto de transações (parcelas) geradas em lote e com forma de pagamento já definida com vencimento mensal.

Todos os fluxos e informações para emissões do Bolix tanto como boleto bancário quanto carnê estão detalhados a seguir:

Ativação do Bolix

Para que você consiga emitir cobranças Bolix, boleto com pix, primeiramente deve-se ativar o Bolix em sua conta Gerencianet, siga estes passos:

1- Acesse sua Conta Digital na plataforma web.
2- Clique no menu Cobranças > Configurações > Boletos Bancários e Carnês.
3- Por fim, habilite a função “Bolix” como nesta imagem.

SDK's

O restante desta página apresenta os procedimentos detalhados para criação do Bolix com os métodos de pagamento boleto bancário e carnê, 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.

1. Criação do Bolix, boleto com pix, em One Step (Um passo)

PHP·

Java·

.NET·

Go·

Ruby·

<?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.)
   ];
   $items = [
       $item_1
   ];
   $metadata = array('notification_url'=>'sua_url_de_notificacao_.com.br'); //Url de notificações onde vamos notificá-lo, independente se for pago pelo código de barras do boleto quanto pelo QR Code.
   $customer = [
       'name' => 'Gorbadoc Oldbuck', // nome do cliente
       'cpf' => '94271564656', // cpf válido do cliente
       'phone_number' => '5144916523', // telefone do cliente
   ];
   $discount = [ // configuração de descontos
       'type' => 'currency', // tipo de desconto a ser aplicado
       'value' => 599 // valor de desconto 
   ];
   $configurations = [ // configurações de juros e mora
       'fine' => 200, // porcentagem de multa
       'interest' => 33 // porcentagem de juros
   ];
   $conditional_discount = [ // configurações de desconto condicional
       'type' => 'percentage', // seleção do tipo de desconto 
       'value' => 500, // porcentagem de desconto
       'until_date' => '2019-08-30' // data máxima para aplicação do desconto
   ];
   $bankingBillet = [
       'expire_at' => '2022-09-01', // data de vencimento do titulo
       'message' => 'Pague pelo código de barras ou pelo QR Code', // mensagem a ser exibida no boleto
       'customer' => $customer,
       'discount' =>$discount,
       'conditional_discount' => $conditional_discount
   ];
   $payment = [
       'banking_billet' => $bankingBillet // forma de pagamento (banking_billet = Bolix)
   ];
   $body = [
       'items' => $items,
       'metadata' =>$metadata,
       'payment' => $payment
   ];
   try {
     $api = new Gerencianet($options);
     $pay_charge = $api->oneStep([],$body);
     echo '<pre>';
     print_r($pay_charge);
     echo '<pre>';
     
    } catch (GerencianetException $e) {
       print_r($e->code);
       print_r($e->error);
       print_r($e->errorDescription);
   } catch (Exception $e) {
       print_r($e->getMessage());
   }

Dados de entrada e saída do Bolix em One Step:

{
  "items": [
    {
      "name": "Meu Produto",
      "value": 5990,
      "amount": 1
    }
  ],
  "payment": {
    "banking_billet": {
      "customer": {
        "name": "Gorbadoc Oldbuck",
        "cpf": "94271564656",
        "email": "[email protected]",
        "phone_number": "5144916523",
        "address": {
          "street": "Avenida Juscelino Kubitschek",
          "number": "909",
          "neighborhood": "Bauxita",
          "zipcode": "35400000",
          "city": "Ouro Preto",
          "complement": "",
          "state": "MG"
        }
      },
      "expire_at": "2022-12-15",
      "configurations": {
        "fine": 200,
        "interest": 33
      },
      "message": "Pague pelo código de barras ou pelo QR Code"
    }
  }
}

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

"OneStep": "/Charge/one-step"
    "items"
        "name"
        "value"
        "amount"
        "marketplace"
            "payee_code"
            "percentage"
    "shippings"
        "name"
        "value"
        "payee_code"
    "metadata"
        "custom_id"
        "notification_url"
    "payment"
        "banking_billet"
            "customer"
                "name"
                "cpf"
                "email"
                "phone_number"
                "birth"
                "address"
                    "street"
                    "number"
                    "neighborhood"
                    "zipcode"
                    "city"
                    "complement"
                    "state"
                "juridical_person"
                    "corporate_name"
                    "cnpj"
            "expire_at"
            "discount"
                "type"
                    "percentage",
                    "currency"
                "value"
            "conditional_discount"
                "type"
                    "percentage",
                    "currency"
                "value"
                "until_date"
            "configurations"
                "fine"
                "interest"
            "message"

b) Atributos que podem ser utilizados para criar um título:

Objeto items

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

Objeto Payment

Atributo	Descrição	Obrigatório	Tipo
`banking_billet`	Forma de pagamento através de "boleto bancário"	Sim	Objeto Banking_Billet

Objeto Banking_Billet

Atributo	Descrição	Obrigatório	Tipo
`name`	Nome do cliente. Mínimo de 1 caractere e máximo de 255.	Sim Obs: Para Pessoa Jurídica não serão obrigatórios o nome e CPF, apenas os demais dados do cliente.	String
`cpf`	CPF válido do cliente (sem pontos, vírgulas ou hífen). Tamanho: 11 caracteres.	Sim Obs: Para Pessoa Jurídica não serão obrigatórios o nome e CPF, apenas os demais dados do cliente.	String
`email`	Email do cliente. Máximo de 255 caracteres. Ex.: [email protected]	Não	String
`phone_number`	Telefone do cliente. Formato: sem pontos ou vírgulas, com DDD de 2 caracteres (9º dígito é opcional). Ex.: 11988887777	Não	String
`birth`	Data de nascimento do cliente. Formato: YYYY-MM-DD	Não	String
`address`	Endereço do cliente. Atributos de address `street` // nome da rua (Object)* `number` // número (String/Integer)* `neighborhood` // Bairro (String)* `zipcode` // CEP (sem pontos ou hífen) (String)* `city` // cidade (String)* `complement` // complemento (String/null) `state` // estado (2 caracteres) (Object)*	Não	Object
`juridical_person`	Dados de pessoa jurídica Atributos de juridical_person `corporate_name` // Nome da razão social. Mínimo de 1 caractere e máximo de 255. String.* `cnpj` // CNPJ da empresa. Tamanho: 14 caracteres. String.*	Não	Object
`expire_at`	Data de vencimento do boleto. Formato: YYYY-MM-DD	Sim	String
`discount`	Define dados de desconto sobre a cobrança. Atributos de 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`.	Não	Object
`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
`configurations`	Permite incluir no boleto multa e juros caso seja pago após o vencimento. Atributos de configurations fine, // valor cobrado de multa após o vencimento. Por exemplo: se você quiser 2%, você deve informar `200`. Mínimo de 0 e máximo de 1000. Integer. Caso você possua configurações de multa ativada na Gerencianet e queira gerar emissões na API sem multa, utilize `0` como valor do atributo `fine` interest, // valor cobrado de juros por dia após a data de vencimento. Por exemplo: se você quiser 0,033%, você deve informar `33`. Mínimo de 0 e máximo de 330. Integer. Caso você possua configurações de multa ativada na Gerencianet e queira gerar emissões na API sem juros, utilize `0` como valor do atributo `interest`	Não	Object

valor obrigatório

2. Criação do Bolix, boleto com pix, em Two Steps (Dois passos)

Crie a transação, informando o item/produto/serviço, valor, quantidade, etc;
Associe à forma de pagamento via boleto, informando o charge_id da transação e os dados do cliente.

2.1. Criar transação

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.

Para gerar uma transação, você deve enviar uma requisição POST para a rota /v1/charge.

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

PHP·

Java·

.NET·

Go·

Ruby·

<?php
 
require __DIR__ . '/../../vendor/autoload.php';

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

$file = file_get_contents(__DIR__ . '/../config.json');
$options = json_decode($file, true);
unset($options['pix_cert']);
 
$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,a
//    '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());
}

Dados de entrada e saída na criação da transação:

{
  "items": [
    {
      "name": "Meu Produto",
      "value": 8900,
      "amount": 1
    }
  ]
}

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

2.2. Associar à forma de pagamento via boleto

Com a transação gerada com sucesso, agora vamos associar com a forma de pagamento banking_billet (boleto bancário) e assim gerar o Bolix. Para tal, deverá ser informado o charge_id obtido ao criar a transação.

Para associar à forma de pagamento, você deve enviar uma requisição POST para a rota /v1/charge/:id/pay, onde :id é o charge_id da transação desejada.

O boleto bancário que será gerado já vem com a forma de pagamento Pix inclusa.

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

PHP·

NodeJs·

Java·

.NET·

Go·

Ruby·

<?php
 
require __DIR__ . '/../../vendor/autoload.php';

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

$file = file_get_contents(__DIR__ . '/../config.json');
$options = json_decode($file, true);
unset($options['pix_cert']);
 
// $charge_id refere-se ao ID da transação gerada anteriormente
$params = [
  'id' => $charge_id
];
 
$customer = [
  'name' => 'Gorbadoc Oldbuck', // nome do cliente
  'cpf' => '94271564656' , // cpf válido do cliente
  'phone_number' => '5144916523' // telefone do cliente
];
 
$bankingBillet = [
  'expire_at' => '2022-12-12', // data de vencimento do boleto (formato: YYYY-MM-DD)
  'customer' => $customer
];
 
$payment = [
  'banking_billet' => $bankingBillet // forma de pagamento (banking_billet = boleto)
];
 
$body = [
  'payment' => $payment
];
 
try {
    $api = new Gerencianet($options);
    $charge = $api->payCharge($params, $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());
}

Dados de entrada e saída na criação da transação:

{
  "payment": {
    "banking_billet": {
      "customer": {
        "name": "Gorbadoc Oldbuck",
        "cpf": "94271564656",
        "email": "[email protected]",
        "phone_number": "5144916523",
        "address": {
          "street": "Avenida Juscelino Kubitschek",
          "number": "909",
          "neighborhood": "Bauxita",
          "zipcode": "35400000",
          "city": "Ouro Preto",
          "complement": "",
          "state": "MG"
        }
      },
      "expire_at": "2022-12-30",
      "configurations": {
        "fine": 200,
        "interest": 33
      },
      "message": "Pague pelo código de barras ou pelo QR Code"
    }
  }
}

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

"id": "/Pay",
    "payment"
        "banking_billet"
            "customer"
                "name"
                "cpf"
                "email"
                "phone_number"
                "birth"
                "address"
                    "street"
                    "number"
                    "neighborhood"
                    "zipcode"
                    "city"
                    "complement"
                    "state"
                "juridical_person"
                    "corporate_name"
                    "cnpj"
            "expire_at"
            "discount"
                "type"
                    "percentage",
                    "currency"
                "value"
            "conditional_discount"
                "type"
                    "percentage",
                    "currency"
                "value"
                "until_date"
            "configurations"
                "fine"
                "interest"
            "message"

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

b) Atributos que podem ser utilizados para gerar um Bolix, pix no boleto bancário:

Atributo	Descrição	Obrigatório	Tipo
`payment`	Tag raiz	Sim	Objeto Payment

Objeto Payment

Atributo	Descrição	Obrigatório	Tipo
`banking_billet`	Forma de pagamento através de "boleto bancário"	Sim	Objeto Banking_Billet

Objeto Banking_Billet

Atributo	Descrição	Obrigatório	Tipo
`name`	Nome do cliente. Mínimo de 1 caractere e máximo de 255.	Sim Obs: Para Pessoa Jurídica não serão obrigatórios o nome e CPF, apenas os demais dados do cliente.	String
`cpf`	CPF válido do cliente (sem pontos, vírgulas ou hífen). Tamanho: 11 caracteres.	Sim Obs: Para Pessoa Jurídica não serão obrigatórios o nome e CPF, apenas os demais dados do cliente.	String
`email`	Email do cliente. Máximo de 255 caracteres. Ex.: [email protected]	Não	String
`phone_number`	Telefone do cliente. Formato: sem pontos ou vírgulas, com DDD de 2 caracteres (9º dígito é opcional). Ex.: 11988887777	Não	String
`birth`	Data de nascimento do cliente. Formato: YYYY-MM-DD	Não	String
`address`	Endereço do cliente. Atributos de address `street` // nome da rua (Object)* `number` // número (String/Integer)* `neighborhood` // Bairro (String)* `zipcode` // CEP (sem pontos ou hífen) (String)* `city` // cidade (String)* `complement` // complemento (String/null) `state` // estado (2 caracteres) (Object)*	Não	Object
`juridical_person`	Dados de pessoa jurídica Atributos de juridical_person `corporate_name` // Nome da razão social. Mínimo de 1 caractere e máximo de 255. String.* `cnpj` // CNPJ da empresa. Tamanho: 14 caracteres. String.*	Não	Object
`expire_at`	Data de vencimento do boleto. Formato: YYYY-MM-DD	Sim	String
`discount`	Define dados de desconto sobre a cobrança. Atributos de 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`.	Não	Object
`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
`configurations`	Permite incluir no boleto multa e juros caso seja pago após o vencimento. Atributos de configurations fine, // valor cobrado de multa após o vencimento. Por exemplo: se você quiser 2%, você deve informar `200`. Mínimo de 0 e máximo de 1000. Integer. Caso você possua configurações de multa ativada na Gerencianet e queira gerar emissões na API sem multa, utilize `0` como valor do atributo `fine` interest, // valor cobrado de juros por dia após a data de vencimento. Por exemplo: se você quiser 0,033%, você deve informar `33`. Mínimo de 0 e máximo de 330. Integer. Caso você possua configurações de multa ativada na Gerencianet e queira gerar emissões na API sem juros, utilize `0` como valor do atributo `interest`	Não	Object
`message`	Permite incluir no boleto uma "observação", ou em outras palavras, uma mensagem para o cliente. Essa mensagem poderá ser vista nos e-mails relacionados à cobrança, no boleto ou carnê. Até 4 linhas contendo 100 caracteres em cada linha. String. O operador `\n` é utilizado para efetuar a quebra de linha.	Não	String

valor obrigatório

3. Gerando um Bolix com o método de pagamento carnê

O carnê é um método de pagamento que gera um conjunto de transações (parcelas) com as mesmas informações de pagamento e do cliente em todas elas, as parcelas de um carnê vencem mensalmente, de acordo com a data definida pelo integrador. Para gerar um carnê, você precisa informar os seguintes dados:

Itens (ou serviço) oferecido;
Data de vencimento da 1ª parcela;
Número de parcelas (repetições).

A seguir, um código de exemplo de criação de um Bolix com o método de pagamento carnê utilizando as SDK's disponíveis. Note que já estamos definindo os itens, os dados do cliente, data de vencimento da primeira parcela do carnê e a quantidade de repetições (em meses):

PHP·

Java·

.NET·

Go·

Ruby·

<?php

require __DIR__ . '/../../vendor/autoload.php';

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

$file = file_get_contents(__DIR__ . '/../config.json');
$options = json_decode($file, true);
unset($options['pix_cert']);

$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
];
 
$customer = [
  'name' => 'Gorbadoc Oldbuck', // nome do cliente
  'cpf' => '94271564656' , // cpf do cliente
  'phone_number' => '5144916523' // telefone do cliente
];

// Exemplo para receber notificações da alteração do status do carne.
// $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,
// 'customer' => $customer,
// 'expire_at' => '2022-12-02',
// 'repeats' => 5,
// 'split_items' => false,
// 'metadata' => $metadata
// ];

$body = [
  'items' => $items,
  'customer' => $customer,
  'expire_at' => '2022-12-02', // data de vencimento da primeira parcela do carnê
  'repeats' => 5, // número de parcelas do carnê
  'split_items' => false // Define se os itens do carnê serão divididos entre as parcelas (true), ou se o valor de cada parcela será o valor total dos itens (false)
];

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

Dados de entrada e saída na criação do Bolix com o método de pagamento carnê: