Credentials, Certificate and Authorization
The Efí Statements API offers endpoints for managing and processing CNAB 240 files. With it, you can:
- consult generated files;
- create and review recurrences;
- generate keys.
To integrate the Statements API with your system or platform, you must have an Efí Digital Account. After opening your account, you will be able to obtain the necessary credentials and certificates to communicate with the Extratos Efí API.
See below how to obtain credentials, certificates and details about the authorization and security of your integration with Efí.
Within systems integrated with our API, it is important that login operations and changing integration keys be done securely. We suggest implementing two-factor authentication and other security practices.
Getting application credentials
An integrator can create as many applications as he wants. For each application, 2 pairs of keys Client_Id
and Client_Secret
are generated, one pair for use in Production environment (?) and another for Sandbox environment (?).
To use the Statements Efí API, it is also necessary to have the required scopes activated.
Understanding application's scopes
When creating or editing an application in your Efí Account, you will need to configure the scopes that the application will have access to. The choice of these scopes defines which actions an application will be authorized to perform via API.
The scopes available in the Statements Efí API are listed below with their respective permission descriptions:
gn.cnab-statement.statement.write
- creation and review of recurrences;gn.cnab-statement.statement.read
- consultation of generated files and registered recurrences and download of the statement;gn.cnab-statement.keys.write
- generates key;
Create a new application or configure an existing one
Below you can see how to create an application or use an existing application to integrate with the Statements Efí API.
- Create an application
- Use an existing application
To create an application for use with the Statements Efí API, follow the steps below:
- Access your account and click on the "API" item at the bottom of the left menu of the Efí account;
- Click on "Criar aplicação"
- Enable the Statements API and choose the scopes you want to release in Production and Sandbox environments (you can edit them in the future);
- With the selected scopes, click "Continuar".

Illustration of the steps for create a new application integrated with the Statements API
To use an application already registered in your account and use it to integrate with the Statements API, follow the steps below:
- Access your account and click on the "API" item at the bottom of the left menu of the Efí account;
- Click on "Aplicações". Then, choose the application to be edited, click on the three dots and select "Configurações";
- Enable the Statements API and choose the scopes you want to release in Production and Homologation environments (you can edit them whenever you want);
- With the selected scopes, click "Continuar".

Steps until editing an application

