Skip to main content

Credentials, Certificate and Authorization

On this page, you will find information about credentials, certificate, and authorization of the Efí Open Finance API.


Through the Open Finance API, we offer services that enable communication with the Efí initiator (authorized participant) and recipient (e-commerce that may or may not be part of the Open Finance participants). With our API, it is possible to initiate the open finance process conveniently and facilitate the payment of the end customer.

Attention!

Before activating the scopes of the Open Finance API, it is essential to read the Terms and Conditions of Use to understand how to use the API in the best way, without issues. Download the PDF available below or here.




To integrate the Open Finance API into your system or platform, you need to have an Efí Digital Account. Once you have access, you can obtain the necessary credentials and certificate for communication with the Open Finance API.

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

Security in credential management

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


Getting application credentials

An integrating person can create multiple applications as needed. For each application, two pairs of keys will be generated, Client_Id and Client_Secret, one for the Production environment (?) and the other for Sandbox (?).

To use the Efí Open Finance API, it is necessary to activate the necessary scopes in your application.

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. These scopes define the actions that an application can perform through the API.

Check below the available scopes in the Open Finance API, along with their permission descriptions:

  • gn.opb.participants.read - Get Open Finance participants;
  • gn.opb.payment.pix.send - initiate Pix via Open Finance;
  • gn.opb.payment.pix.read - list information of payments made;
  • gn.opb.payment.pix.refund - perform a payment refund;
  • gn.opb.payment.pix.cancel - cancel a scheduled payment;
  • gn.opb.config.write - write to the account's URL configuration;
  • gn.opb.config.read - read the account's URL configuration;

Create an Application or Configure an Existing One

See how to create a new application or use an existing application to integrate with the Efí Open Finance API.

To create an application and use the Open Finance API, follow these steps:

  1. Access your account and click on the "API" item at the bottom of the left-hand menu of the Efí account;
  2. Click on "Criar aplicação";
  3. Enable the Open Finance API and choose the scopes you want to release in Production and Sandbox environments (you can edit them in the future);
  4. With the selected scopes, click on "Continuar".
banner

Illustration of the steps to create a new application integrated with the Open Finance 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://openfinance.api.efipay.com.br
Sandboxhttps://openfinance-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.

EnvironmentRota base
Productionhttps://apis.gerencianet.com.br
Sandboxhttps://apis-h.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 Open Finance API


Setting Postman for tests

Before proceeding with Postman setup, make sure you have:

  1. A pair of Client_Id and Client_Secret credentials from an application registered in your Efí Account;
  2. A P12/PEM certificate generated in your Efí account;
  3. The Postman software installed on your computer (If you don't have it, download here);

1. Creating an Environment

Creating an Environment in Postman is necessary for some automations embedded in the collection to work. These automations are designed to make testing easier for developers.

This will allow you to request authorization only once, recording the access_token as an environment variable in Postman, available for use in other 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 be pointed to the Production or Sandbox environment;
  3. Create the variable efi-of-api and as the initial value, insert the URL of the Production or Sandbox Open Finance API;
  4. Save your Environment;
  5. Select the desired Environment so that Postman understands the created variable.

The images below show the illustrated steps above. In this example, an Environment was created for the Production environment of the Efí Open Finance API.

Tip

Repeat the above steps to create an Environment pointed to the Production environment. This way, you can easily switch between Environments, ensuring that your requests are always correctly directed.


banner

Creating a new environment

banner

Environment settings


2. Setting the certificate in Postman

All requests made to the Efí Open Finance 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.

Tip

It is ideal that you configure the certificate for the Sandbox environment, but you can also repeat the steps above to configure Postman with a certificate for the Production environment.


The images below illustrate the step-by-step configuration of the certificate.

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.opb.participants.read gn.opb.payment.pix.send gn.opb.payment.pix.read..."
}