Endpoints
On this page you will find all the endpoints available in the Gerencianet's Pix API. We recommend that you join our community on Discord to track api developments, including the release of new endpoints.
Use the table of contents on the right to quickly navigate between API endpoint groups.
Charges
The following set of endpoints is responsible for the billing management. Charges in the context of the Pix API represent a financial transaction between a payer and a receiver whose payment method is Pix.
Creating instant charges (without txid)
Endpoint to create an instant charge without the field txid.
In general, the txid is created by the receiving user and is under his responsibility.This endpoint is an exception to this rule, and in this case, the txid will be set by Gerencianet.
Requires authorization for the scope: cob.write
Request
- Example 1
- Example 2
Data for billing generation.
(*) Required attribute
| Attribute | Description | Required | Type |
|---|---|---|---|
| calendario | Fields located in the calendar identifier organizes the information about billing time control. calendario: criacao*// Timestamp that indicates the time the charge was created. Respects the format set in RFC 3339. Minimum of 1 character and maximum of 255 characters (String). apresentacao*// Timestamp hat indicates the time when the JSON payload wich represents the charge was recvered. That means it is the time when the user took the QR Code capture to check the payment data. Respects the format defined in RFC 3339. string date-time (QR Code presentation timestamp) expiracao// Charge's time life, specified in seconds counted from the charge's creation day (Calendario.criacao). integer <int32> | Yes | object (Calendar) |
| devedor | The fields located in the debtor object are optional and identify the debtor, that is, the person or institution to whom the charge is addressed. It does not necessarily identify who will actually make the payment. A CPF may be the debtor of a charge, but it can happen that another CPF actually performs the payment of the document. The pagador.cpf and pagador.cnpj field are not allowed to be filled in the same time. If the pagador.cnpj field is filled in, then the pagador.cpf field cannot be filled in, and vice versa. If the pagador.nome is filled in, then there must exist either a pagador.cpf or a pagador.cnpj field filled in too. devedor: cpf*// payer CPF.string /^\d{11}$/ nome*// Payer name. string (Name) ≤ 200 characters | No | Natural person (object) or Legal entity (object) |
| valor | All fields that indicate monetary values comply with the ID 54 format of the EMV/BR Code specification for QR Codes. The decimal separator is the point character. It is not applicable to use thousand separator. Examples of values adhering to the standard: “0.00”, “1.00”, “123.99”, “123456789.23” valor: original*// Original billing amount.string \d{1,10}\.\d{2} | Yes | object |
| chave | The chave field, required, determines the Pix key registered in DICT wich will be used for the charge. This key will be read by the payer's PSP application for DICT searches, which will return the information that will identify the receiver of the charge. | Yes | string (receiver's DICT key) ≤ 77 characters |
| solicitacaoPagador | The field solicitacaoPagador, optional, determines a text to be presented to the payer so that he can enter a related information, in free format, to be sent to the recipient. This text will be filled in, in pacs.008, by the payer's PSP, in the RemittanceInformation field. The size of the field in pacs.008 is limited to 140 characters. | No | string (Payer request)≤ 140 characters |
| infoAdicionais | Each additional information contained in the list (nome and valor) must be presented to the payer. infoAdicionais: nome*// Field's name string (Name) ≤ 50 charactersvalor*// Field's data string (Amount) ≤ 200 characters | No | Array of objects (Additional information) ≤ 50 |
Response
- 201
- 400
- 409
- 500
Creating instant charges (with txid)
Endpoint to create an instant charge with a transaction identifier (txid).
Requires authorization for the scope: cob.write
Request
- Example 1
- Example 2
| Attribute | Description | Required | Type |
|---|---|---|---|
| txid | Transaction identifier The txid field, required, determines the identifier of the transaction. The purpose of this field is to be an element that allows the PSP of the recipient to present to the receiving user the functionality of payments reconciliation, more details click here. | Yes | string (Transaction Id) [A-Z0-9-]{26,35} |
Data used for creating charges.
(*) Required attribute
| Attribute | Description | Required | Type |
|---|---|---|---|
| calendario | Fields nested under the calendar identifier organize information about billing time control. calendario: criacao*// Timestamp that indicates when the charge was created. Respects the format defined in RFC 3339. Minimum of 1 character and maximum of 255 characters (String). apresentacao*// Timestamp that indicates the time when the JSON payload wich presents the charge was recovered. That is the time when the user took the QR Code capture to check the payment data. Respects the format defined in RFC 3339. string date-time (QR Code presentation timestamp) expiracao// Billing lifetime, specified in seconds from the creation date (Calendario.criacao). integer <int32> | Yes | object (Calendario) |
| devedor | Fields nested in the debtor object are optional and identify the debtor, that is, the person or institution to whom the billing is addressed. It does not necessarily identify who will actually make the payment. A CPF may be the debtor of a charge, but it can happen that another CPF actually performs the payment of the document. The pagador.cpf and pagador.cnpj field are not allowed to be filled in at the same time. If the pagador.cnpj field is filled in, then the pagador.cpf field cannot be filled in, and vice versa. If the pagador.name is filled in, then there must exist either a pagador.cpf or a pagador.cnpj field filled in too. devedor: cpf*// Payer document.string /^\d{11}$/ nome*// Payer name. string (Name) ≤ 200 characters | No | Natural Person (object) or Legal entity (object) |
| valor | All fields that indicate monetary values comply with the ID 54 format of the EMV/BR Code specification for QR Codes. The decimal separator is the point character. It is not applicable to use thousand separator. Examples of values adhering to the standard: “0.00”, “1.00”, “123.99”, “123456789.23” valor: original*// Original billing amount.string \d{1,10}\.\d{2} | Yes | object |
| chave | The chave field, required, determines the Pix key registered in DICT wich will be used for the charge. This key will be read by the payer's PSP application for DICT searches, which will return the information that will identify the receiver of the charge. | Yes | string (receiver's DICT key) ≤ 77 characters |
| solicitacaoPagador | The field solicitacaoPagador, optional, determines a text to be presented to the payer so that he can enter a related information, in free format, to be sent to the recipient. This text will be filled in, in pacs.008, by the payer's PSP, in the RemittanceInformation field. The size of the field in pacs.008 is limited to 140 characters. | No | string (Payer request)≤ 140 characters |
| infoAdicionais | Each additional information contained in the list (name and value) must be presented to the payer. infoAdicionais: nome*// Field's name string (Name) ≤ 50 charactersvalor*// Field's data string (Amount) ≤ 200 characters | No | Array of objects (Additional information) ≤ 50 |
Responses
- 201
- 400
- 409
- 500
Review charge
Endpoint to review (modify) a charge using the txid.
Requires authorization for the scope: cob.write
Request
- Example 1
- Example 2
- Example 3
| Attribute | Description | Required | Type |
|---|---|---|---|
| txid | Transaction identifier The txid field determines the identifier of the transaction. For more details click here. | yes | string (Transaction id)[A-Z0-9-]{26,35} |
Charge review data
(*) Required attribute
| Attribute | Description | Required | Type |
|---|---|---|---|
| calendario | Fields in the calendar identifier organize information about billing time control. calendario: criacao*// Timestamp that indicates when the charge was created. Respects the format defined in RFC 3339. Minimum of 1 character and maximum of 255 characters (String). apresentacao*// Timestamp that indicates the time when the JSON payload representing the charge was recovered. That is the time when the user took the QR Code capture to check the payment data. Respects the format defined in RFC 3339. string date-time (QR Code presentation timestamp) expiracao// Billing lifetime, specified in seconds from the creation date (Calendario.criacao). integer <int32> | No | object (Calendário) |
| status | Enum: "ATIVA","CONCLUIDA""REMOVIDA_PELO_USUARIO_RECEBEDOR","REMOVIDA_PELO_PSP" | No | string (Charge Status) |
| devedor | Fields under the devedor object are optional and identify the debtor, that is, the person or institution to whom the collection is addressed. It does not necessarily identify who will actually make the payment. A CPF may be the debtor of a charge, but it can happen that another CPF actually performs the payment of the document. The pagador.cpf and pagador.cnpj field are not allowed to be filled in at the same time. If the pagador.cnpj field is filled in, then the pagador.cpf field cannot be filled in, and vice versa. If the field pagador.name is filled in, then there must exist either a pagador.cpf or a pagador.cnpj field filled in. devedor: cpf*// Payer user CPF.string /^\d{11}$/ nome*// Name of the paying user. string (Name) ≤ 200 characters | No | Natural person (object) or Legal entity (object) |
| valor | All fields that indicate monetary values comply with the ID 54 format of the EMV/BR Code specification for QR Codes. The decimal separator is the dot character. It is not applicable to use as thousand separator. Examples of values adhering to the pattern: “0.00”, “1.00”, “123.99”, “123456789.23” valor: original*// Original billing amount.string {26,35}\d{1,10}\.\d{2} | No | object |
| loc | Identifier of the location's payload. loc: id*// Location ID to associate with billing. int32 | No | object |
| chave | The chave field, required, determines the Pix key registered in DICT that will be used for billing. This key will be read by the payer's PSP application for DICT consultation, which will return the information that will identify the recipient of the charge. | No | string (recipient's DICT key) ≤ 77 characters |
| solicitacaoPagador | The optional solicitacaoPagador field determines a text to be presented to the payer so that it can enter a related information, in free format, to be sent to the recipient. This text will be filled in, in pacs.008, by the payer's PSP, in the RemittanceInformation field. The size of the field in pacs.008 is limited to 140 characters. | No | string (Payer's request)≤ 140 characters |
| infoAdicionais | Each additional information in the list (nome and valor) must be presented to the payer. infoAdicionais: nome*// Field's name string (Name) ≤ 50 charactersvalor*// Field's data string (Amount) ≤ 200 characters | No | Array of objects (Additional information) ≤ 50 |
Responses
- 200
- 400
- 409
- 500
Get charge
Endpoint to get charge's information using the txid.
You can also see information for a specific review of a charge. To do this, it is necessary to inform the query param revisao. Exemplo: /v2/cob/:txid/?revisao=1. When the parameter is not reported, the most recent review is returned as the default.
Requires authorization for the scope: cob.read
Request
| Attribute | Description | Required | Type |
|---|---|---|---|
| txid | Transaction identifier The txid field determines the identifier of the transaction. For more details click here. | Yes | string (Transaction Id)[A-Z0-9-]{26,35} |
| revisao | Allows the recovering previous reviews from a charge. In the absence of this parameter, the charge will always be returned as it is in your last review. | No | Integer <int32> (Review) |
Respostas
The answers below presents Success(200) and Consumption failures/errors.
- Exemplo 1
- Exemplo 2
- 400
Get list of charges
Endpoint to get a list of charges.
This endpoint has filters to ensure better search results, such as CPF/CNPJ and status. In all available filters, the inicio and fim filters are required and represent the range of dates in which the charges consulted must be inserted.
Requires authorization for the scope: cob.read
Request
The code below illustrates the consumption of the endpoint in a request with as few parameters as possible (the range of 'start' and 'end' dates) and the format in which these parameters should be passed on.
(*) Required attribute
| Attribute | Description | Required | Type |
|---|---|---|---|
| inicio | Filters records whose creation date is greater than or equal to the start date. Respects RFC 3339 | Yes | string <date-time> |
| fim | Filters records whose creation date is less than or equal to the end date. Respects RFC 3339 | Yes | string <date-time> |
| cpf | Filter for payer's CPF. It cannot be used at the same time as the CNPJ. | No | string /^\d{11}$/ |
| cnpj | Filter for payer's CNPJ. It cannot be used at the same time as the CPF. | No | string /^\d{14}$/ |
| status | Enum: "ATIVA","CONCLUIDA""REMOVIDA_PELO_USUARIO_RECEBEDOR""REMOVIDA_PELO_PSP"Filter by billing status. | No | string |
| paginacao.paginaAtual | Default: 0Page to be returned by query. If not reported, the PSP assumes it will be 0. | No | integer <int32> (Current page) ≥ 0 |
| paginacao.itensPorPagina | Default: 100Maximum number of records returned on each page. Only the last page can contain a smaller number of records. | No | integer <int32>(Items per Page)[1 .. 1000] |
Responses
- Exemplo 1 (200)
- Exemplo 2 (200)
Pix
The following endpoints bring the features available for managing Pix transactions, this is maintaining receipts and sending amounts through the Pix payment arrangement.
Get Pix.
Endpoint to consult a Pix through an End to End ID (e2eid).
Requires authorization for the scope: pix.read
caution
This endpoint returns only informations about Received Pix.
Request
| Attribute | Description | Required | Type |
|---|---|---|---|
| e2eid | EndToEndIdentification that transits on PACS002, PACS004 e PACS008 | Yes | string 32 characters[A-Z0-9-]{32} |
Respostas
The answers below presents Success(200) and Consumption failures/errors.
- 200
- 403
- 404
- 503
Get list of received Pix.
Endpoint to get a list of received Pix.
Requires authorization for the scope: pix.read
Request
This endpoint has filters to narrow down the results. All filters are of the query params type, so they must be sent by the URL, as exemplified in the code below.
The filters inicio and fim defines a range of dates in which the Pix must be included to be returned. These are required filters.
| Attribute | Description | Required | Type |
|---|---|---|---|
| inicio | Filters the records whose creation date is greater than or equal to the start date. Respects RFC 3339. | Yes | string <date-time> |
| fim | Filters the records whose creation date is less than or equal to the end date. Respects RFC 3339. | Yes | string <date-time> |
| txid | Transaction ID The txid field determines the identifier of the transaction. The purpose of this field is to be an element that allows the recipient's PSP to present to the receiving user the functionality of reconciliation of payments. In pacs.008, it is referenced as TransactionIdentification <txid> or idConciliacaoRecebedor.In terms of operating flow, the txid is read by the payer's PSP application and, after the payment is confirmed, it is sent to the SPI via pacs.008. A pacs.008 is also sent to the recipient's PSP, containing, in addition to all the user payment information, the txid. Upon noticing a receipt with the txid, the PSP of the recipient is able to communicate with the receiving user, informing that a specific payment has been settled. Txid is created exclusively by the receiving user and is under their responsibility. The txid, in the context of presenting a charge, is unique per CPF/CNPJ of the receiving user. It is up to the receiving PSP to validate this rule in the Pix API. | No | string [A-Z0-9-]{26,35} |
| txidPresente | Boolean. | No | |
| devolucaoPresente | Boolean. | No | |
| cpf | Filter for the payer's CPF. It can't be used in the same time as the filter CNPJ. | No | string /^\d{11}$/ |
| cnpj | Filter for the payer's CNPJ. It can't be used in the same time as the filter CPF. | No | string /^\d{14}$/ |
| paginacao.paginaAtual | Default: 0Page to be returned by query. If not reported, the PSP assumes it will be 0. | No | integer <int32> (Current page) ≥ 0 |
| paginacao.itensPorPagina | Default: 100Maximum number of records returned on each page. Only the last page can contain a smaller number of records. | No | integer <int32>(Items per Page)[1 .. 1000] |
Responses
- 200
- 400
- 500
Request for Pix sending
Endpoint to directly send a Pix to a Pix Key registered on a PSP or bank account data, either from Gerencianet or another bank.
caution
To enable the pix/send endpoint you need to fill in this form. After filling out, just wait for us to contact you.
We release a 15-day trial that can be requested by both individuals and legal entities. The procedure is the same, fill out the indicated form.
note
In order to use the Require Pix Sending endpoint, in addition to releasing the pix.send scope, the payer's Pix key must have a webhook associated with it, as it will be through the webhook that Gerencianet will inform you if the sending of pix was performed successfully or not.
For better performance of the use of the service, and aiming to avoid the collision of balance movements, we suggest that the sending of Pix by API is conditioned to the conclusion of the previous transaction, which takes place through the webhook. If the aforementioned practice is not adopted, when multiple submission requests are made simultaneously, the integrator may experience submission failures.
The endpoint may change when it enters in the BACEN patterning scope. Enabled customers will be notified in advance.
Requires authorization for the scope: pix.send
Request
- Exemplo 1
- Exemplo 2
- Exemplo 3 (validating the key holder)
(*) Required attribute
| Attribute | Description | Required | Type |
|---|---|---|---|
| idEnvio | transaction identifier: The idEnvio field determines the transaction identifier.. | Yes | string ^[a-zA-Z0-9]{1,35} |
(*) Required attribute for body
| Attribute | Description | Required | Type |
|---|---|---|---|
| valor | Monetary amounts related to the charge. | Yes | string \d{1,10}.\d{2} |
| pagador | The required payer field contains the Pix key associated with the authenticated account that will be debited the amount you set. pagador: chave* // The chave field, required, determines the Pix key registered in DICT that will be used to identify the Pix payer (Payer's DICT key) ≤ 77 charactersinfoPagador // payer information about the Pix to be sent. string ≤ 140 characters | Yes | object |
| favorecido | The favorecido field, required, contains the Pix key that will be credited the set amount. Favorecido attributes: chave // The chave field, required, determines the Pix key registered in DICT that will be used to identify the Pix recipient. string (recipient's DICT Key) ≤ 77 characterschave attributes: cpf // The cpf field validates if the Pix key registered in the DICT belongs to the holder of the informed document ^[0-9]{11}$cnpj // The cnpj field validates if the Pix key registered in the DICT belongs to the holder of the informed document ^[0-9]{14}$Note: The cpf and cnpj attributes are optional, but once inserted in the schema, the filling becomes mandatory. contaBanco // The contaBanco field, required, determines the bank account details of the Pix recipient.contaBanco attributes: nome (Required) // ISPB of the receiver bank account (string) ≤ 200 characters cpf // Receiver's CPF (string) ^[0-9]{11}$cnpj // Receiver's CNPJ (string) ^[0-9]{14}$codigoBanco (Required) // ISPB of the receiver bank account (string) ^[0-9]{8}$agencia (Required) // Recipient's agency at their Bank (string) ^[0-9]{1,4}$conta (Required) // Recipient's account at their Bank (string)^[0-9]+tipoConta (Required) // Type of the recipient's account at your Bank (string)^[0-9]+* Enum: "cacc"(Checking account), "svgs"(Saving account) | Yes | object |
| status | The status field on the return of the webhook represents the situation of the direct send request from a Pix to a Pix key, and can assume the following states: "EM_PROCESSAMENTO", "REALIZADO", "NAO_REALIZADO" | No | string |
Responses
- 200
- 400
- 409
- 422
- 500
Refund request.
Endpoint to request a return via a Pix e2eid and devolution ID. The reason that will be assigned to PACS.004 will be "Return requested by the receiving user of the original payment" whose acronym is "MD06" according to the RTReason tab of PACS.004 that appears in the Pix Message Catalog.
Requires authorization for the scope: pix.write
Request
(*) Required attribute
| Attribute | Description | Required | Type |
|---|---|---|---|
| e2eid | EndToEndIdentification that transits in PACS002, PACS004 e PACS008 | Yes | string (Ent to end id of the transaction)32 characters[A-Z0-9-]{32} |
| id | Customer-generated ID to represent only one return. | Yes | string (Return Id )[A-Z0-9-]{1,35} |
Data for refund request.
(*) Required attribute
| Attribute | Description | Required | Type |
|---|---|---|---|
| valor | Amount requested for return. The sum of the values of all refunds cannot exceed the total value of the Pix. | Yes | string (Amount)\d{1,10}\.\d{2} |
Responses
- 201
- 400
- 409
- 500
Get refund.
Endpoint to check a return through a Pix End To End ID and return ID.
Requires authorization for the scope: pix.read
Request
(*) Required attribute
| Attribute | Description | Required | Type |
|---|---|---|---|
| e2eid | EndToEndIdentification that transits in the PACS002, PACS004 e PACS008 | Yes | string (End to end Id of the transaction) 32 characters[A-Z0-9-]{32} |
| id | Customer-generated ID to represent only one return. | Yes | string (Return Id)[A-Z0-9-]{1,35} |
Responses
The responses below represent Success(200) and Consumption failures/errors.
- Exemplo 1 (200)
- Exemplo 2 (200)
- 400
- 500
Payload Locations
The set of endpoints below are intended to handle configuration and removal of locations for the use of the payloads.
Creating location from a payload
Endpoint to create a location from the payload.
Requires authorization for the scope: payloadlocation.write
Request
- Exemplo
Responses
The responses below represent Success(200) and Consumption failures/errors.
- 201
- 400
Get locations
Endpoint to get registered locations.
Requires authorization for the scope: payloadlocation.read
Request
To obtain the result of the locations query it is necessary to inform the parameters inicio e fim ("start" and "end") , as shown in the code snippet below. These parameters restrict the results to the locations within this date range.
(*) Required attribute
| Attribute | Description | Required | Type |
|---|---|---|---|
| inicio | Filters records whose creation date is greater than or equal to the start date. Respects RFC 3339. | Yes | string <date-time> |
| fim | Filters records whose creation date is less than or equal to the end date. Respects RFC 3339. | Yes | string <date-time> |
Responses
The responses below represent Success(200) and Consumption failures/errors.
- 200
- 400
Recover payload location
Endpoint to get registered locations.
Requires authorization for the scope: payloadlocation.read
Request
(*) Required attribute
| Attribute | Description | Required | Type |
|---|---|---|---|
| id | Location id registered to serve a payload. | Yes | string |
Response
The responses below represent Success(200) and Consumption failures/errors.
- 200
- 400
Generate QRCode from location
Endpoint to generate QRCode and copy/paste code from a location.
Requires authorization for the scope: payloadlocation.read
Request
(*) Required attribute
| Attribute | Description | Required | Type |
|---|---|---|---|
| id | Location id registered to serve a payload. | Yes | string |
Responses
The responses below represent Success(200) and Consumption failures/errors.
- 200
- 400
Unlink a txid from location
Endpoint used to unlink a txid from location.
Send successfully executed, the entity loc will no longer display a txid if it was displayed before the call of the function. In addition, the entity cob or cobv associated with the unlinked txid will also no longer display a location. This operation does not change the status of the cob or cobv.
Requires authorization for the scope: payloadlocation.write
Request
(*) Required attribute
| Attribute | Description | Required | Type |
|---|---|---|---|
| id | Location id registered to serve a payload. | Yes | string |
Responses
The responses below represent Success(200) and Consumption failures/errors.
- 200
- 400
Webhook
This section brings together endpoints for managing notifications by the receiving PSP to the receiving user.
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
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 Pix Webhook
Endpoint for configuring the notification service about Pix received and Pix send. Pix from static charges will only be notified if they are associated with a txid.
Requires authorization for the scope: webhook.write
Request
(*) Required attribute
| Attribute | Description | Required | Type |
|---|---|---|---|
| chave | The chave field determines the Pix key registered in the DICT that will be used for billing. This key will be read by the payer's PSP application for consultation with the DICT, which will return information that will identify the recipient of the charge. | Yes | string (DICT Key) ≤ 77 characters; |
Data for webhook configuration.
- Example
(*) Required attribute
| Attribute | Description | Required | Type |
|---|---|---|---|
| webhookUrl | Url where the notification will be sent | Yes | string <uri> |
Responses
The responses below represent Success(200) and Consumption failures/errors.
- 201
- 400
Get webhook information
Endpoint for retrieving information about the pix webhook.
Requires authorization for the scope: webhook.read
Request
(*) Required attribute
| Attribute | Description | Required | Type |
|---|---|---|---|
| chave | The chave field determines the Pix key registered in DICT that will be used for billing. This key will be read by the payer's PSP application for dict consultation, which will return the information that will identify the recipient of the charge. | Yes | string (DICT key) ≤ 77 characters; |
Response
The answer below represents Success(200) of consumption.
- 200
Get list of webhooks
Endpoint for consulting webhooks associated with keys through parameters such as início and fim ("start" and "end"). Attributes are entered as query params.
Requires authorization for the scope: cob.write
Request
The snippet below shows how the parameters inicio and fim (required) should be passed on in the requisition.
(*) Required attribute
| Attribute | Description | Required | Type |
|---|---|---|---|
| inicio | Filters records whose creation date is greater than or equal to the start date. Respects RFC 3339. | Yes | string <date-time> |
| fim | Filters records whose creation date is less than or equal to the end date. Respects RFC 3339. | Yes | string <date-time> |
Responses
The responses below represent Success(200) and Consumption failures/errors.
- 200
- 400
Delete webhook.
Endpoint to delete pix webhook.
Requires authorization for the scope: webhook.write
Request
(*) Required attribute
| Attribute | Description | Required | Type |
|---|---|---|---|
| chave | The chave field determines the Pix key registered in DICT that will be used for the charge. This key will be read by the payer's PSP application for DICT consultation, which will return the information that will identify the recipient of the charge. | Yes | string (DICT key) ≤ 77 characters; |
Response
- 204
Receiving Callbacks
This service is protected by an mTLS authentication layer. Callbacks are sent by Gerencianet via POST <url-webhook-cadastrada>/pix when there is a change in Pix status.
Request
A POST request is sent by Gerencianet to the URL you have registered as a webhook for a given key. When there is a change in the status of a Pix transaction, involving the associated key, a JSON object (such as the examples below) is sent to your server. Each request sent has a timeout of 60 seconds, that is, a callback request is interrupted upon reaching 60 seconds without response.
- Example - Received Pix
- Example - Refound
- Example - Send Pix
- Example - Received Pix with informated tariff
The following table details the fields present in the JSON object that will be sent in the notification.
(*) Required attribute
| Attribute | Description | Required | Type |
|---|---|---|---|
| endToEndId | EndToEndIdentification that transits in PACS002, PACS004 e PACS008 | Yes | string (End to end id of the transaction) [A-Z0-9-]{26,35} |
| txid | Transaction Id Determines the identifier of the transaction. The purpose of this field is to be an element that allows the recipient's PSP to present to the receiving user the functionality of reconciliation of payments, more details click here. | No | Array of objects (Pix)[A-Z0-9-]{26,35} |
| valor | Pix amount. | Yes | string \d{1,10}\.\d{2} |
| horario | Time the Pix was processed on psp. | Yes | string <date-time> (Horário) |
| pagador | A CPF or CNPJ can be the payer of a charge. The pagador.cpf and pagador.cnpj field are not allowed to be filled in at the same time. If the pagador.cnpj field is filled in, then the pagador.cpf field cannot be filled in, and vice versa. pagador: cpf*// CPF of the paying user.string /^\d{11}$/nome*// Name of the paying user. string (Name) ≤ 200 characters | No | Natural person (object) or Legal Entity (object) |
| infoPagador | Free payer information | Yes | string ≤140 characters |
| devolucoes | devolucoes:id*// Customer-generated ID to represent only onde refund.string (Refund Id) [A-Z0-9-]{26,35}rtrId*// ReturnIdentification that transits in PACS004. string (RtrId) ≤ 32 charactersvalor*// Amount to refund.string \d{1,10}\.\d{2}horario*// Time attributesobject
status*// Refund status. Enum: "EM_PROCESSAMENTO","DEVOLVIDO","NAO_REALIZADO"string (Status) | No | Array () |
Response
Callback requests await a response with HTTP 2XX status. If the client server returns a different status, Gerencianet makes up to 10 notification retries. The first retry will be made 5 minutes after the callback submission fails. 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 server returns HTTP 429 status (too many requests), Gerencianet servers will attempt to send the notification up to 6 times as well as 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 |
Gerencianet's exclusive endpoints
The endpoints listed in this section are intended to facilitate the use of the Pix API for Gerencianet clients. With the following endpoints you can obtain and change your account information directly through the API, depending on the need for your integration.
Create evp key
Endpoint used to create a random Pix key (evp).
Requires authorization for the scope: gn.pix.evp.write
Request
The request sent to this endpoint does not need a body, only the OAuth authorization headers and the account certificate, as well as the previous endpoints.
Responses
The responses below represent Success(200) and Consumption failures/errors.
- 201
- 400
- 500
Get evp keys
Endpoint used to list random Pix keys (evp). The list will only show the keys of the random type.
Requires authorization for the scope: gn.pix.evp.read
Request
The request sent to this endpoint does not need a body, only the OAuth authorization headers and the account certificate, as well as the previous endpoints.
Responses
The responses below represent Success(200) and Consumption failures/errors.
- 200
- 500
Delete evp key
Endpoint used to remove a random Pix key (evp). If you remove a random key, there is no way to create the same key again: the uuid is generated by DICT, and with each key record request, we are returned a different hash. This means that charges created for the removed key can no longer be paid because the payload will no longer be returned.
Requires authorization for the scope: gn.pix.evp.write
Request
The request sent to this endpoint does not need a body, only the information needed for authorization such as the previous endpoints and the chave (Pix key) parameter passed in the URL, which corresponds to the random Pix key (evp) that will be erased.
Responses
The responses below represent Success(200) and Consumption failures/errors.
- 200
- 400
- 500
Get your account balance
Endpoint for the purpose of searching the balance in your Gerencianet account. You can enable scope in your application settings in your Gerencianet account.
Requires authorization for the scope: gn.balance.read
Request
The request sent to this endpoint does not need a body, only the OAuth authorization headers and the account certificate, as well as the previous endpoints.
Responses
The responses below represent Success(200) and Consumption failures/errors.
- 200
- 500
Create/modify account settings
Endpoint for the purpose of creating and modifying your account settings related to the API.
Requires authorization for the scope: gn.settings.write
Request
Below is an example of body for the requisition:
- Example
(*) Required attribute
| Attribute | Description | Required | Type |
|---|---|---|---|
| pix | Object containing pix-related account settings.receberSemChave*// Required Boolean attribute that configures the possibility of receiving Pix without registered keys.booleanchaves// Optional object attribute. It can contain one or more keys and their individual settings.
| Yes | Object |
Responses
The responses below represent Success(200) and Consumption failures/errors.
- 204
- 400
- 500
Get account settings
Endpoint for the purpose of listing the settings set on the account.
Requires authorization for the scope: gn.settings.read
Request
The request sent to this endpoint does not need a body, only the OAuth authorization headers and the account certificate, as well as the previous endpoints.
Responses
The responses below represent Success(200) and Consumption failures/errors.
- 200
- 400
Request Reconciliation Extract
Endpoint to request reconciliation extract.
Requires authorization for the scope: gn.reports.write
Request
Below is an example of body for the requisition:
- Example 1
- Example 2
(*) Required attribute
| Attribute | Description | Required | Type |
|---|---|---|---|
| dataMovimento | Date of the desired extract | Yes | string |
| tipoRegistros | Object containing the desired parameters | Yes | object |
| pixRecebido | Received Pix (PR) | No | boolean |
| pixDevolucaoEnviada | Pix Return Sent (PDE) | No | boolean |
| tarifaPixRecebido | Pix Received Rate (TPR) | No | boolean |
| pixEnviadoChave | Pix Sent via key (PEC) | No | boolean |
| pixEnviadoDadosBancarios | Pix Sent via bank details (PEB) | No | boolean |
| pixDevolucaoRecebida | Pix Return Received (PDR) | No | boolean |
Note: The attributes that are not mandatory belong to the object tipoRegistros. To perform the request, it is necessary that the tipoRegistros contain at least one of the attributes. When the attribute is not entered, the value is assumed to be false.
Responses
The responses below represent Success(202) and Consumption failures/errors.
- 202
- 400
- 500
Status types returned in the body:
AGUARDANDO_PROCESSAMENTO: This status indicates that the extract request was successfully received and is in the queue waiting to start processing;
EM_PROCESSAMENTO: This status indicates that the file generation has started and is in the data processing stage;
CONCLUIDO: This status indicates that an extract with the same parameters was requested previously and a file with the returned id is already downloadable.
GOOD PRACTICE:
After performing the POST request, the API has an average waiting time of 30 seconds to process the extract. So it is recommended to wait this time to perform the GET request.
Request Download Reconciliation Extract
Endpoint to request the download of the reconciliation extract.
Requires authorization for the scope: gn.reports.read
Request
| Attribute | Description | Required | Type |
|---|---|---|---|
| id | Identifier to fetch requested report | Yes | string |
Responses
Attention
If it consumes the GET endpoint and the extract has not yet been processed, the response will be success(202) and the return will be similar to what is returned in the request, informing which processing step the request is in.
The responses below represent Success(200) and Consumption failures/errors.
- 200
- 202
- 404
- 500
Return detail
For more information about the .CSV document that is returned and the caption of the fields, download the PDF available on this link.