Endpoints

Information about all endpoints available in the Gerencianet Account Opening API.

On this page you will find all available endpoints of the Gerencianet Payment API. We recommend that you join our community in Discord to keep up with api developments, including the release of new endpoints.

Use the summary below to quickly navigate between api endpoint groups.

Video Tutorial Gerencianet Openning Account API

Base routes

Base route or base URL's for environments, use the route below to communicate your application with the production environment offered by Gerencianet.

Production

 "URL": {
    "Production": "https://apis.gerencianet.com.br/"
  }

Get authorization

POST/oauth/token

This endpoint is used to authorize an application's credentials and get the scopes that the application has to access the other API endpoints. The P12/PEM certificate must be present in the authorization request for the handshake with the API server to be allowed.

Examples of authorization using the certificate. P12

To use the Gerencianet Payment API, the client and server must communicate on a verified connection to each other. Verification is done by the two-way certificate (.PEM or .P12), that is, the server and client have implemented a private key certificate and a public key certificate that allows one to ensure the identity of the other.

Therefore to make any HTTP request to the Openning account API, including the authorization request with OAuth2, it is necessary the certificate .P12, or .pem, in the request headers.

Below are examples of how to consume the Authorization of the Gerencianet Openning account API by incorporating this certificate into the request.

<?php //Desenvolvido pela Consultoria Técnica da Gerencianet

$config = [
  "certificado" => "./certificado.pem",
  "client_id" => "YOUR-CLIENT-ID",
  "client_secret" => "YOUR-CLIENT-SECRET"
];
$autorizacao =  base64_encode($config["client_id"] . ":" . $config["client_secret"]);

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => "https://apis.gerencianet.com.br/oauth/token", // Rota base, homologação ou produção
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => '{"grant_type": "client_credentials"}',
    CURLOPT_SSLCERT => $config["certificado"], // Caminho do certificado
    CURLOPT_SSLCERTPASSWD => "",
    CURLOPT_HTTPHEADER => array(
        "Authorization: Basic $autorizacao",
        "Content-Type: application/json"
    ),
));

$response = curl_exec($curl);

curl_close($curl);

echo "<pre>";
echo $response;
echo "</pre>";

Authorization example of response
The code snippet below represents an example of OAuth's response to your authorization request.

Response

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "gn.barcode.read gn.barcode.pay.write gn.barcode.pay.read"
}

Simplified Registration

Request to open a simplified account

POST/cadastro/conta-simplificada

Requests simplified account opening for integration. The input data refers to the final customer. If the input data is valid, the customer will receive a link in which they can authorize integration with a Gerencianet account.

Requires authorization for the scope: gn.registration.write

Creating account/ application

If your end customer already has a Gerenciant account, two options will appear for him:

Create an application in the current account, where you will have access to the credentials and define the scopes.
Create a secondary account for the end customer with the settings/access defined in the request.

Refusing the account oppening

If your customer refuses the account opening process, you will have to wait 2 business days before starting a new process. Note: The information is not returned if the customer denies the opening process.

Request

Natural Person data
Juridical Person data

{
  "clienteFinal": {
    "cpf": "12345678900",
    "nomeCompleto": "Nome Exemplo",
    "dataNascimento": "13/08/2000",
    "nomeMae": "Exemplo de nome da mãe",
    "celular": "31987654321",
    "email": "emaildeexemplo@gerencianet.com.br",
    "endereco": {
      "cep": "35400000",
      "estado": "MG",
      "cidade": "Ouro Preto",
      "bairro": "Bairro exemplo",
      "logradouro": "Exemplo do nome da rua",
      "numero": "777",
      "complemento": "apto 101"
    }
  },
  "meioDeNotificacao": [
    "sms",
    "whatsapp"
  ],
  "escoposIntegrados": [
    "charge.write",
    "pix.send"
  ]
}

Data that can be used in the simplified account opening request.
(*) Mandatory attributes

