Playground: Transactions

To acess the sandbox environmet you will need a Gerencianet account. Create your 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 sandbox environment.

Creating a charge (transaction) via integration with the Gerencianet API has two steps:

  1. First generate the transaction (or charge) through the endpoint POST /v1/charge;
  2. Finally, associate the generated transaction with a payment method through the endpoint POST /v1/charge/:id/pay.

After using the POST /v1/charge endpoint, the transaction will already be created and, from this moment on, it will be possible to associate it with the payment method such as boleto or credit card.

Next, check all the endpoints present in our Playground, within the "Transactions":


POST /v1/charge

Allows you to create a new transaction; returns a transaction identifier code named charge_id.

Only after generating the transaction will it be associated with a payment method, which can be boleto or credit card.

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

The following is a simple JSON that can be used to create a charge (still no payment method defined) in the Playground. In this case, this JSON defines that the charge must have a product named Meu Produto, value 8900 (which is equivalent to BRL 89.00) and quantity 1. Also, you can see the predicted output and validation schema with all attributes (mandatory and optional) available for this method:

{
"items": [
{
"name": "Meu Produto",
"value": 8900,
"amount": 1
}
]
}

GET /v1/charge/:id

Allows you to return information from an existing transaction.

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

The following is a simple JSON that can be used to fetch information from some transaction in the Playground. By informing the charge_id input parameter, information about the existing transaction will be returned, as you can see in the expected output available for this method:

Input parameter: inform the "charge_id" of the transaction

PUT /v1/charge/:id/metadata

Allows you to include information such as notification_url and custom_id to an existing transaction.This endpoint is extremely important to update your transaction's notification URL or modify the custom_id previously associated with your transactions.

  • notification_url: is a valid URL address that will receive transaction status change notifications
  • custom_id: 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.

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 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;

  • 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/charge/:id/metadata method that are available for use:

The following is a simple JSON that can be used to change the notification URL and/or custom_id of an existing transaction in the Playground. Also, you can see the predicted output and validation schema with all attributes (mandatory and optional) available for this method. Remembering that you need to inform the charge_id input parameter of the desired transaction:

{
"notification_url": null,
"custom_id": null
}

PUT /v1/charge/:id/billet

Allows you to change the due date of a transaction in which the payment method is a boleto (banking_billet) and which has not yet been paid. The due date format must follow the following pattern: YYYY-MM-DD.

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

The following is a simple JSON that can be used to change the due date of a boleto in the Playground - in this case, the new due date of the boleto will be 2021-12-30 (equivalent to 30/12 /2021). Also, you can see the predicted output and validation schema with all attributes (mandatory and optional) available for this method. Remembering that it is necessary to inform the charge_id input parameter of the desired transaction:

{
"expire_at": "2021-12-30"
}

PUT /v1/charge/:id/cancel

Through this endpoint it is possible to cancel a created transaction.

Only transactions with new, waiting, unpaid or link status can be cancelled. 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 billing status is changed from canceled to paid.

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

The following is a simple JSON that can be used to cancel a transaction created in Playground. Also, you can look at the predicted output available for this method. Remembering that you need to inform the charge_id input parameter of the desired transaction:

Input parameter: inform the "charge_id" of the transaction

POST /v1/charge/:id/pay

Allows you to associate a payment method with an already created transaction.

After generating a transaction through the endpoint POST /v1/charge, it is settled with the status of new (new), that is, a new transaction was generated, however, no payment method has been assigned to her.

To define a payment method for the created transaction, the integrator can choose between banking_billet or credit_card (boleto bancario and credit card, respectively).

  • Boleto Bancário: the transaction goes through a status change cycle, being initially created with the status of new (new) and, when defining the payment method, the status will be waiting (waiting). This means that the boleto has been successfully generated, but has not yet been paid. When choosing boleto bancario, the consumer response will already have the typed line, barcode and link to access the boleto;

  • Credit Card: the main difference for the boleto is related to the need to use a code called “payment_token”. In the Playground, you can generate your token by clicking on the “Gerar payment token” button and pasting it into the payment_token attribute. In the production environment, obtaining the "payment_token" is done by consuming a Javascript code available in your account.

In the following image, you can see the screen of our test environment, which contains the resources linked to the POST /v1/charge/: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 transaction already created in Playground - the integrator can choose between banking_billet or credit_card. Also, you can see the predicted output and validation schema with all attributes (mandatory and optional) available for this method. Remembering that you need to inform the charge_id input parameter of the desired transaction:

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

In the case of the tab "Dados de Entrada (boleto)", is being generated a boleto due on 12/30/2018, we are using a message to inform the customer about something, and if the charge is paid after the due date, a 2% fine and 0.033% interest per day will be charged.

In the case of the tab "Dados de Entrada (cartão)", the payment_token is the payment token required when paying via card. In the Playground, it is obtained just by clicking the "Gerar payment token" button and pasting it inside the payment_token attribute. If it was in a production environment, it would be obtained through the Javascript code available for each Gestornet account - for boleto the "payment_token" is not necessary.

information

When using the message attribute, you must use the \n operator to "break" the line. In the code we provide we have already included this operator.


POST /v1/charge/:id/billet/resend

Allows you to resend the boleto to some email address.

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

