Playground: Carnê

To acess the sandbox environmet you will need a Gerencianet account. Create your account.

The Playground (also called as "sandbox") it is a development/test environment in which the integrator, regardless of the operation to be performed, can use to learn about the payment mechanism and flow in a 100% test and uncomplicated environment. Know more about the Gerencianet's sandbox environment.

A "carnê" is a set of transactions (installments) generated with a payment method already defined. The installments of a carnê are due monthly, according to the date defined by the integrator. For more details about carnês, check out the specific section.

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).

Next, check all the endpoints present in our Playground, in the "Carnês" modality:


POST /v1/carnet

Used to generate a set of transactions (installments) generated with a payment method already defined. The installments of a carnê are due monthly, according to the date defined by the integrator.

A carnê has the active status until the last installment is due.

The main attributes of carnê's creation are:

  • Item: item being sold;
  • Customer: payer's personal info;
  • Expire_at: expiration of the first installment of the carnê;
  • Repeats: number of installments of the carnê.

It should also be noted that each carnê generated has a unique identification called carnet_id, and each installment of this carnê also has a unique identifier called charge_id.

In the following image, you can see the screen of our test environment, which contains the resources linked to the POST /v1/carnet method that are available for use:

{
"items": [
{
"name": "Meu Produto",
"value": 7500,
"amount": 1
}
],
"customer": {
"name": "Gorbadoc Oldbuck",
"cpf": "94271564656",
"phone_number": "5144916523"
},
"expire_at": "2021-12-20",
"configurations": {
"fine": 200,
"interest": 33
},
"message": "Este é um espaço de até 80 caracteres para informar algo a seu cliente",
"repeats": 5,
"split_items": false
}

This JSON creates a carnê, in which the name of the product/service is "Meu Produto", value R$ 75.00 and quantity 1, with the buyer's data, the due date of the first installment on 12/20/2018 and containing 5 installments (in months).. That is, it is a carnê containing 5 installments of R$ 75.00, totaling R$ 375.00, with the first installment of R$ 75.00 due on 12/20/2018, the second on 20/20 01/2019, and so on. Also, we are using a message of up to 80 characters to inform the customer something, and if the PARCEL is paid after the expiry date, will be charged 2% fine and 0.033% interest per day.


GET /v1/carnet/:id

Returns information about a created carnê. Each transaction created for each carnê has a unique identifier key.

In the following image, you can see the screen of our test environment, which contains the resources linked to the GET /v1/carnet/:id method that are available for use:

The following is a simple JSON that can be used to return information about a carnê created in Playground. Also, you can look at the predicted output available for this method. Remembering that it is also necessary to inform the carnet_id input parameter of the CARNÊ:

Input parameter: inform the "carnet_id" of the created carnê

This JSON returns information from a carnê created in Playground, as can be seen in the "Dados de saída" tab.


PUT /v1/carnet/:id/metadata

Allows you to include information such as notification_url and custom_id in a carnê. For that, you need to inform the carnet_id of the existing carnê in which you want to include this information. This endpoint is extremely important to update your notification URL linked to the carnê or modify the custom_id previously associated in the carnê.

  • notification_url: is a valid URL address that will receive notifications of transaction status changes. Confirmations, failures or any type of status change will be reported to the URL provided when generating the carnê;
  • custom_id: 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.

Use cases for this endpoint:

  • Integrator changed the server IP that was associated in the subscription/transactions notification URL;

  • Integrator has updated the notification URL for new subscriptions/transactions that are created, but needs to update also on previous subscriptions/transactions that were generated and that are associated with the incorrect/outdated URL;

  • SSL (https) has been installed on the client's server and even if the client defines a 301 or 302 redirect rule, it will be necessary to define the new URL in the subscriptions/transactions that have the "old" URL;

  • Integrator generated charges and had not informed the notification URL when sending the subscription/transaction creation request;

  • Modify or add information next to the custom_id attribute associated with previously generated signatures/transactions;

  • And others possible scenarios.

In the following image, you can see the screen of our test environment, which contains the resources linked to the PUT /v1/subscription/:id/metadata method that are available for use:

The following is a simple JSON that can be used to change the notification URL and the custom_id of an existing carnê in the Playground. Also, you can see the predicted output and validation schema with all tags (required and optional) available for this method. Remembering that it is also necessary to inform the carnet_id input parameter of the carnê:

{
"notification_url": "htttp://www.meusite.com.br/notificacoes/",
"custom_id": "258789877"
}

This JSON allows you to change the notification URL and custom_id of a carnê created.


PUT /v1/carnet/:id/parcel/:parcel

Allows you to change the due date of a certain installment of a carnê. To do so, you need to inform the carnet_id, the installment you want and the expire_at (new expiration date, in the format YYYY-MM-DD).

Only installments that have a waiting or unpaid status can have their due dates changed.

In the following image, you can see the screen of our test environment, which contains the resources linked to the PUT /v1/carnet/:id/parcel/:parcel method that are available for use:

