Generate boleto bancário

We currently offer two procedures for creating a Boleto Bancário type transaction, in the first of them the title is created in a single step, thus being conventional as One Step. The second option for creating the transaction takes place in two steps, thus being called Two Steps. Generating a boleto does not involve transmitting sensitive data such as a credit card number. Therefore, just consume the respective payment endpoint to generate the registered boleto. Both flows are detailed below:

Creating the Transaction in One Step.
Creating the Transaction in Two Steps.

1. Creating the Transaction in One Step

In this option, it is necessary that the body of the request contains all the minimum attributes required for issuing the title. Below are implementation examples using the available SDK's:

important

For the creation of transactions via One Step to occur, it is normally necessary to update your SDK. All the files necessary for this are available through our repository and in our documentation.

<?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 = desenvolvimento 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) Hierarchical structure of Schema attributes that can be used:

"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) Attributes that can be used to create a title:

Objeto items

Attribute	Description	Mandatory	Type
`items`	item being sold. The same transaction can have unlimited items. Item attributes: `name`// Name of the item, product or service. Minimum of 1 character and maximum of 255 characters (String). `value`// Value, in cents. Ex: R$ 10,00 = 1000. Integer `amount`// Amount. Integer	Yes	Array
`shippings`	Determines the shipping amount(s) for a transaction. The same transaction can have unlimited shipping values. shipping attributes: `name`// shipping label. Maximum 255 characters. String. `value`// Shipping cost, in cents (1990 equivalent a R$19,90). Integer	No	Array
`metadata`	Define transaction-specific data metadata attributes: `custom_id`// It allows associating a Gerencianet transaction with a specific ID of your system or application, allowing you to identify it if you have a specific ID and want to keep it. Maximum of 255 characters. String/null. `notification_url`// Address of your valid URL that will receive transaction status change notifications. Maximum 255 characters. String/null.	No	Object

Objeto Payment

Attribute	Description	Mandatory	Type
`banking_billet`	Payment method via "boleto bancário"	Yes	Object Banking_Billet

Objeto Banking_Billet

Attribute	Description	Mandatory	Type
`name`	Client name. Minimum of 1 character and maximum of 255 characters (String).	Yes Obs: For juridical person, the name and CPF will not be mandatory, only the other customer data.	String
`cpf`	Valid customer ID (no dots, commas or hyphens). Size: 11 characters.	Yes Obs: For juridical person, the name and CPF will not be mandatory, only the other customer data.	String
`email`	customer email. Maximum 255 characters. Ex.: email@email.com	No	String
`phone_number`	customer phone. Format: no dots or commas, with 2-character area code (9th digit is optional). Ex.: 11988887777	Yes	String
`birth`	Customer's date of birth. Format: YYYY-MM-DD	No	String
`address`	customer address. address attributes: `street`// Name of the street (Object) `number`// Number (String/Integer) `neighborhood`// Neighborhood (String) `zipcode`// CEP (no dots or hyphen) (String) `city`// City (String) `complement`// Complement (String/null) `state`// State (2 caracteres) (Object)	No	Object
`juridical_person`	Juridical person data. attributes of juridical_person: `corporate_name`// Corporate name. Minimum of 1 character and maximum of 255. String. `cnpj`// CNPJ from the company. Size: 14 caracters. String.	No	Object
`expire_at`	Expiration date of boleto. Format: YYYY-MM-DD	Yes	String
`discount`	Defines discount data on the charge. discount attributes: type// discount type (String). Allowed values: `currency`:the discount will be reported in cents. `percentage`: the discount will be informed in percentage. `cnpj`// CNPJ from the company. Size: 14 caracters. String. value*// Discount amount (Integer). If the discount type is `currency` , the value of this tag must be informed by the integrator in cents (that is, 500 equals to R$ 5,00). If the discount type is `percentage`,the value must be multiplied by 100 (ie 1500 equals 15%). Examples: 1)`currency`// must be informed in cents, that is, if the discount will be R$ 5.99, the integrator must inform `599`; 2)`percentage` // must be informed in cents, that is, if the discount is 15%, the integrator must inform `1500`.	Não	Object
`conditional_discount`	Defines conditional discount that is valid until a specific date. If payment is not made by that date, the discount is invalidated. Conditional discount attributes: type// Discount type (String). Allowed values: `currency`: the discount will be reported in cents. `percentage`: the discount will be informed in percentage. `cnpj`// CNPJ from the company. Size: 14 caracteres. String. value// Discount amount (Integer). If the discount type is `currency` , the value of this tag must be informed by the integrator in cents (ie 500 is equivalent to R$ 5.00). If the discount type is `percentage`,the value must be multiplied by 100 (ie 1500 equals 15%). Examples: 1)`currency`// must be informed in cents, that is, if the discount will be R$ 5.99, the integrator must inform `599`; 2)`percentage` // must be informed in cents, that is, if the discount is 15%, the integrator must inform `1500`. until_date, // Maximum date the discount will be granted. (String). Format: YYYY-MM-DD	No	Object
`configurations`	Allows you to include a fine and interest in the ticket if it is paid after the due date. Attributes of configurations: fine// Amount charged after the due date. For example: if you want 2%, you must inform `200`.Minimum of 0 and maximum of 1000. Integer. If you have fine settings activated in Gestoret and want to generate API emissions without fines, use `0`as attribute value `fine` interest// Amount charged for interest per day after the due date. For example: if you want 0.033%, you must enter `33`.Minimum of 0 and maximum of 330. Integer. If you have fine settings activated in Gerencianet and want to generate interest-free issues in the API, use `0` as attribute value `interest`	No	Object
`message`	Allows you to include an "observation" in the ticket, or in other words, a message for the customer. This message can be seen in the emails related to the charge, in the boleto or carnet. Up to 4 lines containing 100 characters on each line. String. the operator `\n`is used to perform the line break.	No	String

