Skip to main content

Credentials, Certificate and Authorization

On this page, you'll find information about credentials, certificates, and authorization for the Efí Account Opening API.


With the Account Opening API, you can initiate the account opening process for your clients conveniently and obtain the necessary credentials and certificates to use the client's application.

Warning about Beta API

Currently, our API is in beta version. We're excited to share this tool with you; however, it's essential to remember that it's under active development and may undergo changes during this period.

We deeply value your feedback during this beta phase. We want to hear about your experiences and suggestions to continuously improve the API. Feel free to contact us through our support channels or community forum on Discord.


To integrate the Efí Account Opening API into your system or platform, you need to have an Efí Business Digital Account. After gaining access to the account, you can acquire the necessary credentials to establish communication with the Efí Account Opening API.

See below how to obtain credentials, certificates, and details about authorization and security for your integration with Efí.

Security in Credentials Management

Within systems integrated with our API, it's important that login operations and integration key changes are performed securely. We suggest implementing two-factor authentication and other security practices.


Getting application credentials

An integrating person can create as many applications as desired. For each application, 2 pairs of keys Client_Id and Client_Secret are generated, one pair for use in the Production environment (?) and another for the Sandbox environment (?). In addition, it is necessary to activate the necessary scopes to be able to use the Efí Account Opening API.

Understanding application's scopes

When creating or editing an application in your Efí Account, you will need to configure which scopes the application will have access to. The choice of these scopes defines what actions an application will be authorized to perform via the API.

The scopes available in the Account Opening API are listed below with their respective descriptions:

  • gn.registration.write - perform a simplified account opening request;
  • gn.registration.read - retrieve credentials for the simplified account;
  • gn.registration.webhook.write - change webhook;
  • gn.registration.webhook.read - get webhook

Attention!

To use the Efí Account Opening API, it is necessary to have the release of the scopes mentioned on this page. To obtain this release, it is necessary to fill out the form available here.


Create an application or configure an existing one

Attention!

To use the Efí Account Opening API, it is necessary to have an active application with scopes in both Production and Sandbox environments of the Pix or Open Finance API.


See how to create an application or use an existing application to integrate with the Efí Account Opening API.

To create an application and use the Account Opening API, follow these steps:

  1. Access your Efí account and click on "API" in the left menu;
  2. Click on "Criar aplicação";
  3. Enable the Pix API and choose the scopes you want to grant access to in both Production and Sandbox environments (you can edit them at any time);
  4. Once the scopes are selected, click on "Continuar".
banner

Illustration of the steps to create a new application integrated with the Pix API

Generating and converting a P12 certificate

To generate and convert a certificate, if necessary, you can access the link.

Base Routes

To communicate with Efí's production or Sandbox environments, use the following base routes or URLs.

EnvironmentBase Route
Productionhttps://abrircontas.api.efipay.com.br
Sandboxhttps://abrircontas-h.api.efipay.com.br

The following routes are still available for communication with your application but will be discontinued soon. We recommend that you use the routes mentioned above.

EnvironmentBase Route
Sandboxhttps://apis.gerencianet.com.br

OAuth2 Authentication

The Efí Open Finance API uses the OAuth 2.0 protocol to authorize requests made. The goal is to obtain an access token (access_token), which allows the authorized application to consume the API endpoints.

Request authentication is done using HTTP Basic Auth with the application's Client_Id and Client_Secret credentials created in the Efí account.

In this way, OAuth responds with the authorizations granted to the application, allowing or denying requests based on this information.

Attention!

The P12/PEM Certificate generated in the previous steps is required in all requests made to the Open Finance API, including the authorization request.


Postman Collection for Account Opening API


Setting Postman for tests

Tip

The use of the Postman software is optional. Below, we'll explain how to set it up. If you don't want to use Postman for testing, you can skip to the topic: Get Authorization.


To proceed with the Postman setup, you'll need:

  1. A pair of Client_Id and Client_Secret credentials from an application registered in your Efí Account;
  2. A P12/PEM certificate generated as illustrated in the previous steps;
  3. 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.

This will allow you to request authorization only once, storing the access_token as an environment variable in Postman, available for use in subsequent requests.

To create an Environment, follow these steps:

  1. Press Ctrl+N to trigger the shortcut and select "Environment";
  2. Assign a name, preferably specifying whether this Environment will point to the Production or Sandbox environment;
  3. Create the variable efi-cadastro-api with the initial value and insert the URL of the Efí Account Opening API for Production;
  4. Save your Environment;
  5. Select the desired Environment for Postman to understand the created variable.

The following images show the illustrated steps above. In this example, an Environment was created for the Production environment of the Efí Account Opening API.

banner

Creating a new environment


banner

Environment settings


2. Setting the certificate in Postman

All requests made to the Efí Account Opening API require the certificate generated in your Efí account. Therefore, to facilitate your tests using Postman, follow the steps below to configure the use of the certificate during requests automatically:

  1. Click on the gear icon in the top right corner of Postman;
  2. Then click on "Settings" to open the settings;
  3. In the top tab, click on "Certificates";
  4. Then click on "Add Certificate";
  5. In the configuration window of the new certificate, fill in the "Host" field with the Base Route of the environment to which the certificate belongs (Production or Sandbox);
  6. Use the "PFX File" field to inform Postman where your P12/PEM certificate file is located;
  7. Finish by clicking "Add" to save your settings.

By following these steps, Postman will automatically use the certificate in all requests made to the configured environment.

banner

Accessing Postman settings


banner

Adding a new certificate in Postman


banner

Certificate settings


3. Assigning the Client_Id and Client_Secret in Postman

To complete the configuration of your Postman, you need to configure the credentials of an application from your Efí account. These credentials are used for Basic Auth and to obtain the access_token through OAuth.

Follow the steps below to include the credentials and perform your first test on the Efí Open Finance API.

  1. In the imported collection, navigate to the route /v1/oauth/token and double-click to open;
  2. Access the "Authorization" menu and verify that the "Type" is selected as "Basic Auth";
  3. Fill in the "username" and "password" fields with the credentials of your application, i.e., the Client_Id and the Client_Secret, respectively;
  4. To test, click the "Send" button to send the request.

The image below illustrates the above steps. If everything was followed correctly, you should receive a JSON response, containing the access_token, token_type, expires_in, and scope (as in the image below).

banner

Using application credentials for request authorization


Obtain Authorization

POST /v1/oauth/token

This endpoint is used to authorize the credentials of an application and obtain access scopes to the Efí Open Finance API. To ensure security in the communication between client and server, it is essential that the P12/PEM certificate is present in the authorization request.

Examples of Authorization Using the .P12 Certificate

To use the Efí Open Finance API, the client and the server must communicate over a verified connection. This is done through the bidirectional certificate (.PEM or .P12), where both server and client have a private key certificate and a public key certificate to ensure their identities.

Therefore, when making any HTTP request to the Open Finance API, including the OAuth2 authorization request, it is essential that the .P12 or .PEM certificate is present in the request headers.

Below are examples of how to obtain authorization in the Efí Open Finance API, incorporating this certificate into the request.

// 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://pix-h.api.efipay.com.br/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>";
?>

Example of authorization response

The code snippet below represents an example of the OAuth response to your authorization request.

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

Tutorial Efí Account Opening API

In this video we will demonstrate the opening and authentication process in practice, as well as presenting the webhooks, endpoints and other important details of the account opening API.