Next, a simple JSON that can be used to resend a boleto created in Playground by e-mail - in this case, it will define that the address "email_do_cliente@servidor.com.br" will receive the boleto that was created in a tests. Also, you can see the predicted output and validation schema with all attributes (mandatory and optional) available for this method. Remembering that you need to inform the charge_id input parameter of the desired transaction:

{
"email": "email_do_cliente@servidor.com.br"
}

POST /v1/charge/:id/history

The history of a transaction represents all the actions that have been done with that transaction up to the present time. You can add custom messages to this history using the /v1/charge/:id/history endpoint.

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

The following is a simple JSON that can be used to add a description to a given transaction in the Playground - in this case, it will add the description "Camisa Polo tamanho G cor azul". Also, you can see the predicted output and validation schema with all attributes (mandatory and optional) available for this method. Remembering that you need to inform the charge_id input parameter of the desired transaction:

{
"description": "Camisa Polo tamanho G cor azul"
}

POST /v1/charge/:id/link

Allows you to return a link to a Gerencianet payment page. In other words, the integrator generates a charge and then, instead of defining the payment via boleto or credit card, the integrator can request a link, even choosing whether the payment page should accept boleto, card or both.

In addition, the integrator sets a due date for the payment page, that is, after the date defined by the integrator, the payment screen link will no longer be valid. The integrator can define the discount for boleto or card, and can also inform whether or not he wants to collect the customer's address.

This payment screen is not a payment definition such as a boleto or card, but an intermediary. It is useful when the integrator does not want to implement its own payment page, for example.

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

The following is a simple JSON that can be used to return a link to a Gerencianet payment page. To use it, you must previously create a transaction and, in the id field, provide the charge_id of the transaction that was created earlier. Thus, a link will be returned that will allow the customer to go to a payment screen previously configured by the integrator.

Also, you can see the predicted output and validation schema with all tags (mandatory and optional) available for this method. Remembering that it is also necessary to inform the input parameter charge_id of the desired transaction and created previously:

{
"message": "Escreva aqui, se quiser, uma mensagem ao seu cliente, limite de 80 caracteres",
"expire_at": "2021-12-20",
"request_delivery_address": false,
"payment_method": "all"
}
This JSON will return a link that will give access to a payment screen. Note that this link on the payment screen will be valid until 12/20/2018, we are not asking for our customer's delivery address and the payment method allowed is boleto and card (which could also have used ``banking_billet`` to allow payment via boleto or ``credit_card`` for card only).

There are other possibilities, such as, for example, granting a discount according to the payment method, it would be enough to use the billet_discount attributes - see in the "Schema" tab all the possible attributes to be used.


PUT /v1/charge/:id/link

Allows you to update (change) certain parameters/attributes of a payment link created through POST /v1/charge/:id/link, as long as the payment has not been confirmed. Some information that can be updated: payment method, insert discount and message to the customer, payment link expiration date and change (or not) the buyer's delivery address.

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

The following is a simple JSON that can be used to update (change) certain parameters/attributes of a payment link created through POST /v1/charge/:id/link, as long as the payment has not been confirmed. Also, you can see the predicted output and validation schema with all tags (mandatory and optional) available for this method. Remembering that you also need to inform the charge_id input parameter of the desired transaction:

{
"expire_at": "2021-12-30",
"request_delivery_address": false,
"payment_method": "all"
}

POST /v1/charge/:id/balance-sheet

You can define that the transaction will be of the balance sheet type. This is a model used by condominiums and accounting firms.

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

The following is a simple JSON that can be used to define that a transaction will be of the balance sheet type. To use it, you must previously create a transaction and, in the id field, provide the charge_id of the transaction that was created earlier. Thus, it will be defined that such a transaction will be of the balance sheet type, and the next (and last) step will be to consume the endpoint responsible for defining the payment type boleto (which is [POST /v1/charge/:id/pay](#post- v1chargeidpay)).

Also, you can see the predicted output and validation schema with all tags (mandatory and optional) available for this method. Remembering that it is also necessary to inform the input parameter charge_id of the desired transaction and created previously:

{
"title": "Balancete Demonstrativo",
"body": [
{
"header": "Demonstrativo de Consumo",
"tables": [
{
"rows": [
[
{
"align": "left",
"color": "#000000",
"style": "bold",
"text": "Exemplo de despesa",
"colspan": 2
},
{
"align": "left",
"color": "#000000",
"style": "bold",
"text": "Total lançado",
"colspan": 2
}
],
[
{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Instalação",
"colspan": 2
},
{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "R$ 100,00",
"colspan": 2
}
]
]
}
]
},
{
"header": "Balancete Geral",
"tables": [
{
"rows": [
[
{
"align": "left",
"color": "#000000",
"style": "normal",
"text": "Confira na documentação da Gerencianet todas as configurações possíveis de um boleto balancete.",
"colspan": 4
}
]
]
}
]
}
]
}

This JSON will define that the transaction will be of the balance sheet type. The next (and last) step will be to consume the endpoint responsible for the boleto definition (which is POST /v1/charge/:id/pay) and this boleto will come out in the balance sheet standard. See an example of this type of ticket in this image.


PUT /v1/charge/:id/settle

Allows you to mark as paid (manual paid) a certain transaction.

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

The following is a simple JSON that can be used to mark a transaction created in Playground as paid. Also, you can look at the predicted output available for this method. Remembering that you also need to inform the charge_id input parameter of the desired transaction:

Input parameter: inform the "charge_id" of the transaction