Fields with * represent mandatory values

2. Two-Step Boleto Creation

Create the transaction, informing the item/product/service, value, quantity, etc;
Associate it with the payment method via boleto, informing the charge id of the transaction and the customer's data.

The rest of this page has the detailed procedures, but you need to install one of our libraries on your server to run the sample code. Make sure the Gerencianet SDK has been installed.

2.1. Create transaction

First, we need to generate the transaction (also called "charge"). It is at this moment that the name of the item/product/service, transaction value, quantity, among other possible information will be informed.

After creating it, the charge_id will be returned, which is the unique identifier of the transaction and will be used to associate the payment method.

As soon as this transaction is created, it receives the status new, which means that the charge has been generated and is awaiting definition of the payment method. This charge will only change its status when the integrator defines your payment method.

To generate a transaction, you must send a POST request to the /v1/charge route.

If you want, you can explore and learn more about this feature using our Playground.

The example below shows how this can be done, using the SDK's available:

<?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 = desenvolvimento 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']

// 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) Hierarchical structure of Schema attributes that can be used:

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

To check more details, access here and explore in our Playground.

b) Attributes that can be used to create a transaction:

Objeto items

Attribute	Description	Mandatory	Type
`items`	item being sold. The same transaction can have unlimited items. item attributes: `name`// Name of the item, product or service. Minimum of 1 character and maximum of 255 characters (String). `value`// Value, in cents. Ex: R$ 10,00 = 1000. Integer `amount`// Quantity. Integer	Yes	Array
`shippings`	Determines the shipping amount(s) for a transaction. The same transaction can have unlimited shipping values. Shipping attributes: `name`// shipping label. Maximum 255 characters. String. `value`// Shipping cost, in cents (1990 equals to R$19,90). Integer	No	Array
`metadata`	Define transaction-specific data metadata attributes: `custom_id`// It allows associating a Gerencianet transaction with a specific ID of your system or application, allowing you to identify it if you have a specific ID and want to keep it. Maximum 255 characters. String/null. `notification_url`//Address of your valid URL that will receive transaction status change notifications. Maximum 255 characters. String/null.	No	Object

Fields with * represent mandatory values

2.2. Associate to payment method via boleto

With the transaction successfully generated, we will now associate it with the desired payment method - in this case, it will be banking_billet. To do so, the charge_id obtained when creating the transaction must be informed.

At this moment, when defining boleto bancário as the payment method for the transaction, its status will be changed from new to waiting. This means that the payment method has been selected and is waiting for payment confirmation.

To associate with the payment method, you must send a POST request to the /v1/charge/:id/pay route, where :id is the charge_id of the desired transaction.