The following is a simple JSON that allows you to change the due date of a certain installment of a carnê. Also, you can see the predicted output and validation schema with all tags (required and optional) available for this method. Remembering that you must inform the carnet_id and the number of the installment that you want to change the due date.

{
"notification_url": "htttp://www.meusite.com.br/notificacoes/",
"custom_id": "258789877"
}
This JSON changes the due date of a boleto in the Playground, changing the due date of a certain installment of a carnê to 12/30/2018.

PUT /v1/carnet/:id/cancel

Allows you to cancel a specific carnê. To do so, you must inform the carnet_id you want to cancel.

In the following image, you can see the screen of our test environment, which contains the resources linked to the PUT /v1/carnet/:id/cancel method that are available for use:

The following is a simple JSON that can be used to cancel a certain carnê. Also, you can see the predicted output and validation schema with all tags (required and optional) available for this method:

Input parameter: inform the "carnet_id" of the desired carnê

This JSON performs the cancellation of a certain carnê created in Playground.


PUT /v1/carnet/:id/parcel/:parcel/cancel

Allows you to cancel a specific parcel of an existing carnê. To do so, you must inform the carnet_id and the number of the installment you wish to cancel.

In the following image, you can see the screen of our test environment, which contains the resources linked to the PUT /v1/carnet/:id/parcel/:parcel/cancel method that are available for use:

The following is a simple JSON that can be used to cancel a specific parcel of an existing carnê. Also, you can look at the predicted output available for this method. Remembering that it is also necessary to inform the carnet_id input parameter and the installment number of the carnê:

Input parameter: inform the "carnet_id" and the "parcel number" of the carnet

This JSON allows you to cancel a specific parcel of an existing carnet that was created in Playground.


POST /v1/carnet/:id/resend

This method allows the carnê to be forwarded to an email address. You must inform the carnet_id of the carnê.

In the following image, you can see the screen of our test environment, which contains the resources linked to the POST /v1/carnet/:id/resend method that are available for use:

The following is a simple JSON that can be used to resend by email a certain carnê created in Playground. Also, you can see the predicted output and validation schema with all tags (required and optional) available for this method. Remembering that it is also necessary to inform the carnet_id input parameter of the carnê:

{
"email": "email_do_cliente@servidor.com.br"
}

This JSON defines that the address "email_do_cliente@servidor.com.br" will receive a duplicate of a certain carnê that was created in Playground.


POST /v1/carnet/:id/parcel/:parcel/resend

This method allows a certain parcel of a carnê to be resent to an email address. To do so, you must enter the carnet_id.

In the following image, you can see the screen of our test environment, which contains the resources linked to the POST /v1/carnet/:id/parcel/:parcel/resend method that are available for use:

The following is a simple JSON that can be used to resend by email a certain carnê created in Playground. Also, you can see the predicted output and validation schema with all tags (required and optional) available for this method. Remembering that you also need to inform the input parameter carnet_id and the number of the parcel you want to resend:

{
"email": "email_do_cliente@servidor.com.br"
}

This JSON defines that the address "email_do_cliente@servidor.com.br" will receive a duplicate of a parcel of a carnê that was created in Playground.


POST /v1/carnet/:id/history

The history of a carnê is similar to the history of a transaction. However, it reflects the actions that the carnê itself suffered. And, in the same way, it is possible to add personalized messages to the history of a carnê, without these, however, influencing the internal process of the carnê.

To do so, you must inform the carnet_id of the carnê. This description must have a minimum of one character and a maximum of 255 characters.

In the following image, you can see the screen of our test environment, which contains the resources linked to the POST /v1/carnet/:id/history method that are available for use:

The following is a simple JSON that can be used to add a description to a carnê in the Playground. Also, you can see the predicted output and validation schema with all tags (required and optional) available for this method. Remembering that it is also necessary to inform the carnet_id input parameter of the carnê:

{
"description": "Camisa Polo tamanho G cor azul"
}

This JSON adds the description "Camisa Polo tamanho G cor azul in a certain carnê that was created in the Playground.


PUT /v1/carnet/:id/parcel/:parcel/settle

Allows you to mark as paid (manual paid) a certain installment of a carnê. To do so, you must inform the carnet_id and the installment number of the carnê you wish to mark as paid.

That is, if you have a carnê of 12 installments whose carnet_id is 24744 and you want to mark the 2nd installment as "paid", you must pass the carnet_id and the number 2.

In the following image, it is possible to observe the screen of our test environment, which contains the resources linked to the PUT /v1/carnet/:id/parcel/:parcel/settle method that are available for use:

The following is a simple JSON that can be used to mark as paid a certain installment of a carnê created in Playground. Also, you can look at the predicted output available for this method. Remembering that you must inform the carnet_id and the number of the parcel you want to mark as paid:

Input parameter: inform the "carnet_id" and the number of the installment of the carnê you want to mark as paid