Introduction

This page contains a introduction to the Gerencianet Account Opening API and information on how to configure an environment for its consumption.

Account Opening API

The Account Opening API provides our services to facilitate the opening of accounts on Gerencianet. With our API it is possible to start the process of opening your customer's accounts in a practical way and obtain the necessary credentials and certificates to use the customer's application.

Understanding the application scopes

When creating or editing an application in your Gerencianet Account, you will need to configure the scopes that the application will have access to. Choosing these scopes will define the actions that an application will be authorized to perform via API.

The scopes available in the Gerencianet Account Opening API are listed below with their respective descriptions:

• gn.registration.write - Permission to make a simplified account opening request;
• gn.registration.read - Permission to get account credentials;
• gn.registration.webhook.write - Permission to change the webhook;
• gn.registration.webhook.read - Permission to get the webhook;

Caution

To use the Gerencianet Account Opening API, it is necessary to activate the scopes mentioned on this page, therefore, you must fill in the form available at this link.

After filling it out, just wait for us to contact you.

OAuth2 authentication

The process to authenticate in the Gerencianet Payment API follows the [OAuth2]((http://oauth.net/2/) process, in this process, it is included the security certificate generated in your Gerencianet account. Through this, the OAuth2 authentication can access the authorizations of you application and authorize or deny the requests.

For more details regarding authentication with OAuth2, just click on the button below:

Authorization

The Payments API requires the use of a PFX(.p12) certificate that is generated in your Gerencianet account. The Auth2 provides an authorization mechanism called mutual Transport Layer Security (mTLS) through the certificate created in your Gerencianet account, this method adds another level of security to the requests between your application and the Gerencianet Payment API.

For more details about the PFX(.p12) creation and the mTLS pattern, just click on the button below:

Configuring tests on Postman

To proceed with the Postman configuration step, you must have:

1. A pair of Client_Id and Client_Secret credentials of an application registered in your Gerencianet Account;
2. A P12/PEM certificate generated in your Gerencianet account;
3. The Postman software installed on your computer (If you don't have it, click here to download it);

1. Importing the Account Opening API Collection

This is the link to our Collection that we will keep updated with the Gerencianet Account opening API endpoints.

2. With Postman started, use the shortcut Ctrl+O to open the import screen;
3. Select Collection file;
4. Click Import

2. Creating an Environment

Creating an Environment in Postman is necessary for some automations built into the collection to work. These automations are designed to make it easier for developers during testing.

With them you need to request the authorization only once, and then the access_token is recorded as a Postman environment variable, available for use in subsequent requests.

To create an Environment follow the steps below.

1. Use the Ctrl+N shortcut and select 'Environment';
2. Give a name specifying whether this Environment will be pointed to the production or homologation environment;
3. Create the variable gn-api-contas and in initial value enter the URL of the Production or Homologation Payment API;
4. Save your Environment;
5. Select the desired Environment, so Postman will understand the created variable.

The images below shows the steps above. As an example, an Environment was created for Gerencianet's Account Openning API Production environment.

3. Setting the certificate in Postman

All requests made to the Gerencianet Payment API need the certificate generated in your Gerencianet account. Therefore, to help you testing Postman, follow the steps below to configure the certificate usage during requests automatically:

1. Click the gear icon in the upper right corner of the Postman;
2. Then click "Settings" to open the settings;
3. In the top tab, click "Certificates";
4. Then click on "Add Certificate";
5. In the configuration window of the new certificate, fill the "Host" field with the Base Route of the environment to which the certificate belongs (Production or Homologation);
6. Use the "PFX File" field to tell Postman where your P12/PEM certificate file is located;
7. Finish by clicking "Add" to save your settings.

By following these steps, Postman will use the certificate for any requests made to the Host of the configured environment.

4. Assigning the Client_Id and Client_Secret in Postman

To complete the configuration of your Postman it is necessary to configure the credentials of an application of your Gerencianet account. These credentials are used for Basic Auth and to get the access_token from OAuth.

Follow the steps below to include the credentials and perform your first test in the Pix Gerencianet API.

1. In the imported collection, navigate to the /oauth/token route and double-click to open;
2. Go to the "Authorization" menu and make sure that the "Type" (authorization type) is selected as "Basic Auth";
3. In the "username" and "password" fields fill with your application credentials, Client_Id and Client_Secret respectively;
4. To test, click the "Send" button to submit the request

The image below illustrates the steps above. If everything was followed correctly, you should get a response in JSON format, containing the access_token, token_type, expires_in e scope (like the image bellow).