Endpoints

Information from all endpoints available in the Open Finance API

On this page you will find all the endpoints available in the Gerencianet Open Finance API and information on how to use them correctly, such as the scopes necessary for the consumption of each route and their return details.

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

Application settings

Configuring application URLs

PUT/open-fincance/config

This endpoint is used to create or modify a configuration in the application related to the Open Finance API.

caution

To register the Webhook url, it is necessary that the communication obeys the mTLS standard, which will be validated at the time of configuration. For more details, visit the link.

Request

Data for configuration.

• URLs settings

// Exemplo configurando uma URL

{

"redirectURL": "https://client.com/redirect/here",

"webhookURL": "https://client.com/send/callback/here"

}

Attribute	Description	Mandatory	Type
redirectURL	Url where the final customer will be directed after the transaction. The redirectURL will be activated when the customer is directed to the store of origin, that is, to the environment that the integrator prepares to receive the customer after completing the actions in the banking environment.	Yes	String
webhookURL	Url where the notification will be sent.	Yes	String

Getting application URLs settings

GET/open-fincance/config

This endpoint is used to return the application settings related to the Open Finance API, it is not necessary to inform any parameters.

Responses

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

• 200(Success)
• 400(Bad Request)
• 500(Error)

{

"redirectURL": "https://client.com/redirect/here",

"webhookURL": "https://client.com/send/callback/here"

}

Participants

Get the participants institutions of Open Finance

GET/open-fincance/participantes/:nome

Endpoint to get one or more active participants of Open Finance.
Requires authorization for the scope: gn.opb.participants.read

Request

Attribute	Description	Mandatory	Type
Nome	PSP name to be searched.	No	String

Note

If the "nome" (name) attribute is not present in the request, all active Open Finance participants willl be returned.

Responses

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

• 200(Success)
• 404(Not Found)
• 401(Unauthorized)
• 403(Forbidden)
• 412(Precondition Failed)
• 500(Error)

List with one or more Open Finance Participants

{

"participantes": [

{

"identificador": "9f4cd202-8f2b-11ec-b909-0242ac120002",

"nome": "MARCA GERENCIANET",

"descricao": "Descrição da marca",

"portal": "https://openbankingbrasil.org.br/quem-participa/",

"logo": "https://www.gerencianet.com.br/logo.png",

"organizacoes": [

{

"nome": "Gerencianet",

"cnpj": "09089356000118,",

"status": "Ativo"

}

]

}

]

}

Payments

Request to start using Pix via Open Finance

POST/open-finance/pagamentos/pix

This endpoint is used to enter payment information to be initiated and the output is a redirect url, which must be inserted into a button so that the user clicks and is redirected to the account institution holding.

Request

Attribute	Description	Mandatory	Type
x-idempotency-key	Unique key to avoid duplicate requests in a short time. If several requests with the same information are sent at the same time, one of them will be successfully processed. If another request is sent with the same key, a 409 error will be returned. (This attribute must be sent in the Header)	Yes	String. minLength:36 maxLength:72

• Payment initiation

Payment initiation example

{

"pagador": {

"idParticipante": "9f4cd202-8f2b-11ec-b909-0242ac120002",

"cpf": "45204392050", // cpf ou cnpj

"cnpj": "90293071000112"

},

"favorecido": {

"contaBanco": {

"codigoBanco": "364",

"agencia": "0001",

"documento": "11122233344",

"nome": "Luiz Silva",

"conta": "654984",

"tipoConta": "CACC"

}

},

"valor": "9.90",

"codigoCidadeIBGE": "3540000",

"infoPagador": "Compra dia xx"

}

Data that can be used in the payment initiation request:

Attribute	Description	Mandatory	Type
Pagador	The fields in the "pagador" identifier organizes informations regarding the data of the final customer to whom the charge will be generated. pagador: idParticipante*// Participant identifier in the Central Bank directory. (String) cpf*// Final customer CPF (document), natural person. (String) cnpj*// Final customer CNPJ (document), juridical person. (String)	Yes	Object.
Favorecido	The fields in the "favorecido" identifier organizes informations regarding the data of the final customer to whom the charge will be generated. favorecido: contaBanco* : (bank account) codigoBanco*// Bank code. (String) agencia*// agency (String) documento*// Account owner document. (String) nome*// Account owner name (String) conta*// Account number with the last digit. (String) Tipoconta*: CACC: Conta Corrente, used to post debits and credits in general. SLRY: Salary account, used for salary payments. SVGS: Conta Poupança, used for savings. TRAN: Conta de Transações, used as basic account type. (Values) //[ CACC, SLRY, SVGS, TRAN ]	Yes	Object.
Valor	Payment value.	Yes	String.
codigoCidadeIBGE	City code (or zipcode) according to IBGE.	Yes	String.
infoPagador	Informations to the final payer. 200(Success)	No	String.

