Skip to main content

Efí Exclusive Endpoints

The endpoints listed in this section aim to facilitate the use of the Pix API for Efí clients. With the following endpoints, you can obtain and modify information from your account directly through the API, according to the needs of your integration.


Create EVP Key​

Endpoint used to create a random Pix key (evp).

POST /v2/gn/evp
Requires authorization for the scope: gn.pix.evp.write


Request

The request sent to this endpoint does not require a body, only the OAuth authorization headers and the account certificate, just like the previous endpoints.


Responses

The responses below represent Success(201) and consumption failures/errors.

{
  "chave": "345e4568-e89b-12d3-a456-006655440001"
}

List EVP Keys​

Endpoint used to list random Pix keys (evp). The listing will only show keys of the random type.

GET /v2/gn/evp
Requires authorization for the scope: gn.pix.evp.read


Request

The request sent to this endpoint does not require a body, only the OAuth authorization headers and the account certificate, just like the previous endpoints.

Responses

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

{
  "chaves": [
    "355e4568-e89b-1243-a456-006655440001",
    "133e4568-e89b-1243-a456-006655440000"
  ]
}

Remove EVP Key​

Endpoint used to remove a random Pix key (evp). It is important to note that, when removing a random key, it will not be possible to create it again because the uuid is generated by DICT and each registration request results in 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.

DELETE /v2/gn/evp/:chave
Requires authorization for the scope: gn.pix.evp.write


Responses

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

Removed random key.

Get Account Balance​

Endpoint designed to check the balance in your Efí account. You can enable the scope in the settings of your application in your Efí account.

GET /v2/gn/saldo/
Requires authorization for the scope: gn.balance.read


Request

The request sent to this endpoint does not require a body, with the option to specify the bloqueios parameter as true or false, as shown in the code snippet below. This parameter displays or hides balances blocked by MED or judicial action.

/v2/gn/saldo?bloqueios=true

Responses

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

//Bloqueios = true
{
  "saldo": "100.00",
  "bloqueios": {
    "judicial": "0.00",
    "med": "0.00",
    "total": "0.00"
  }
}

Create/modify account settings​

Endpoint designed to create and modify account settings related to the API client.

Through this endpoint, you can define whether you want to exclusively receive a Pix through a transfer via key (receberSemChave = false), or allow receipts also through bank data (receberSemChave = true). In addition to the account configuration, it can also be used to modify Pix receipt settings associated with a specific key, such as allowing receipt without a txid, or blocking receipt by document type CPF or CNPJ, for example, and tariff and/or payer information in the webhook.

Configuration to block receipt when the Debtor's document is different from the Payer's document

  • This configuration ("documentoPagadorIgualDevedor": true) validates both CPF and CNPJ, that is, it verifies the payer's document.
  • It is a configuration applied at the key level, that is, there can be a key with the configuration enabled (true), another with the configuration disabled (false) and a third without the configuration defined, being interpreted as false.
  • When the configuration is "documentoPagadorIgualDevedor": true, for any COB or COBV payment received in this key, the payer's CPF is compared with the debtor's CPF specified when issuing the charge.
    • If the CPFs are different, the payment will not be made, and the charge will remain in active status, and can only be paid by the person defined as the debtor.
    • If the CPFs are the same, the payment will be completed normally.
  • If the configuration is "documentoPagadorIgualDevedor": true, but the COB does not have the debtor field filled in, the payment will be made normally. However, this case does not occur for COBV, as the debtor field is mandatory in COBV, ensuring that documents are checked.

For more information about this endpoint, visit the Module 5.1 of our online course.

PUT /v2/gn/config
Requires authorization for the scope: gn.settings.write


Request

{
  "pix": {
      "receberSemChave": true,
      "chaves": {
          "355e4568-e89b-1243-a456-006655440001": {
              "recebimento": {
                  "txidObrigatorio": false,
                  "recusarTipoPessoa": "PF",
                  "qrCodeEstatico": {
                      "recusarTodos": false
                  },
                  "documentoPagadorIgualDevedor": true,
                  "webhook": {
                      "notificacao": {
                          "tarifa": true,
                          "pagador": true
                      },
                      "notificar": {
                          "pixSemTxid": true
                      }
                  }
              },
              "envio": {
                  "webhook": {
                      "notificacao": {
                          "tarifa": true,
                          "favorecido": true
                      }
                  }
              }
          }
      }
  }
}

