Creating carnês

Learn how to generate a carnê for your customers. Carnê is a payment method that generates a set of transactions (installments) with the same payment and customer information in all of them - it is ideal for those who carry out sales in installments and also for those who work with monthly payments.

The installments of a carnê are due monthly, according to the date defined by the integrator. To generate a carnê, you need to provide the following data:

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

To create the carnê, you must send a POST request to the /v1/carnet route.

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

The following is an example code for creating a carnê using the available SDK's. Note that we are already defining the items, customer data, due date of the first installment of the carnê and the number of installments (in months):

1. Create Carnê

<?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' => '2020-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());
}

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"

To more details, click here and explore our Playground.

b) Attributes that can be used to create a carnê:

Attribute	Description	Required	Type
`items`	item being sold. The same transaction can have unlimited items. Item attributes: `name`// Name of the item, product or service. Minimum 1 character and maximum 255 characters (String). `value`// Value, in cents of Real. Ex: BRL 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` // Valid customer email address. (String) `phone_number` // Valid customer phone number, no special characters. (String) `birth` // Customer's date of birth (valid date in YYYY-MM-DD format) . (String) `address` // Shipping Address. (Object) (more info) `juridical_person` // Juridical Person data. (Object) (more info)	Yes	Object
`expire_at`	Payment expiration date. The interval of the installments of a carnê is always 1 (one) month between them. `Format: YYYY-MM-DD`	Yes	String
`repeats`	Number of installments in the carnê. `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`	Defines transaction specific data Metadata attributes: `custom_id`// Allows you to associate a Gerencianet transaction with a specific ID on your system or application, allowing you to identify it if you have a specific identification 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. Configuration attributes: fine// Amount charged for fine after expiration. For example: if you want 2%, you would enter `200`.Minimum of 0 and maximum of 1000. Integer. If you have fine settings enabled in Gerencianet and want to generate API emissions without fines, use `0` as the value of the `fine` attribute interest// Amount charged for interest per day after the due date. For example: if you want 0.033%, you would enter `33`.Minimum of 0 and maximum of 330. Integer. If you have fine settings activated in your Gerencianet and want to generate interest-free API issues, use `0` as the attribute value `interest`	No	Object
`message`	Allows you to include an "observation" in the billing, or in other words, a message to the customer. This message can be seen in e-mails related to billing, on the boleto or carnê. Up to 4 lines containing 100 characters in each line. String. The `\n` operator is used to perform the line break.	No	String
`discount`	Defines discount data about the charge. Discount attributes: type* // Type of discount (String). Allowed values: `currency`: the discount will be reported in cents. `percentage`: the discount will be informed in percentage. `cnpj`// CNPJ of the company. Size: 14 characters. String. value// Discount value (Integer). If the discount type is `currency` , the value of this tag must be informed by the integrator in cents (500 is equivalent to R$ 5.00). If the discount type is `percentage`, the value must be multiplied by 100 ( 1500 is equivalent to 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. Attributes of conditional_discount: type// Discount type (String). Allowed values: `currency`: the discount will be reported in cents. `percentage`: the discount will be informed in percentage. `cnpj`// CNPJ of the company. Size: 14 characters. String. value// Discount value (Integer). If the discount type is `currency` , the value of this tag must be informed by the integrator in cents ( 500 is equivalent to R$ 5.00). If the discount type is `percentage`, the value must be multiplied by 100 ( 1500 is equivalent to 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

payment made as 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 carnê for a client who is a Juridical Person (PJ).

List of all possible status of a carnê and installments

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

Check in this link for all the details of the possible status of carnets and installments.

Callbacks (notifications) of the installments and carnês from the API to your system

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

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

2. Other endpoints and methods

There are other carnê's endpoints and methods that are available in the API and can be exploited by the integrator. Check out the complete list:

3. Videos: Carnês

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 carnê through integration with our API.

3.1. Overview of Carnês (Gerencianet API integration)

3.2. Creating a transaction by issuing a carnê (Gerencianet API integration)

Complete Course on Integration with the Gerencianet API

For access to other classes, on other subjects, access the page Online Integration Course.

4. Next steps

With the carnês created, let's see how they work. Be sure to also check out all the carnês related endpoints.

Creating carnês

1. Create Carnê

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

b) Attributes that can be used to create a carnê:

payment made as Juridical Person (PJ)

List of all possible status of a carnê and installments

Callbacks (notifications) of the installments and carnês from the API to your system

2. Other endpoints and methods

3. Videos: Carnês

3.1. Overview of Carnês (Gerencianet API integration)

3.2. Creating a transaction by issuing a carnê (Gerencianet API integration)

Complete Course on Integration with the Gerencianet API

4. Next steps

NEED HELP?

FIND OUT MORE

UTILITIES

Acompanhe-nos

Creating carnês

1. Create Carnê#

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

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

payment made as Juridical Person (PJ)

List of all possible status of a carnê and installments

Callbacks (notifications) of the installments and carnês from the API to your system

2. Other endpoints and methods#

3. Videos: Carnês#

3.1. Overview of Carnês (Gerencianet API integration)#

3.2. Creating a transaction by issuing a carnê (Gerencianet API integration)#

Complete Course on Integration with the Gerencianet API

4. Next steps#

1. Create Carnê

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

b) Attributes that can be used to create a carnê:

2. Other endpoints and methods

3. Videos: Carnês

3.1. Overview of Carnês (Gerencianet API integration)

3.2. Creating a transaction by issuing a carnê (Gerencianet API integration)

4. Next steps