Bolix

Bolix, pix on boleto, allows you to generate boleto and carnet transactions for your customer with the addition of Pix as a payment method. The Bolix when issued in the form of a boleto can be generated via API in one step, also known as One Step or in two steps, the Two Steps. The issuance of Bolix as a carnet is also available, which consists of a set of transactions (installments) generated in installments and with a payment method already defined with monthly maturity.

All flows and information for Bolix issuances both as boleto and carnê are detailed below.:

Creating Bolix with the payment method Boleto Bancário, transaction in One Step.
Creating Bolix with Boleto Bancário payment method, transaction in Two Steps (Two Steps).
Creating Bolix with the carnet payment method.

Activation of Bolix

1- Access your Digital Account at web platform.

2- Click on Collections > Settings > Boletos Bancário and Carnets.

3- Finally, enable the “Bolix” function like this image.

SDK's

The rest of this page presents the detailed procedures for creating Bolix with the boleto bancário and carnê payment methods, but you need to install one of our libraries on your server to run the example codes. Make sure the Gerencianet SDK has been installed.

1. Creation of Bolix, boleto with pix, 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:

<?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' => '2023-08-30' // data máxima para aplicação do desconto
   ];
   $bankingBillet = [
       'expire_at' => '2023-09-01', // data de vencimento do titulo
       'message' => 'Pay by barcode or 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 = 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());
   }

Bolix input and output data in One Step:

Dados de entrada
Dados de saída

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

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. Creation of Bolix, boleto with pix, in Two Steps

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());
}

Input and output data in transaction creation:

Dados de entrada
Dados de saída

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

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());
}

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

Dados de entrada
Dados de saída

{
  "payment": {
    "banking_billet": {
      "customer": {
        "name": "Gorbadoc Oldbuck",
        "cpf": "94271564656",
        "email": "email_do_cliente@servidor.com.br",
        "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) 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"

For more details, click here e explore em nosso 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. Generating a Bolix with the carnet payment method

Carnet is a payment method that generates a set of transactions (installments) with the same payment and customer information in all of them, the installments of a carnet are due monthly, according to the date defined by the integrator. To generate a carnet, you need to provide the following data:

Items (or service) offered;
Due date of the 1st installment;
Number of installments (repetitions).

Below is an example code for creating a Bolix with the payment method using the available SDK's. Note that we are already defining the items, customer data, due date of the first installment of the booklet and the number of repetitions (in months):

<?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
]
 
$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' => '2020-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
];

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());
}

Input and output data when creating Bolix with the payment method:

Dados de entrada
Dados de saída

{
  "items": [
    {
      "name": "Meu Produto",
      "value": 7500,
      "amount": 1
    }
  ],
  "customer": {
    "name": "Gorbadoc Oldbuck",
    "cpf": "94271564656",
    "phone_number": "5144916523"
  },
  "expire_at": "2022-12-20",
  "configurations": {
        "fine": 200,
        "interest": 33
      },
  "message": "Este carnê aceita o pagamento por QR Code Pix e por código de barras",
  "repeats": 3,
  "split_items": false
}

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

"id": "/Carnet"
    "items"
        "name"
        "value"
        "amount"
    "customer"
        "name"
        "cpf"
        "email"
        "phone_number"
        "birth"
        "address"
            "street"
            "number"
            "neighborhood"
            "zipcode"
            "city"
            "complement"
            "state"
        "juridical_person"
            "corporate_name"
            "cnpj"
    "expire_at"
    "repeats"
    "split_items"
    "metadata"
        "custom_id"
        "notification_url"
    "configurations"
        "fine"
        "interest"
    "message"
    "discount"
        "type"
            "percentage",
            "currency"
        "value"
    "conditional_discount"
        "type"
            "percentage",
            "currency"
        "value"
        "until_date"

For more details, click here and explore in our Playground.

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

Attribute	Description	Mandatory	Type
`items`	item being sold. The same transaction can have unlimited items. item attributes: `name`Minimum of 1 character and maximum of 255 characters (String). `value` Ex: R$ 10,00 = 1000. Integer `amount`Integer	Yes	Array
`customer`	Payer's personal data. Customer attributes: `name`(String) `cpf` // Customer CPF (no dots, commas or hyphens).(String) `email` (String) `phone_number` // Valid customer phone number, no special characters. (String) `birth` (String) `address` (Object) (more information) `juridical_person`(Object)	Yes	Object
`expire_at`	Expiry date of the card. The interval of the installments of a carnet is always 1 (one) month between them. `Format: YYYY-MM-DD`	Yes	String
`repeats`	Number of installments of the carnet. `Minimum of 2 installments and maximum of 12 installments`	Yes	Integer
`split_items`	Split items between parcels. Defines if the carnê items will be divided between the installments (true), or if the value of each installment will be the total value of the items (false).	No	Boolean
`metadata`	Define transaction-specific data metadata attributes: `custom_id`// It allows associating a Gestãonet 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
`configurations`	Allows you to include a fine and interest in the carnê 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 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 charge, or in other words, a message to the customer. This message can be seen in the emails related to the charge, in the carnet or boleto. Up to 4 lines containing 100 characters on each line. String. the operator `\n`is used to perform the line break.	No	String
`discount`	Defines discount data about 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 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`.	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. 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`// company's 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

Fields with * represent mandatory values

Bolix 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 attribute juridical_person.

See details at this link on how to generate a booklet for a client who is a Juridical Person (PJ).

List of all possible statuses of a transaction

All carnets have status, which represents the "situation" of that carnet. Therefore, it is important to know the possible statuses in the API to provide the proper handling in your system.

Check out this link all the details of the possible status of the carnets and installments of the carnet.

Callbacks (notifications) of Bolix transactions from the API to your system

Notifications allow you to be informed when a parcel or carnet has its status changed. In this way, you will be able to identify when an installment is paid, for example.

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

4. Other Bolix 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:

5. Next steps

There are other API solutions that allow the use of Bolix with the payment method by bank slip, do you want to know them?

Bolix

Activation of Bolix

SDK's

1. Creation of Bolix, boleto with pix, in One Step

Bolix input and output data in One Step:

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

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

2. Creation of Bolix, boleto with pix, in Two Steps

2.1. Create transaction

Input and output data in transaction creation:

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

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

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. Generating a Bolix with the carnet payment method

Input and output data when creating Bolix with the payment method:

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

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

Bolix payment made as a Juridical Person (PJ)

List of all possible statuses of a transaction

Callbacks (notifications) of Bolix transactions from the API to your system

4. Other Bolix endpoints

5. Next steps

NEED HELP?

FIND OUT MORE

UTILITIES

Acompanhe-nos

Bolix

Activation of Bolix

SDK's

1. Creation of Bolix, boleto with pix, in One Step#

Bolix input and output data in One Step:#

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

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

2. Creation of Bolix, boleto with pix, in Two Steps#

2.1. Create transaction#

Input and output data in transaction creation:#

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#

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

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. Generating a Bolix with the carnet payment method#

Input and output data when creating Bolix with the payment method:#

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

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

Bolix payment made as a Juridical Person (PJ)

List of all possible statuses of a transaction

Callbacks (notifications) of Bolix transactions from the API to your system

4. Other Bolix endpoints#

5. Next steps#

1. Creation of Bolix, boleto with pix, in One Step

Bolix input and output data in One Step:

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

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

2. Creation of Bolix, boleto with pix, in Two Steps

2.1. Create transaction

Input and output data in transaction creation:

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

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

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. Generating a Bolix with the carnet payment method

Input and output data when creating Bolix with the payment method:

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

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

4. Other Bolix endpoints

5. Next steps