Playground: Subscription

To access the test environment you need a Gerencianet account. Create 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 playground.

A subscription is a set of transactions generated, which can be charged by bank slip or credit card. For more details on subscriptions, check out the specific section.

To create a signature, it is quite simple and requires only three steps:

  1. First, create the subscription plan through the POST /v1/plan endpoint;
  2. Now create subscriptions to link to the plan using the POST /v1/plan/:id/subscription endpoint;
  3. Finally, define the payment method for the subscription through the endpointPOST /v1/subscription/:id/pay.

Now, check out all the endpoints present in our Playground, in the "Subscriptions" modality:


POST /v1/plan

Creates the subscription plan, being defined by the integrator the name of the plan, interval (in months) in which the subscription will be generated and the amount of repetitions that the charge will be generated.

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

seguir, um JSON simples que cria plano de assinatura no Playground. Nele, está sendo definido que a assinatura é chamada "Plano de Internet - Velocidade 10 Mb", a cobrança é "mensal" e serão geradas "12 cobranças" (ou até que o plano seja cancelado).

Also, you can see the predicted output and validation schema with all tags (required and optional) available for this method:

{
"name": "Plano de Internet - Velocidade 10 Mb",
"interval": 1,
"repeats": 12
}

GET /v1/plans

Search for information related to a subscription. 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 record the search will be performed.

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

The following is a simple JSON that can be used to search for information related to a previously created subscription in Playground. This JSON returns information related to a subscription, being able to use any of the three input parameters name, limit and offset to search it - if nothing is informed, it will return all the subscriptions created in Playground.

Also, you can look at the predicted output available for this method. Remembering that it is also necessary to inform the input parameters name, limit and offset of the subscription.

Input parameter: inform the "name", "limit" and "offset" of the subscription

PUT /v1/plan/:id

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

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

The following is a simple JSON that can be used to edit the name of an existing subscription plan. In this case, this JSON will update the existing subscription plan name to "Meu novo nome do plano".

Also, you can see the predicted output and validation schema with all tags (required and optional) available for this method. Remembering that it is necessary to inform the identifier of the subscription plan, which in this case is the plan_id:

{
"name": "Meu novo nome do plano"
}


DELETE /v1/plan/:id

Allows you to cancel a subscription plan. To do so, you must inform the plan_id.

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

The following is a simple JSON that can be used to cancel a subscription plan.

Also, you can look at the predicted output available for this method. It should be noted that it is necessary to inform the plan_id input parameter of the subscription plan:

Input parameter: enter the "plan_id" of the subscription plan

POST /v1/plan/:id/subscription

Creates a subscription when you need to charge your customers recurrently. In this way, subsequent costs will be created automatically based on the plan configuration. To do so, you must inform the plan_id of the previously created plan that you want to associate with a subscription.

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

The following is a simple JSON that allows you to create subscriptions and associate them with plans to recurrently bill. This JSON associates the subscription entitled "Internet - Monthly" with the subscription plan plan (plan_id) informed in the input parameter, value of R$ 69.90 and amount equal to 1 .

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 plan_id of the plan you want to associate with a subscription:

{
"items": [
{
"name": "Internet - Mensalidade",
"value": 6990,
"amount": 1
}
]
}

GET /v1/subscription/:id

Allows you to search for information about a subscription that is linked to a plan.

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

The following is a simple JSON that can be used to fetch information related to subscribing to a subscription linked to a plan created in the Playground. In this case, information about a subscription that is linked to a plan will be returned, according to the subscription_id informed in the input parameter.

Also, you can look at the predicted output available for this method. Remembering that you also need to inform the subscription_id input parameter of the desired subscription:

Input parameter: inform the "subscription_id" of the transaction

PUT /v1/subscription/:id/cancel

Allows you to cancel active subscriptions on a subscription plan. To do so, you must inform the subscription_id of the subscription 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/subscription/:id/cancel method that are available for use:

The following is a simple JSON that allows you to unsubscribe from active subscriptions to a subscription plan created in Playground.

Also, you can look at the predicted output available for this method. Remembering that you also need to inform the subscription_id input parameter of the desired subscription:

Input parameter: inform the "subscription_id" of the transaction

PUT /v1/subscription/:id/metadata

Changes the information sent in the metadata property of a subscription at any time. This endpoint is extremely important for updating your subscription's notification URL or modifying the custom_id previously associated with the subscription.

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

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 custom_id of an existing transaction 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 you also need to inform the subscription_id input parameter of the desired subscription:

{
"items": [
{
"name": "Internet - Mensalidade",
"value": 6990,
"amount": 1
}
]
}

POST /v1/subscription/:id/pay

Defines a recurring payment method for a given subscription. It can be by credit card or banking billet:

  • Card: will charge your card monthly according to the number of repetitions defined by the plan;

  • Boleto: will be generated according to the number of repetitions defined by the plan, and can be sent by email. The subscriber or seller can unsubscribe at any time. When this occurs, the two are notified via email, with all the details of the cancellation.

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

The following is a simple JSON that can be used to associate a payment method with a subscription already created in Playground - the integrator can choose between banking_billet or credit_card (bank slip and credit card, respectively) .

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 subscription_id input parameter of the subscription associated with the payment method:

{
"payment": {
"credit_card": {
"customer": {
"name": "Gorbadoc Oldbuck",
"cpf": "94271564656",
"email": "email_do_cliente@servidor.com.br",
"birth": "1990-08-29",
"phone_number": "5144916523"
},
"payment_token": "",
"billing_address": {
"street": "Avenida Juscelino Kubitschek",
"number": "909",
"neighborhood": "Bauxita",
"zipcode": "35400000",
"city": "Ouro Preto",
"complement": "",
"state": "MG"
}
}
}
}

This JSON associates a particular signature with a payment method, which can be a bank slip or credit card. In the case of payment by card, the "payment_token" is the payment token, which is obtained through Javascript code available for each Gerencianet account - for bank slip the "payment_token" is not necessary.


POST /v1/subscription/:id/history

The history of a subscription represents all actions that have taken place with that subscription so far. You can add custom messages to this history using the /v1/subscription/:id/history endpoint.

Personalized messages do not influence in the subscription itself, only its history. To do so, you must inform the subscription_id of the desired transaction. 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/subscription/:id/history method that are available for use:

The following is a simple JSON that allows you to add custom messages to a subscription's history, as well as the predicted output and validation schema with all tags (required and optional) available for this method. Remembering that you must inform the subscription_id input parameter of the subscription:

{
"description": "Minha mensagem do histórico aqui"
}