Other endpoints

There are other endpoints (services) available in the API that can be used in credit card transactions:

  1. Cancel certain transaction
  2. Change notification URL (notification_url) and/or transaction custom_id
  3. Add information to transaction history
  4. Return transaction information
  5. List installments, according to the credit card brand
Before proceeding, make sure that the Gerencianet SDK has been installed

The rest of this page presents the detailed procedures, but you need to install one of our libraries on your server to run the example codes.

1. Cancel certain transaction

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

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

To cancel a transaction, you must submit a request PUT 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'; // SDK-related path
use Gerencianet\Exception\GerencianetException;
use Gerencianet\Gerencianet;
$clientId = 'informe_seu_client_id'; // enter your Client_Id, depending on the environment (Des or Prod)
$clientSecret = 'informe_seu_client_secret'; // enter your Client_Secret, depending on the environment (Des or Prod)
$options = [
'client_id' => $clientId,
'client_secret' => $clientSecret,
'sandbox' => true // change according to the environment (true = development and false = production)
];
// $charge_id refers to the transaction ID ("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());
}

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

You can set or change the information sent in the property metadata of the transaction 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 request PUT to the route /v1/charge/: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 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'; // SDK-related path
use Gerencianet\Exception\GerencianetException;
use Gerencianet\Gerencianet;
$clientId = 'informe_seu_client_id'; // enter your Client_Id, depending on the environment (Des or Prod)
$clientSecret = 'informe_seu_client_secret'; // enter your Client_Secret, depending on the environment (Des or Prod)
$options = [
'client_id' => $clientId,
'client_secret' => $clientSecret,
'sandbox' => true // change according to the environment (true = development and false = production)
];
// $charge_id refers to the transaction ID ("charge_id")
$params = [
'id' => $charge_id
];
$body = [
'custom_id' => 'REF0001', // associate Gerencianet transaction with its own identifier
'notification_url' => 'http://seu_dominio.com/notification' // notification url
];
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"

To check more details, go 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

3. 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'; // SDK-related path
use Gerencianet\Exception\GerencianetException;
use Gerencianet\Gerencianet;
$clientId = 'informe_seu_client_id'; // enter your Client_Id, depending on the environment (Des or Prod)
$clientSecret = 'informe_seu_client_secret'; // enter your Client_Secret, depending on the environment (Des or Prod)
$options = [
'client_id' => $clientId,
'client_secret' => $clientSecret,
'sandbox' => true // change according to the environment (true = development and false = production)
];
// $charge_id refers to the transaction ID ("charge_id")
$params = [
'id' => $charge_id
];
$body = [
'description' => 'Custom history' // message that will be added to the charge history
];
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"

To check more details, go 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

4. Return transaction information

To return information from a transaction (such as a billet, for example), you must send a request GETto 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'; // SDK-related path
use Gerencianet\Exception\GerencianetException;
use Gerencianet\Gerencianet;
$clientId = 'informe_seu_client_id'; // enter your Client_Id, depending on the environment (Des or Prod)
$clientSecret = 'informe_seu_client_secret'; // enter your Client_Secret, depending on the environment (Des or Prod)
$options = [
'client_id' => $clientId,
'client_secret' => $clientSecret,
'sandbox' => true // change according to the environment (true = development and false = production)
];
$params = [
'id' => $charge_id // $charge_id refers to the transaction ID ("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());
}

5. List installments, according to the credit card brand

The installments endpoint is used to list the installments of each credit card brand, with the interest values and number of installments calculated according to the integrating account. That is, if your account has a card interest setting (option available for customers who have chosen to receive card amounts in installments), it is not necessary to make any calculations, this endpoint already informs the calculated amounts.

Available brand: visa, mastercard, amex, elo and hipercard.

The example below shows how this can be done, using the SDK's available:

<?php
require __DIR__.'/../../vendor/autoload.php'; // SDK-related path
use Gerencianet\Exception\GerencianetException;
use Gerencianet\Gerencianet;
$clientId = 'informe_seu_client_id'; // enter your Client_Id, depending on the environment (Des or Prod)
$clientSecret = 'informe_seu_client_secret'; // enter your Client_Secret, depending on the environment (Des or Prod)
$options = [
'client_id' => $clientId,
'client_secret' => $clientSecret,
'sandbox' => true // change according to the environment (true = development and false = production)
];
$params = [
'total' => '20000',
'brand' => 'visa'
];
try {
$api = new Gerencianet($options);
$installments = $api->getInstallments($params, []);
print_r($installments);
} catch (GerencianetException $e) {
print_r($e->code);
print_r($e->error);
print_r($e->errorDescription);
} catch (Exception $e) {
print_r($e->getMessage());
}