Others endpoints

There are another endpoints (services) available in the API that can be used in subscriptions:

  1. List existing subscription plans

  2. Cancel subscription plan

  3. Return subscription information linked to a plan

  4. Cancel active subscriptions on a plan

  5. Change notification URL (notification_url) and/or custom_id of subscriptions

  6. List installments, according to the credit card brand

  7. Add information to subscription history

  8. Edit subscription plan name

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

The rest of this page provides detailed procedures, but you need to install one of our libraries on your server to run the sample code.


1. List existing subscription plans

Allows you to list the subscription plans created. There are advanced filters that can be used to find, such as:

  • Name: returns results from the search for the name of the previously registered plan;
  • Limit: maximum limit of response records;
  • Offset: determines from which register the search will be performed.

To return information demonstrating the subscription plans already created, you must send a GET request to the /v1/plans route.

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 = ['limit' => 20, 'offset' => 0];
try {
$api = new Gerencianet($options);
$plans = $api->getPlans($params, []);
print_r($plans);
} catch (GerencianetException $e) {
print_r($e->code);
print_r($e->error);
print_r($e->errorDescription);
} catch (Exception $e) {
print_r($e->getMessage());
}

2. Cancel subscription plan

Allows you to cancel a subscription plan. To do so, you must enter the plan_id of the subscription plan you wish to cancel.

To cancel a subscription plan, you must send a DELETE request to the /v1/plan/:id route, where :id is the plan_id of the plan you want to cancel.

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)
];
// $plan_id refere-se ao "plan_id" do plano
$params = [
'id' => $plan_id
];
try {
$api = new Gerencianet($options);
$plan = $api->deletePlan($params, []);
print_r($plan);
} catch (GerencianetException $e) {
print_r($e->code);
print_r($e->error);
print_r($e->errorDescription);
} catch (Exception $e) {
print_r($e->getMessage());
}

3. Return subscription information linked to a plan

Allows you to search for information about a subscription that is linked to a plan. To do so, you must inform the subscription_id of the subscription you want to search for.

To return information from a subscription linked to a plan, you must send a GET request to the /v1/subscription/:id route, where :id is the subscription_id of the subscription.

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)
];
// $subscription_id refere-se ao "subscription_id" da assinatura
$params = [
'id' => $subscription_id
];
try {
$api = new Gerencianet($options);
$subscription = $api->detailSubscription($params, []);
print_r($subscription);
} catch (GerencianetException $e) {
print_r($e->code);
print_r($e->error);
print_r($e->errorDescription);
} catch (Exception $e) {
print_r($e->getMessage());
}

4. Cancel active subscriptions on a plan

Allows you to cancel active subscriptions on a plan. To do so, you must inform the subscription_id of the subscription you want to cancel.

To cancel active subscriptions in a subscription plan, you must send a PUT request to the /v1/subscription/:id/cancel route, where :id is the subscription_id of the subscription.

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)
];
// $subscription_id refere-se ao "subscription_id" da assinatura
$params = [
'id' => $subscription_id
];
try {
$api = new Gerencianet($options);
$subscription = $api->cancelSubscription($params, []);
print_r($subscription);
} catch (GerencianetException $e) {
print_r($e->code);
print_r($e->error);
print_r($e->errorDescription);
} catch (Exception $e) {
print_r($e->getMessage());
}

5.Change notification URL (notification_url) and/or custom_id of subscriptions

You can set or change the information sent in the metadata property of a subscription at any time. This endpoint is extremely important for updating your notification URL tied to subscriptions or modifying the custom_id previously associated with the subscription.

In this case, all transactions belonging to the subscription will be updated.

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

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 also needs to update on previous subscriptions/transactions 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 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 subscriptions/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;
$file = file_get_contents(__DIR__.'/../config.json');
$options = json_decode($file, true);
// $subscription_id refere-se ao "subscription_id" da assinatura
$params = [
'id' => $subscription_id
];
$body = [
'notification_url' => 'http://localhost.com',
'custom_id' => 'Custom Subscription 0001'
];
try {
$api = new Gerencianet($options);
$subscription = $api->updateSubscriptionMetadata($params, $body);
print_r($subscription);
} 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": "/SubscriptionMetadataUpdate"
"notification_url"
"custom_id"

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


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

AttributeDescriptionRequiredType
notification_urlAddress of your valid URL that will receive transaction status change notifications.
Maximum 255 characters		NoString/null
custom_idAllows you to associate 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

6. 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 brands: 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'; // 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 = [
'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());
}

7. Add information to subscription history

The history of a subscription is similar to the history of a transaction. However, it reflects the actions that the signature suffered. And, in the same way, it is possible to add personalized messages to the history of a subscription, without influencing in the flow of the same.

To add custom messages to the history of a subscription, you must send a POST request to the route /v1/subscription/:id/history, where :id is the subscription_id of the subscription.

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)
];
// $subscription_id refere-se ao ID da assinatura desejada
$params = [
'id' => $subscription_id
];
$body = [
'description' => 'Esta assinatura é sobre um serviço'
];
try {
$api = new Gerencianet($options);
$response = $api->createSubscriptionHistory($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": "/SubscriptionHistory"
"description"

To more details, click here and explore it in our Playground.

b) Attributes that can be used to add messages to the subscription history:

AttributeDescriptionRequiredType
descriptionAllows you to add information to the subscription history without influencing its flow.
Minimum of 1 character and maximum of 255 characters (String).		YesString

8. Edit subscription plan name

Allows you to change (edit) the name of a pre-existing subscription plan. For this, the plan identifier plan_id must be provided.

To do so, you must send a PUT request to the /v1/plan/:id route, where :id is the plan_id of the plan.

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 = [ 'name' => 'Meu novo plano' ];
try {
$api = new Gerencianet($options);
$subscription = $api->updatePlan($params, $body);
print_r($subscription);
} 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": "/UpdatePlan"
"name"

To more details, click here and explore it in our Playground.


b) Attribute that can be used to edit the name of a pre-existing subscription plan:


AttributeDescriptionRequiredType
nameAllows you to change (edit) the name of a pre-existing subscription plan.
Minimum of 1 character and maximum of 255 characters (String).		YesString