If you want, you can explore and learn more about this feature using our Playground..

The example below shows how this can be done, using the SDK's available:

<?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 = desenvolvimento 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) Hierarchical structure of Schema attributes that can be used:

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

To check more details, access here and explore in our Playground

b) Attributes that can be used to generate a Bolix, pix in the boleto bancário:

Attribute	Description	Mandatory	Type
`payment`	root tag	Yes	Object Payment

Object Payment

Attribute	Description	Mandatory	Type
`banking_billet`	Payment method via "boleto bancário"	Yes	Object Banking_Billet

Object Banking_Billet

Attribute	Description	Mandatory	Type
`name`	Customer name. Minimum of 1 character and maximum of 255 characters (String).	Yes Obs: For Juridical Person, the name and CPF will not be mandatory, only the other customer data.	String
`cpf`	CPF customer valid (no periods, commas or hyphens) Size: 11 characters.	Yes Obs: For Juridical Person, the name and CPF will not be mandatory, only the other customer data.	String
`email`	customer email. Maximum 255 characters. Ex.: email@email.com.	No	String
`phone_number`	customer phone. Format: no dots or commas, with 2-character area code (9th digit is optional). Ex.: 11988887777	Yes Obs: For Juridical Person, the name and CPF will not be mandatory, only the other customer data.	String
`birth`	Customer's date of birth. Format: YYYY-MM-DD	No	String
`address`	customer address. attributes of address: `street`// Street name (Object) `number`// Número (String/Integer) `neighborhood` (String) `zipcode`(String) `city`// Cidade (String) `complement` (String/null) `state`(2 caracteres) (Object)	No	Object
`juridical_person`	Juridical person data. Atributos de juridical_person: `corporate_name` Minimum of 1 character and maximum of 255. String. `cnpj` Size: 14 characters. String.	No	Object
`expire_at`	Boleto expiration date. Format: YYYY-MM-DD	Yes	String
`discount`	Defines discount data about the charge. discount attributes: type(String). Allowed values: `currency`: the discount will be reported in cents. `percentage`: the discount will be informed in percentage. `cnpj` Size: 14 characters. String. value* (Integer). If the discount type is `currency` , the value of this tag must be informed by the integrator in cents (that is, 500 is equivalent to R$ 5.00). If the discount type is `percentage`, the value must be multiplied by 100 (ie 1500 equals 15%). Examples: 1)`currency`// must be informed in cents, that is, if the discount will be R$ 5.99, the integrator must inform `599`; 2)`percentage` // must be informed in cents, that is, if the discount is 15%, the integrator must inform `1500`.	No	Object
`conditional_discount`	Defines conditional discount that is valid until a specific date. If payment is not made by that date, the discount is invalidated. Atributos de conditional_discount: type* (String). Allowed values: `currency`: the discount will be reported in cents. `percentage`: the discount will be informed in percentage. `cnpj`Size: 14 characters. String. value// discount amount (Integer). If the discount type is `currency` , the value of this tag must be informed by the integrator in cents (ie 500 is equivalent to R$ 5.00). If the discount type is `percentage`, the value must be multiplied by 100 (ie 1500 equals 15%). Examples: 1)`currency`// must be informed in cents, that is, if the discount will be R$ 5.99, the integrator must inform `599`; 2)`percentage` // must be informed in cents, that is, if the discount is 15%, the integrator must inform `1500`. until_date*, // Maximum date the discount will be granted. (String). Format: YYYY-MM-DD	No	Object
`configurations`	Allows you to include a fine and interest in the boleto if it is paid after the due date. Settings attributes: fine// Amount charged after the due date. For example: if you want 2%, you must inform `200`.Minimum of 0 and maximum of 1000. Integer. If you have fine settings activated in Gerencianet and want to generate API emissions without fines, use `0`as attribute value `fine` interest// Amount charged for interest per day after the due date. For example: if you want 0.033%, you must enter `33`.Minimum of 0 and maximum of 330. Integer. If you have fine settings activated in Gerencianet and want to generate interest-free issues in the API, use `0` as attribute value `interest`	No	Object
`message`	Allows you to include an "observation" in the ticket, or in other words, a message for the customer. This message can be seen in the emails related to the charge, in the boletos and carnês. Até 4 linhas contendo 100 caracteres em cada linha. String. O operador `\n`é utilizado para efetuar a quebra de linha.	No	String