Responses

The responses below represent Success(204) and consumption failures/errors.

Configurações criados / modificadas

List account settings​

Endpoint used to list the settings defined in the account.

GET /v2/gn/config
Requires authorization for the scope: gn.settings.read


Request

The request sent to this endpoint does not require a body, only the OAuth authorization headers and the account certificate, as with the previous endpoints.Responses

The response below represent Consumption Success (200).

{
  "pix": {
    "receberSemChave": true,
    "chaves": {
      "355e4568-e89b-1243-a456-006655440001": {
        "recebimento": {
          "txidObrigatorio": true,
          "recusarTipoPessoa": "PF",
          "qrCodeEstatico": {
              "recusarTodos": false
          }
        }
      }
    }
  }
}

Get Receipts​

Endpoint designed to retrieve receipts for Pix transactions via API..

GET /v2/gn/pix/comprovantes
Requires authorization for the scope: gn.receipts.read


Request

To retrieve the query result, it is necessary to provide at least one parameter with the ID of the desired transaction. The query parameter can be either e2eId, idEnvio, rtrId, or txid, and only one identifier can be used per request.

Responses

The response below represent Consumption Success (200).


Get Token Bucket​

Endpoint to retrieve the number of tokens for each token package in the integrator account. There are two types of buckets: the bucket of tokens for document and evp keys, called bucketA, and the bucket of tokens for phone and email keys, called bucketB.

GET /v2/gn/chaves/balde
Requires authorization for the scope: gn.keys.bucket.read


Request

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

Responses

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

{
  "baldeA": {
      "tiposChave": [
          "cpf",
          "cnpj",
          "evp"
      ],
      "capacidade": "number",
      "fichasDisponiveis": "number",
      "taxaDeReposicaoFichas": "number",
      "periodoReposicaoEmSegundos": "number",
  },
  "baldeB": {
      "tiposChave": [
          "telefone",
          "email"
      ],
      "capacidade": "number",
      "fichasDisponiveis": "number",
      "taxaDeReposicaoFichas": "number",
      "periodoReposicaoEmSegundos": "number",
  }
}

List account MED infractions​

Endpoint to list open violations across all accounts associated with the document linked to the authenticated account.

GET /v2/gn/infracoes
Requires authorization for the scope: gn.infractions.read


Request

The code snippet below illustrates the consumption of the endpoint in a request with as few parameters as possible (the inicio and fim date range) and the format in which these parameters should be passed on.

/v2/gn/infracoes?inicio=2020-10-22T00:00:00Z&fim=2023-12-30T23:00:00Z

Responses

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

{

  "parametros":{
    "inicio":"2023-11-22T16:01:35Z",
    "fim":"2023-12-22T16:01:35Z",
    "paginacao":{
       "paginaAtual":0,
       "itensPorPagina":10,
       "quantidadeDePaginas":2,
       "quantidadeTotalDeItens":20
    }
  },
  "infracoes":[
    {
      "idInfracao":"8ad75c93-6150-422c-929e-822f361c7a6b",
      "endToEndId":"E09089356202312181249APId91a6304",
      "protocolo":1313,
      "dataTransacao":"2023-12-22T16:01:35Z",
      "valor":100,
      "chave": "[email protected]", //OPTIONAL
      "status": "ABERTA", //ENUM["ABERTA", "ACEITA", "CANCELADA_EFI", "CANCELADA_EFI", "EM_DEFESA", "REJEITADA"]
      "razao":"Solicitacao de devolução",
      "tipoSituacao": "golpe", //OPTIONAL. ENUM["golpe", "aquisição da conta", "coerção", "acesso fraudulento", "outro", "desconhecido"]
      "tipoFraude": "aplicativo fraudulento", //OPTIONAL.
      "comentario": "Transação feita através de Qrcode falso em boleto", //OPTIONAL
      "defesa": "Comentario de defesa", //OPTIONAL 
      "justificativaAnalista": "Não foi identificado a fraude", //OPTIONAL
      "identificadorTicket":[
          94,
          95
      ],
      "dadosAnalise":{
          "abertura":"2023-12-22T16:01:35Z",
          "prazoFinalizacao":"2023-12-22T16:01:35Z",
          "recebimentoDefesa": "2023-12-22T16:01:35Z", //OPTIONAL 
          "finalizacao": "2023-12-22T16:01:35Z" //OPTIONAL
      },
      "origem":{
          "nomeParticipante":"BANCO XYZ",
          "conta":10001,
          "nome":"Fulano de Tal",
          "documento":"800000000000000"
      },
      "destino":{
          "nomeParticipante":"Efí S/A",
          "conta":10001,
          "nome":"Fulano de Tal",
          "documento":"800000000000000"
      },
      "criadoEm":"2023-12-22T16:01:35Z",
      "atualizadoEm":"2023-12-22T16:01:35Z"
    }
  ]
}

