Other endpoints

There are other endpoints (services) available in the API that can be used in payment links:

Change certain parameters/attributes of an existing payment link
Cancel certain transaction
Change notification URL (notification_url) and/or transaction custom_id
Add information to transaction history
Return transaction information

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 certain parameters/attributes of an existing payment link

Allows you to update (change) certain parameters and attributes of a payment link created through PUT /v1/charge/:id/link, as long as payment confirmation has not occurred.

Some information that can be updated/changed in a payment link:

Update (change) allowed payment method;
Insertion of discounts (including conditional);
Changing the information message to the customer;
Due date of the payment link;
Request change (or not) of the buyer's delivery address.

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'; 
 
use Gerencianet\Exception\GerencianetException;
use Gerencianet\Gerencianet;
 
$clientId = 'informe_seu_client_id'; 
$clientSecret = 'informe_seu_client_secret'; 
 
$options = [
  'client_id' => $clientId,
  'client_secret' => $clientSecret,
  'sandbox' => true 
];
 

$params = [
  'id' => $charge_id
];

$body = [
  'billet_discount' => 0,
  'card_discount' => 0,
  'message' => '',
  'expire_at' => '2022-12-20',
  'request_delivery_address' => false,
  'payment_method' => 'all'
];

try {
  $api = new Gerencianet($options);
  $response = $api->updateChargeLink($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": "/ChargeLinkUpdate"
    "billet_discount": {
    "card_discount": {
    "conditional_discount": {
        "null"
            "id": "/ConditionalDiscount"
        "type": {
            "percentage"
            "currency"
        "value": {
        "until_date": {
    "message": {
    "expire_at": {
    "request_delivery_address": {
    "payment_method": {
        "banking_billet"
        "credit_card"
        "all"

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

b) Attributes that can be used to change certain parameters/attributes of an existing payment link:

Attribute	Description	Mandatory	Type
`billet_discount`	Defines a discount, in reais, if the payer chooses a boleto bancário as the payment method (inform the entire amount, in reais). 5000 is equivalent to R$ 50,00	No	Integer
`card_discount`	Defines a discount, in reais, if the payer chooses a credit card as the payment method (enter Integer value). 5000 is equivalent to R$ 50,00	No	Integer
`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 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
`message`	Defines a message for the payer. The message appears on the payment screen, in the billing-related emails and on boleto, if this is the chosen payment method. Minimum of 3 and maximum of 80 characters.	No	String
`expire_at`	Defines the due date of the payment screen and of the ticket itself, if this is the chosen payment method. Format: YYYY-MM-DD	Yes	String
`request_delivery_address`	Defines whether the payment screen should ask the payer to enter a delivery address. There are two possible values: `true` `false`	Yes	Boolean
`payment_method`	Defines the payment methods that must be available on the screen for your customer to choose, which can be: `banking_billet` (boleto bancário) `credit_card` (cartão de crédito) `all` (allow payment via boleto and credit card)	Yes	Object

Fields with * represent mandatory values

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, you must send a PUT request to the /v1/charge/:id/cancel 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
];
 
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:

Attribute	Description	Mandatory	Type
`notification_url`	Address of your valid URL that will receive transaction status change notifications. Maximum of 255 characters	No	String/null
`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	No	String

4. Add information to transaction history

Otransaction history represents all actions that have occurred with this transaction up to the present time. 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:

Attribute	Description	Mandatory	Type
`description`	Allows you to add information to the transaction history. Minimum of 1 character and maximum of 255 characters.	Yes	String

5. Return transaction information

To return information from a transaction, you must send a GET request to the /v1/charge/:id 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)
];

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

Other endpoints

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

1. Change certain parameters/attributes of an existing payment link

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

b) Attributes that can be used to change certain parameters/attributes of an existing payment link:

2. Cancel certain transaction

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

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

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

4. Add information to transaction history

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

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

5. Return transaction information

NEED HELP?

FIND OUT MORE

UTILITIES

Acompanhe-nos

Other endpoints

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

1. Change certain parameters/attributes of an existing payment link#

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

b) Attributes that can be used to change certain parameters/attributes of an existing payment link:#

2. Cancel certain transaction#

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

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

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

4. Add information to transaction history#

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

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

5. Return transaction information#

1. Change certain parameters/attributes of an existing payment link

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

b) Attributes that can be used to change certain parameters/attributes of an existing payment link:

2. Cancel certain transaction

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

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

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

4. Add information to transaction history

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

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

5. Return transaction information