Fields with * represent mandatory values

Payment made as a Juridical Person (PJ)

The customer associated with the transaction can be a Juridical Person. In this case, the Corporate Name and CNPJ of the paying company must be informed within the juridical_person attribute.

See details in this link on how to generate a payment whose payment method is "boleto Bancário" for a client who is a Juridical Person (PJ).

List of all possible statuses of a transaction

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 in this link all the details of the possible status of the transactions.

API transaction callbacks (notifications) to your system

Notifications allow you to be informed when a transaction has changed status. This way, you will be able to identify when a boleto is paid, for example.

Check out in this link all the details on how to implement your notification URL.

3. Other endpoints

There are other endpoints and methods related to payment via boleto bancário that are available in the API and can be explored by the integrator. Check out the complete list:

4. Videos: Creating transaction and generating boleto bancário

Thinking about offering new ways of transmitting information, Gerencianet makes available the following videos in order to explain, in a clear and objective way, how to create a transaction via integration and associate it with the payment method by "boleto bancario".

4.1. Creating transaction via Playground (test environment/sandbox)

4.2. Defining payment method by Boleto Bancário (via Playground)

4.3. Creating a transaction by integration - Payment by Boleto Bancario

5. Next steps

There are other API solutions that allow the use of payment by boleto bancário, do you want to know them?

Generate boleto bancário

1. Creating the Transaction in One Step

important

a) Hierarchical structure of Schema attributes that can be used:

b) Attributes that can be used to create a title:

2. Two-Step Boleto Creation

2.1. Create transaction

a) Hierarchical structure of Schema attributes that can be used:

b) Attributes that can be used to create a transaction:

2.2. Associate to payment method via boleto

a) Hierarchical structure of Schema attributes that can be used:

b) Attributes that can be used to generate a Bolix, pix in the boleto bancário:

Payment made as a Juridical Person (PJ)

List of all possible statuses of a transaction

API transaction callbacks (notifications) to your system

3. Other endpoints

4. Videos: Creating transaction and generating boleto bancário

4.1. Creating transaction via Playground (test environment/sandbox)

4.2. Defining payment method by Boleto Bancário (via Playground)

4.3. Creating a transaction by integration - Payment by Boleto Bancario

5. Next steps

NEED HELP?

FIND OUT MORE

UTILITIES

Acompanhe-nos

Generate boleto bancário

1. Creating the Transaction in One Step#

important

a) Hierarchical structure of Schema attributes that can be used:#

b) Attributes that can be used to create a title:#

2. Two-Step Boleto Creation#

2.1. Create transaction#

a) Hierarchical structure of Schema attributes that can be used:#

b) Attributes that can be used to create a transaction:#

2.2. Associate to payment method via boleto#

a) Hierarchical structure of Schema attributes that can be used:#

b) Attributes that can be used to generate a Bolix, pix in the boleto bancário:#

Payment made as a Juridical Person (PJ)

List of all possible statuses of a transaction

API transaction callbacks (notifications) to your system

3. Other endpoints#

4. Videos: Creating transaction and generating boleto bancário#

4.1. Creating transaction via Playground (test environment/sandbox)#

4.2. Defining payment method by Boleto Bancário (via Playground)#

4.3. Creating a transaction by integration - Payment by Boleto Bancario#

5. Next steps#

1. Creating the Transaction in One Step

a) Hierarchical structure of Schema attributes that can be used:

b) Attributes that can be used to create a title:

2. Two-Step Boleto Creation

2.1. Create transaction

a) Hierarchical structure of Schema attributes that can be used:

b) Attributes that can be used to create a transaction:

2.2. Associate to payment method via boleto

a) Hierarchical structure of Schema attributes that can be used:

b) Attributes that can be used to generate a Bolix, pix in the boleto bancário:

3. Other endpoints

4. Videos: Creating transaction and generating boleto bancário

4.1. Creating transaction via Playground (test environment/sandbox)

4.2. Defining payment method by Boleto Bancário (via Playground)

4.3. Creating a transaction by integration - Payment by Boleto Bancario

5. Next steps