Attribute	Description	Mandatory	Type
`clienteFinal`	The fields in the final customer identification organize informations about the final customer data for which the account will be generated. clienteFinal: `cpf`// Natural Person's CPF. (String) `nomeCompleto`// Final customer's full name, natural person. (String) `dataNascimento`// Final customer born date. (String in the format: `DD/MM/YYYY`) `nomeMae`// Final customer mother's name, natural person. (String) `celular`// Final customer's phone number. (String) `email`// Final customer's email. (String) `cnpj`// Juridical Person's CNPJ (String) `razaoSocial`// Final customer's social name, juridical person. (String) `endereco`// Final customer's address. (Object) `cep`// Final customer's zipcode (CEP), natural person. (String) `estado`// Final customer's state, natural person (String) Values: `AC, AL, AP, AM, BA, CE, DF, ES, GO, MA, MT, MS, MG, PA, PB, PR, PE, PI, RJ, RN, RS, RO, RR, SC, SP, SE, TO` `cidade`// Final customer's city name, natural person. (String) `bairro`// Final customer's neighbourhood name. (Object) `logradouro`// Final customer's street name, natural person. (String) `numero`// Final customer's address number. (Object) `complemento`// Final customer's adress complement, natural person. (String)	Yes	String
`meioDeNotificacao`	Determines where and which way will the final customer receive the notification to approve the process. Values: `sms`, `whatsapp`	Yes	String
`escoposIntegrados`	Scopes of services that the integrator wants to access in the final customer's account. It is not possible to request unconfigured service scopes for the requesting integrator's application. Values: `charge.write, cob.write, payloadlocation.write, payloadlocation.read,` `cob.read, pix.write, pix.read, pix.send, webhook.write, webhook.read,` `gn.balance.read, gn.pix.evp.write, gn.pix.evp.read, gn.settings.write,` `gn.settings.read, gn.barcode.read, gn.barcode.pay.write,gn.barcode.pay.read`	Yes	String

Responses
The answers below represent Success(200) and Failures/Errors of consumption.

{
  "contaSimplificada": {
    "identificador": "92ccd29b-54c9-49fc-b8e8-717a3b373c5e"
  }
}

Get credentials from simplified account

GET/cadastro/conta-simplificada/:identificador/credenciais

Endpoint to get the Client_id and Client_Secret to integrate with a simplified account.
Requires authorization for the scope: gn.registration.read

Request

Attribute	Description	Mandatory	Type
identificador	Generated simplified account's identifier	Yes	String

Responses

The responses below represent Success(200) and Consumption failures/errors.

200(Success)
401(Unauthorized)
403(Forbidden)
412(Precondition Failed)
500(Error)

{
  "clientId": "92ccd29b-54c9-49fc-b8e8-717a3b373c5e",
  "clientSecret": "b2e9dcca-c46d-4b9b-89d2-c625949bea40",
  "conta": {
    "numero": "10000"
  },
  "escopos": [
    "pix.send",
    "cob.write",
    "webhook.read"
  ],
  "ativo": true
}

Get certificate from simplified account

GET/cadastro/conta-simplificada/:identificador/certificado

Endpoint to get the certificate to integrate with a simplified account.
Requires authorization for the scope: gn.registration.read

Request

Attribute	Description	Mandatory	Type
identificadorWebhook	Generated simplified account's identifier.	Yes	String

Responses

The responses below represent Success(200) and Consumption failures/errors.

200(Success)
401(Unauthorized)
403(Forbidden)
412(Precondition Failed)
500(Error)

{
  "clientId": "92ccd29b-54c9-49fc-b8e8-717a3b373c5e",
  "clientSecret": "b2e9dcca-c46d-4b9b-89d2-c625949bea40",
  "conta": {
    "numero": "10000"
  },
  "escopos": [
    "pix.send",
    "cob.write",
    "webhook.read"
  ],
  "ativo": true
}

Webhook

It brings together endpoints for managing notifications to the integrator.

Understanding the mTLS pattern

As a rule by the Central Bank, it will be necessary to insert a Gerencianet public key on its server so that the communication complies with the mTLS pattern. In your domain that represents your server, a configuration must be made to require the public key (mTLS) that we are providing for mutual authentication to occur.

Gerencianet will make 2 requests for your domain (server):