Edits required for an application's access to the Statements API
Generating and converting a P12 certificate
To generate and convert a certificate, if necessary, you can access the link.
Base route
In this documentation, you will notice references to the Base route or Base URL for the Production environment. This route is, in fact, the URL at which the Statements Efí API is located. Thus, when we refer to endpoints, it is implied that these URL segments also make up the final route of the desired resource.
Use the route below to communicate your application with the production environment offered by Efí.
Environment | Base route |
---|---|
Production | https://extratos.api.efipay.com.br |
OAuth2 Authentication
The authorization mechanism for requests made to the Statements Efí API is compatible with the OAuth2 protocol.
Objective of OAuth2
Obtain an access token (access_token
) that should be used to authorize all calls made to the API, verifying if a particular application has permissions to consume the requested endpoint.
How request authentication is done
It is done with HTTP Basic Auth using the Client_Id
and Client_Secret
of the application created in your Efí account.
Through this authentication, OAuth can respond with the authorizations that the application has, and consequently authorize or deny requests based on this information.
The P12/PEM Certificate generated in the previous steps is required in all requests made to the Statements API, including the authorization request.
Postman Collection for Statements API
This is the link to our Collection, which we will keep updated with the endpoints of the Statements Efí API.
Setting Postman for tests
Using the Postman software is optional. The following paragraphs explain how to set it up. If you do not wish to use Postman for testing, you can skip to the topic: Obtain Authorization.
To proceed with the Postman setup step, you should have:
- A pair of credentials
Client_Id
andClient_Secret
from an application registered in your Efí Account; - A P12/PEM certificate generated as illustrated in the previous steps;
- The Postman software installed on your computer (If you don't have it, click here to download);
1. Creating an Environment
Creating an Environment in Postman is necessary for some built-in automations in the collection to work. These automations are designed to make testing easier for developers.
With them, you only need to request authorization once, and then the access_token
is stored as an environment variable in Postman, available for use in subsequent requests.
To create an Environment, follow the steps below.
- Press the shortcut
Ctrl+N
and select "Environment"; - Assign a name, preferably specifying whether this Environment will be pointed to the Production or Sandbox environment;
- Create the variable
efi-ext-api
and, as the Initial value, enter the URL of the Statements Efí API for Production; - Save your Environment;
- Select the desired Environment. This way, Postman will understand the created variable.
The images below illustrate the steps above. As an example, an Environment was created pointing to the Production environment of the Statements Efí API.

Creating a new environment

Environment settings
2. Setting the certificate in Postman
All requests made to the Statements Efí API require the certificate generated in your Efí account. Therefore, to facilitate your testing using Postman, follow the steps below to configure the use of the certificate during requests automatically:
- Click on the gear icon in the top right corner of Postman;
- Then, click on "Settings" to open the settings;
- In the top tab, click on "Certificates";
- Next, click on "Add Certificate";
- In the new certificate configuration window, fill in the "Host" field with the Base route of the environment to which the certificate belongs (Production or Sandbox);
- Use the "PFX File" field to inform Postman where your P12/PEM certificate file is located;
- 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.

Accessing Postman settings

Adding a new certificate in Postman

Certificate settings
3. Assigning the Client_Id and Client_Secret in Postman
To complete the configuration of your Postman, you need to set up the credentials of an application from your Efí account. These credentials are used for Basic Auth and obtaining the access_token
with OAuth.
Follow the steps below to include the credentials and perform your first test on the Statements API.
- In the imported collection, navigate to the route
/v1/oauth/token
and double-click to open; - Access the "Authorization" menu and make sure the "Type" is selected as "Basic Auth";
- In the "username" and "password" fields, fill in with the credentials of your application, Client_Id and Client_Secret, respectively;
- To test, click the "Send" button to submit the request
The image below illustrates the steps above. If everything was followed correctly, you should receive a response in JSON format, containing the access_token
, token_type
, expires_in
, and scope
(as shown in the image below).

Using the credentials of an application for request authorization
Obtain authorization
This endpoint is used to:
- authorize the credentials of an application
- obtain the scopes that the application has to access the other endpoints of the API.
The P12/PEM certificate must be present in the authorization request so that the handshake with the API server is allowed.
Examples of authorization using the .P12 certificate
For using the Statements Efí API, it is necessary for the client and the server to communicate over a mutually verified connection. Verification is done through a bidirectional certificate (.PEM or .P12), meaning the server and client have implemented a private key certificate and a public key certificate that allows each to ensure the other's identity.
Therefore, to make any HTTP request to the Statements API, including the authorization request with OAuth2, the .P12 or .PEM certificate must be present in the request headers.
Below, we provide examples of how to consume authorization from the Statements Efí API, incorporating this certificate into the request.
- PHP
- Node
- Python
- .Net
- Ruby
- Java
- Go
// Developed by the Technical Consulting Team at Efí
<?php
$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://extratos.api.efipay.com.br/v1/oauth/token", // Base route, Sandbox or production
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"], // Certificate path
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>";
?>
// Developed by the Technical Consulting Team at Efí
"use strict";
const https = require("https");
var axios = require("axios");
var fs = require("fs");
// Insert the path to your .p12 certificate within your project
var certificado = fs.readFileSync("./certificado.p12");
// Insert the values of your statement production credentials
var credenciais = {
client_id: "YOUR-CLIENT-ID",
client_secret: "YOUR-CLIENT-SECRET",
};
var data = JSON.stringify({ grant_type: "client_credentials" });
var data_credentials = credenciais.client_id + ":" + credenciais.client_secret;
// Encoding the credentials in base64
var auth = Buffer.from(data_credentials).toString("base64");
const agent = new https.Agent({
pfx: certificado,
passphrase: "",
});
// Consumption in production of the POST oauth/token route
var config = {
method: "POST",
url: "https://extratos.api.efipay.com.br/v1/oauth/token",
headers: {
Authorization: "Basic " + auth,
"Content-Type": "application/json",
},
httpsAgent: agent,
data: data,
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
#Developed by the Technical Consulting Team at Efí
import requests
import base64
credentials = {
"client_id": "YOUR-CLIENT-ID",
"client_secret": "YOUR-CLIENT-SECRET",
}
certificado = './certificado.pem' # The certificate variable is the directory where your certificate in .pem format should be inserted
auth = base64.b64encode(
(f"{credentials['client_id']}:{credentials['client_secret']}"
).encode()).decode()
url = "https://extratos.api.efipay.com.br/v1/oauth/token" #For the Production environment
payload="{\r\n \"grant_type\": \"client_credentials\"\r\n}"
headers = {
'Authorization': f"Basic {auth}",
'Content-Type': 'application/json'
}
response = requests.request("POST",
url,
headers=headers,
data=payload,
cert=certificado)
print(response.text)
// Developed by the Technical Consulting Team at Efí
using System;
using System.Security.Cryptography.X509Certificates;
using System.Collections.Generic;
using RestSharp;
namespace Exemplo
{
class Authorize
{
public static string Base64Encode(string plainText)
{
var plainTextBytes = System.Text.Encoding.UTF8.GetBytes(plainText);
return System.Convert.ToBase64String(plainTextBytes);
}
static void Main(string[] args)
{
var credencials = new Dictionary<string, string>{
{"client_id", "YOUR-CLIENT-ID"},
{"client_secret", "YOUR-CLIENT-SECRET"}
};
var authorization = Base64Encode(credencials["client_id"] + ":" + credencials["client_secret"]);
var client = new RestSharp.RestClient("https://extratos.api.efipay.com.br/v1/oauth/token");
var request = new RestRequest(Method.POST);
X509Certificate2 uidCert = new X509Certificate2("./certificado.p12", "");
client.ClientCertificates = new X509CertificateCollection() { uidCert };
request.AddHeader("Authorization", "Basic " + authorization);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\r\n \"grant_type\": \"client_credentials\"\r\n}", ParameterType.RequestBody);
IRestResponse restResponse = client.Execute(request);
string response = restResponse.Content;
Console.WriteLine(response);
}
}
}
#Developed by the Technical Consulting Team at Efí
require "uri"
require "net/http"
require "openssl"
client_id = "YOUR-CLIENT-ID";
client_secret = "YOUR-CLIENT-SECRET";
certfile = File.read("certificado.pem") # The certfile variable is the directory where your certificate in .pem format should be inserted
url = URI("https://extratos.api.efipay.com.br/v1/oauth/token") #For the Production environment
https = Net::HTTP.new(url.host, url.port);
https.use_ssl = true
https.cert = OpenSSL::X509::Certificate.new(certfile)
https.key = OpenSSL::PKey::RSA.new(certfile)
request = Net::HTTP::Post.new(url)
request.basic_auth(client_id, client_secret)
request["Content-Type"] = "application/json"
request.body = "{\r\n \"grant_type\": \"client_credentials\"\r\n}"
response = https.request(request)
puts response.read_body
// Developed by the Technical Consulting Team at Efí
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.URL;
import java.util.Base64;
import javax.net.ssl.HttpsURLConnection;
import javax.net.ssl.SSLSocketFactory;
public class Auth {
public static void main(String[] args) throws Exception {
String client_id = "YOUR-CLIENT-ID";
String client_secret = "YOUR-CLIENT-SECRET";;
String basicAuth = Base64.getEncoder().encodeToString(((client_id+':'+client_secret).getBytes()));
//Directory where your certificate in .p12 format should be inserted
System.setProperty("javax.net.ssl.keyStore", "certificado.p12");
SSLSocketFactory sslsocketfactory = (SSLSocketFactory) SSLSocketFactory.getDefault();
URL url = new URL ("https://extratos.api.efipay.com.br/v1/oauth/token"); //For the Production environment
HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();
conn.setDoOutput(true);
conn.setRequestMethod("POST");
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Authorization", "Basic "+ basicAuth);
conn.setSSLSocketFactory(sslsocketfactory);
String input = "{\"grant_type\": \"client_credentials\"}";
OutputStream os = conn.getOutputStream();
os.write(input.getBytes());
os.flush();
InputStreamReader reader = new InputStreamReader(conn.getInputStream());
BufferedReader br = new BufferedReader(reader);
String response;
while ((response = br.readLine()) != null) {
System.out.println(response);
}
conn.disconnect();
}
}
// Developed by the Technical Consulting Team at Efí
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
"crypto/tls"
)
const(
client_id = "YOUR-CLIENT-ID"
client_secret = "YOUR-CLIENT-SECRET"
)
func main() {
url := "https://extratos.api.efipay.com.br/v1/oauth/token"// Base route, Sandbox or production
method := "POST"
payload := strings.NewReader(`{"grant_type": "client_credentials"}`)
cert, _ := tls.LoadX509KeyPair("CA.crt.pem", "KEY.crt.pem")// Your certificate and private key generated from the OpenSSL conversion commands
client := &http.Client{
Transport: &http.Transport{
TLSClientConfig: &tls.Config{
Certificates: []tls.Certificate{cert},
},
},
}
req, err := http.NewRequest(method, url, payload)
if err != nil {
fmt.Println(err)
return
}
req.SetBasicAuth(client_id, client_secret)
req.Header.Add("Content-Type", "application/json")
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := ioutil.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Example of authorization response
The code snippet below represents an example of the OAuth response to your authorization request.
- Response
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "gn.cnab-statement.keys.write gn.cnab-statement.statement.read gn.cnab-statement.statement.write"
}