Submit MED infringement defense​

Endpoint that allows you to create a defense for a specific offense.

Important!

We emphasize that the information sent through this endpoint does not replace the ticket submission. Our analyst may contact you through the ticket to request additional documents or information, if necessary.

The data sent by this endpoint only serves to complement the analysis, but does not eliminate the need for follow-up via ticket, especially since the defense endpoint does not currently allow attachments to be sent.


POST /v2/gn/infracoes/:idInfracao/defesa
Requires authorization for the scope: gn.infractions.write


Request

{
  "analise": "rejeitado",
  "justificativa": "Justificativa"
}

Responses

The responses below represent Success(201) and consumption failures/errors.

MED infringement defense created

Request Reconciliation Statement​

Endpoint for requesting a reconciliation statement.

POST /v2/gn/relatorios/extrato-conciliacao
Requires authorization for the scope: gn.reports.write


Request


{
  "dataMovimento": "2023-12-15",
  "tipoRegistros": {
    "pixRecebido": true,
    "pixEnviadoChave": true,
    "pixEnviadoDadosBancarios": true,
    "estornoPixEnviado": true,
    "pixDevolucaoEnviada": true,
    "pixDevolucaoRecebida": true,
    "tarifaPixEnviado": true,
    "tarifaPixRecebido": true,
    "estornoTarifaPixEnviado": true,
    "saldoDiaAnterior": true,
    "saldoDia": true,
    "transferenciaEnviada": true,
    "transferenciaRecebida": true,
    "estornoTransferenciaEnviada": true,
    "tarifaTransferenciaEnviada": true,
    "estornoTarifaTransferenciaEnviada": true,
    "estornoTarifaPixRecebido": true,
    "splitPixDevolucaoEnviada": true
  },
  "dadosAdicionais": {
    "pixRecebido": [
      "nome"
    ],
    "pixEnviadoChave": [
      "nome",
      "documento"
    ]
  }
}

Responses

The responses below represent Success(202) and consumption failures/errors.

{
  "id": "3d0ca315-aff9–4fc2-be61–3b76b9a2d798",
  "dataSolicitacao": "“2022-02-14T14:42:51.013Z",
  "status": "AGUARDANDO_PROCESSAMENTO"
}

Types of status returned in the body:

  • AGUARDANDO_PROCESSAMENTO: This status indicates that the extract request was successfully received and is queued awaiting processing to begin;
  • EM_PROCESSAMENTO: This status indicates that the file generation has started and is in the process of processing the data;
  • CONCLUIDO: This status indicates that a extract with the same parameters was previously requested and a file with the returned id is now available for download.

Best Practice

After making the POST request, the API has an average waiting time of 30 seconds to process the extract. Therefore, it is recommended to wait for this time before making the GET request.


Request Download Reconciliation Statement​

Endpoint to request the download of the reconciliation statement.

GET /v2/gn/relatorios/:id
Requires authorization for the scope: gn.reports.read


Attention!

If you consume the GET endpoint and the extract 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.


When completed, the report is returned in CSV format. The file may contain the record blocks requested in the request, including SPDE for Sent Split Pix Refunds and additional fields in the PR and PEC blocks when enabled.

To view the complete structure of CSV blocks and fields, access the detailed manual for this endpoint.


Responses
The responses below represent Success(200) and consumption failures/errors.
CA;Efí;364;0001;292591;Acme SA;2026-04-24;2026-04-23;Extrato de Conciliação API Pix;1.0
T;0;0;0;0;0;0

Return Details

For more information about the .CSV document that is returned and the legend of the fields, download the PDF available below or through this link.


Last updated on