First Request: Let's make sure your server is demanding a public key from Gerencianet. This will be done when sending a request without a certificate and your server should not accept the request. Once answered with the refusal, the 2nd request will be sent.
Second Request: We will send the notification together with our public key, your server, which must contain the public key available, must perform the "Hand-Shake" and thus the communication will be established.

Your server must have the minimum version of TLS 1.2. You can check about your TLS here

On your server you must configure a 'POST' route with a default response as a string "200". Our production certificate or homologation must be inserted in your server, below we have some examples.

Dedicated Servers

It is recommended that you have a dedicated server to be able to configure the webhook, since it is necessary to have access to some files to perform the configurations as in the examples below.

Shared hosting

For hosting on shared servers, there may be restrictions regarding the insertion of certificates generated by another entity, such as our CA for example. If you have problems, we advise you to opening a ticket with the subject: mTLS on shared hosting or contact us through our channel #api-pix no Discord. We will analyze the situation so that we can act together to help you.

Examples of server settings

To configure your server, you will need the Gerencianet public keys. Below are the key addresses for the Production and Homologation environments. These keys must be downloaded and placed on your server.

Attribute	Description
Production	`https://pix.gerencianet.com.br/webhooks/chain-pix-prod.crt`
Homologation	`https://pix.gerencianet.com.br/webhooks/chain-pix-sandbox.crt`

The code snippets below seek to exemplify the necessary settings on your server so that it is possible to perform the hand-shake with our servers.

Python
Nginx
Node
Apache
PHP

from flask import Flask, jsonify
import ssl
import json
app = Flask(__name__)


@app.route("/")
def hello():
    return "<h1 style='color:blue'>Hello There!</h1>"


@app.route("/", methods=["PUT"])
def hello_put():
    response = {"status": 200}
    return jsonify(response)


@app.route("/", methods=["POST"])
def imprimir():
    imprime = print(request.json)
    data = request.json
    with open('data.txt', 'a') as outfile:
        outfile.write("\n")
        json.dump(data, outfile)
    return jsonify(imprime)

def hello_post():
    response = {"status": 200}
    return jsonify(response)

if __name__ == "__main__":
    context = ssl.SSLContext(ssl.PROTOCOL_TLSv1_2)
    context.verify_mode = ssl.CERT_REQUIRED
    context.load_verify_locations('path-certificate/Gerencianet-public-cert.crt')
    context.load_cert_chain(
        'path-certificate/server_ssl.crt.pem',
        'path-certificate/server_ssl.key.pem')
    app.run(ssl_context=context, host='0.0.0.0')
#Desenvolvido pela Consultoria Técnica da Gerencianet

To have a valid SSL, you must contact a Certificate Authority and generate a private key server_ssl.key.pem and a public key server_ssl.crt.pem, so you can validate the integrity of the connection. You can do this for free using a utility like Certbot for example.

Setting the Webhook

POST/cadastro/webhook

Configures webhook for the Account Opening API.
Requires authorization for scope: gn.registration.webhook.write

Request
Data for webhook configuration.

Add Webhook
Update Webhook

{
  "webhookUrl": "https://gerencianet.com.br/meu-webhook"
}

(*) Mandatory attribute

Attribute	Description	Mandatory	Type
webhookURL	URL where the notification will be sent.	Yes	String. Example: `https://gerencianet.com.br/meu-webhook`
identificadorWebhook	Webhook identifier key.	No	String. Example: 92ecc0a8-9631-4601-a188-feacf8288c13

Responses
The responses below represent Success(200) and Failures/Errors of consumption.

200(Success)
400(Bad request)
401(Unauthorized)
500(Error)

{
  "identificadorWebhook": "92ecc0a8-9631-4601-a188-feacf8288c13"
}

Detail Webhook

GET/cadastro/webhook/:identificadorWebhook

Get details about the configured webhook for the Account Openning API.

Requires authorization for the scope: gn.registration.webhook.read

Request
The request sent to this endpoint doesn't need a body, just the authorization header, OAuth, parameters and the account certificate.

Attribute	Description	Mandatory	Type
identificadorWebhook	Pix key evp linked to the webhook	Yes	String. Example: 92ecc0a8-9631-4601-a188-feacf8288c13

