Other endpoints

There are other endpoints (services) available in the API that can be used in boleto bancário transactions:

  1. Change boleto bancário due date

  2. Cancel certain transaction

  3. Change notification URL (notification_url) and/or transaction custom_id

  4. Resend boleto bancário by email

  5. Add information to transaction history

  6. Return transaction information

  7. Mark a transaction as paid

Before proceeding, make sure that the Gerencianet SDK has been installed

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


1. Change due date from boleto bancário

Allows you to change the due date of a transaction whose payment method is banking_billet (boleto bancário) and which has not yet been paid.

To do so, you must enter the charge_id of the desired transaction and the new expiration date in YYYY-MM-DD format within the expire_at attribute. You must send a PUT request to the route /v1/charge/:id/billet, where :id is the charge_id of the ticket you want to update.

important

The new due date must be at least greater than the current due date.


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
];
$body = [
'expire_at' => '2022-12-20'
];
try {
$api = new Gerencianet($options);
$charge = $api->updateBillet($params, $body);
print_r($charge);
} catch (GerencianetException $e) {
print_r($e->code);
print_r($e->error);
print_r($e->errorDescription);
} catch (Exception $e) {
print_r($e->getMessage());
}

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

"id": "/ChargeBilletUpdate"
"expire_at"

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


b) Atributo que pode ser utilizado para atualizar data de vencimento de boleto:

AtributoDescriçãoObrigatórioTipo
expire_atData de vencimento do boleto.
Formato: YYYY-MM-DD		SimString

2. Cancel certain transaction

A transaction can only be canceled if it has the status new, waiting, unpaid or link.

Once a transaction is cancelled, there is only one condition for this status to be changed again: if the customer prints the slip before the integrator cancels the transaction, he or she can make the payment normally at a bank branch. In this case, the integrator and the payer receive payment confirmation as usual and the charge status is changed from canceled to paid.

To cancel a transaction (for example, cancel a boleto), you must send a PUT request to the route /v1/charge/:id/cancel, where :id is the charge_id of the desired transaction.

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 ("charge_id")
$params = [
'id' => $charge_id
];
try {
$api = new Gerencianet($options);
$charge = $api->cancelCharge($params, []);
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());
}

3. Change notification URL (notification_url) and/or transaction custom_id

You can set or change the information sent in the transaction's metadata property at any time. This endpoint is extremely important for updating your transaction-linked notification URL or modifying the custom_id previously associated with your transactions.

To change the notification_url and/or custom_id of a transaction, you must send a PUT request to the /v1/charge/ route :id/metadata, where :id is the charge_id of the desired transaction.

Use cases for this endpoint:

  • Integrator changed the server IP that was associated in the transaction notification URL;

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

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

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

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

  • Among other possible scenarios.

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 ("charge_id")
$params = [
'id' => $charge_id
];
$body = [
'custom_id' => 'REF0001', // associar transação Gerencianet com seu identificador próprio
'notification_url' => 'http://seu_dominio.com/notification' // url de notificação
];
try {
$api = new Gerencianet($options);
$charge = $api->updateChargeMetadata($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": "/ChargeMetadataUpdate"
"notification_url"
"custom_id"

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


b) Attributes that can be used to update notification URL and/or custom_id:

AttributeDescriptionMandatoryType
notification_urlAddress of your valid URL that will receive transaction status change notifications.
Maximum of 255 characters		NoString/null
custom_idIt 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		NoString

4. Resend boleto bancário by email

A transaction that has banking_billet (boleto bancário) as a payment method and whose status is waiting or unpaid, can have the boleto resent by e- mail.

To do so, simply send your identifier charge_id and the valid email address to which the boleto should be sent.

To resend a boleto by email, you must send a POST request to the route /v1/charge/:id/billet/resend, where :id is the charge_id of the desired transaction.

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 ("charge_id")
$params = [
'id' => $charge_id
];
$body = [
'email' => 'email_do_cliente@servidor.com.br'
];
try {
$api = new Gerencianet($options);
$response = $api->resendBillet($params, $body);
print_r($response);
} catch (GerencianetException $e) {
print_r($e->code);
print_r($e->error);
print_r($e->errorDescription);
} catch (Exception $e) {
print_r($e->getMessage());
}

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

"id": "/ChargeBilletResend"
"email"

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


b) Attribute that can be used to resend a boleto by email:

AttributeDescriptionMandatoryType
emailPlease provide a valid email address to which the ticket should be sent.YesString

5. Add information to transaction history

The history of a transaction represents all the actions that have taken place with that transaction to date. Personalized messages do not influence the transaction itself, only its history.

This can be viewed both in the transaction details through the interface and using the transaction details endpoint.

To do so, just send the identifier charge_id and the message to be added to the transaction history.

To add custom messages to a transaction's history, you must send a POST request to the /v1/charge/:id/history route, where :id is the charge_id of the desired transaction.

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 ("charge_id")
$params = [
'id' => $charge_id
];
$body = [
'description' => 'Custom history' // mensagem que será inserida ao histórico do carnê
];
try {
$api = new Gerencianet($options);
$response = $api->createChargeHistory($params, $body);
print_r($response);
} catch (GerencianetException $e) {
print_r($e->code);
print_r($e->error);
print_r($e->errorDescription);
} catch (Exception $e) {
print_r($e->getMessage());
}

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

"id": "/ChargeHistory"
"description"

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


b) Attribute that can be used to add messages to the transaction history:

AttributeDescriptionMandatoryType
descriptionAllows you to add information to the transaction history.
Minimum of 1 character and maximum of 255 characters.		YesString

6. Return transaction information

To return information from a transaction (such as a boleto, for example), you must send a request GET to the route /v1/charge/:id, where :id is the charge_id of the desired transaction.

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)
];
$params = [
'id' => $charge_id // $charge_id refere-se ao ID da transação ("charge_id")
];
try {
$api = new Gerencianet($options);
$charge = $api->detailCharge($params, []);
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());
}

7. Mark a transaction as paid

For details on how to mark a transaction as paid, see this link.