Responses

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

• 200(Success)
• 404(Bad Request)
• 401(Unauthorized)
• 403(Forbidden)
• 409(Conflict)
• 422(Unprocessable)
• 431(Fields Too Large)
• 500(Error)

{

"identificadorPagamento": "ae71713f-875b-4af3-9d85-0bcb43288847",

"redirectURI": "https://open-banking.banco.com.br/authorize?request=eyJjd&redirect_uri=https://pub.opb.testegerencianet.com.br/callback&scope=openid%20pagamentos%20consent:urn:gerencianet:fdf36ac8-f213-4057-bf2e-2ce7bd828abf&response_type=code%20id_token"

}

Obs:The redirect link contained in the redirectURI parameter has an expiration time that may be different for each account holder chosen for the payment. The shortest expiration time is 30 seconds.

List of payments for a period of time

GET/open=finance/pagamentos/pix

This endpoint is used to list information about payments that have been made over a period of time.

This endpoint has mandatory start and end filters that represent the range of dates in which the queried charges must be included.

Requisição
Data that can be used in the information listing request:

Attribute	Description	Mandatory	Type
inicio	Inicial date of the payment. Example: 2022-04-29	Yes	String
fim	Final date of the payment. Example: 2022-04-29	Yes	String
quantidade	Quantity of returns for page. Example: 5	No	String
pagina	number of the page you want to consult according to the quantity. Example: 2	No	String
status	payment status. Example: 2	No	String
identificador	Payment identifier (If this field is informed, the others are disregarded in the search).	No	String

Responses

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

• 200(Success)
• 400(Bad Request)
• 404(Unknown Payment Error)
• 422(Unprocessable)
• 500(Error)

{

"pagamentos": [

{

"identificadorPagamento": "urn:gerencianet:49315a93-d39c-4564-9edb-9a73678dbdb1",

"valor": "1.99",

"status": "pendente",

"dataCriacao": "2022-04-29T11:55:03.000Z"

}

],

"total": 3,

"porPagina": 1,

"ultimo": "/pagamentos/pix?inicio=2022-04-29&fim=2022-04-29&quantidade=1&pagina=3",

"proximo": "/pagamentos/pix?inicio=2022-04-29&fim=2022-04-29&quantidade=1&pagina=2",

"anterior": null,

"atual": "/pagamentos/pix?inicio=2022-04-29&fim=2022-04-29&quantidade=1&pagina=1"

}

Receiving callbacks

This service is protected by an mTLS authentication layer.

Request

A POST request is sent by Gerencianet to the URL you registered as a webhook for a given key. When there is a change in the status of an Open Finance transaction, involving the associated key, a JSON object (like the examples below) will be sent to your server. Each request sent has a timeout of 60 seconds, that is, a callback request is interrupted when it reaches 60 seconds without a response.

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

• Example - Callbacks data

// Exemplo - 200 (Notificação enviada com sucesso)

{

"identificadorPagamento": "urn:instituicaoDetentoraDeConta:fd2be7c4-604c-4493-9236-78fe66f40597",

"valor": "9.90",

"status": "aceito",

"dataCriacao": "2024-09-20T18:37:23.000Z",

"endToEndId": "E090993562022060954525a47762681g"

}

The following table details the fields present in the JSON object that will be sent in the notification.

Attribute	Description	Mandatory	Type
identificadorPagamento	Identifier of the payment initiated in the Open Finance API. Example: ae71713f-875b-4af3-9d85-0bcb43288847	Yes	String
status	Status of payment initiated. Example: pendente, agendado, rejeitado e aceito.	Yes	String
Valor	Transaction amount received. Example: 9,90	Yes	String \d10.\d2
dataCriacao	Transaction creation date.	Yes	String (datetime)
endToEndId	EndToEndIdentification que transita na PACS002, PACS004 e PACS008	No	String (32 characters)^[a-zA-Z0-9]32$

Response

Callback requests wait for a response with HTTP status 2XX. If the client's server returns a different status, Gerencianet will make up to 10 notification retries. The first retry will be made 5 minutes after the callback fails to send. If the error persists, subsequent attempts will be sent at increasing time intervals, as shown in the table below.

important

In cases where the client's server returns HTTP status 429 (too many requests), Gerencianet's servers will try to send the notification up to 10 times also according to the table below.

Trial number	Time (in minutes)
1	5
2	10
3	20
4	40
5	80
6	160
7	320
8	640
9	1280
10	2560