Responses
The responses below represent Success(200) and Failures/Errors of consumption.

200(Success)
400(Bad request)
401(Unauthorized)
500(Error)

{
  "webhookUrl": "https://gerencianet.com.br/meu-webhook",
  "identificadorWebhook": "92ecc0a8-9631-4601-a188-feacf8288c13",
  "criacao": "2021-10-26T11:23:35.000Z"
}

Cancel Webhook

DELETE/cadastro/webhook/:identificadorWebhook

Cancel/delete the configured webhook for the Account Openning API.

Requires authorization for the scope: gn.registration.webhook.write

Request
The request sent to this endpoint doesn't need a body, just the authorization header, OAuth, parameters and the account certificate.

Attribute	Description	Mandatory	Type
identificadorWebhook	Pix key evp linked to the webhook.	Yes	String. Example: 92ecc0a8-9631-4601-a188-feacf8288c13

Responses
The responses below represent Success(200) and Failures/Errors of consumption.

200(Success)
400(Bad request)
401(Unauthorized)
500(Error)

No content 
* Webhook was cancelled.

Get list of Webhooks

GET/cadastro/webhooks

Get the list of configured webhooks for the Account Openning API.

Requires authorization for the scope: gn.registration.webhook.read

Request
The request sent to this endpoint doesn't need a body, just the authorization header, OAuth, parameters and the account certificate.

Attribute	Description	Mandatory	Type
inicio	Start date to the list.	Yes	string($datetime) Example :2020-04-01T00:00:00.000Z
fim	Final date to the list.	Yes	string($datetime) Example :2022-10-29T00:00:00.000Z
paginacao.paginaAtual	Current page listed.	No	Integer. Example : 0
paginacao.itensPorPagina	Quantity listed per page.	No	Integer. Example : 10

Responses
The responses below represent Success(200) and Failures/Errors of consumption.

200(Success)
400(Bad request)
401(Unauthorized)
500(Error)

Success
{
  "parametros": {
    "inicio": "2020-04-01T00:00:00.000Z",
    "fim": "2020-04-01T23:59:59.000Z",
    "paginacao": {
      "paginaAtual": 0,
      "itensPorPagina": 100,
      "quantidadeDePaginas": 1,
      "quantidadeTotalDeItens": 1
    }
  },
  "webhooks": [
    {
      "webhookUrl": "https://gerencianet.com.br/meu-webhook",
      "identificadorWebhook": "92ecc0a8-9631-4601-a188-feacf8288c13",
      "criacao": "2021-10-26T11:23:35.000Z"
    }
  ]
}

Endpoints

Video Tutorial Gerencianet Openning Account API

Base routes

Get authorization

Examples of authorization using the certificate. P12

Simplified Registration

Request to open a simplified account

Creating account/ application

Refusing the account oppening

Get credentials from simplified account

Get certificate from simplified account

Webhook

Understanding the mTLS pattern

Dedicated Servers

Shared hosting

Examples of server settings

Setting the Webhook

Detail Webhook

Cancel Webhook

Get list of Webhooks

NEED HELP?

FIND OUT MORE

UTILITIES

Acompanhe-nos

Endpoints

Video Tutorial Gerencianet Openning Account API#

Base routes#

Get authorization#

Examples of authorization using the certificate. P12#

Simplified Registration#

Request to open a simplified account#

Creating account/ application

Refusing the account oppening

Get credentials from simplified account#

Get certificate from simplified account#

Webhook#

Understanding the mTLS pattern#

Dedicated Servers

Shared hosting

Examples of server settings#

Setting the Webhook#

Detail Webhook#

Cancel Webhook#

Get list of Webhooks#

Video Tutorial Gerencianet Openning Account API

Base routes

Get authorization

Examples of authorization using the certificate. P12

Simplified Registration

Request to open a simplified account

Get credentials from simplified account

Get certificate from simplified account

Webhook

Understanding the mTLS pattern

Examples of server settings

Setting the Webhook

Detail Webhook

Cancel Webhook

Get list of Webhooks