Skip to main content

Credentials and Authorization

On this page, you will find information about credentials and authorization for the Efí Billing API.


The Efí Billing API offers advanced features that allow you to issue different types of charges, such as Boleto, Credit Card, Payment Booklet, Payment Links, Subscriptions (Recurring), and Marketplace (Payment Split).

To integrate the Efí Billing API into your system or platform, you need to have an Efí Digital Account. After accessing the account, you can obtain the necessary credentials to establish communication with the Efí Billing API.

Below, you will find how to obtain the credentials and details about the authorization and security of your integration with Efí.

Credential Management Security

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


Getting application credentials

To obtain application credentials, the integrator can create as many applications as desired. Each application is associated with 2 pairs of keys: Client_Id and Client_Secret, with one pair intended for the Production environment (?) and the other for the Sandbox environment (?). It is essential to activate the scope in your application to use the Efí Billing API.

Create an application or configure an existing one

See how to create an application or leverage an existing one to integrate with the Efí Billings API.

To create an application and use the Billings API, follow the steps below:

  1. Access your Efí account and click on "API" in the left menu;
  2. Click on "Criar aplicação";
  3. Enable the Billings API and choose the scope to release the Production/Sandbox environments;
  4. With the selected scope, click on "Continuar".
banner

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

Base Routes

In this documentation, you will find references to the Base Routes or Base URLs for Production or Sandbox environments. These routes represent the address of the Efí Billings API. When we mention endpoints, these URL parts are also part of the path to access the desired resource.

To communicate your application with the Efí production and Sandbox environments, use the following routes:

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

The following routes are still available for your application's communication, but they will be discontinued soon. We recommend using the previously mentioned routes.

EnvironmentBase Route
Productionhttps://api.gerencianet.com.br
Sandboxhttps://sandbox.gerencianet.com.br

Authentication with OAuth2

The authentication process for the Billings API follows the OAuth2 protocol. Requests are authenticated using HTTP Basic Auth.

Postman Collection for Billings API


Configuring Postman for Tests

Tip

The use of Postman software is optional. Below, we will explain how to configure it. If you do not wish to use Postman for tests, you can skip to the topic: Obtaining Authorization.


Before proceeding with the Postman configuration, make sure you have:

  1. A pair of Client_Id and Client_Secret credentials from an application registered in your Efí Account;
  2. The Postman software installed on your computer (If you do not have it, download it here);

1. Creating an Environment

Creating an Environment in Postman is necessary for some embedded 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, saving the access_token as a Postman environment variable, available for use in other subsequent requests.

To create an Environment, follow these steps:

  1. Press Ctrl+N and select "Environment";
  2. Assign a name, preferably specifying whether this Environment will point to the Production or Testing environment;
  3. Create the variable efi-cob-api and as the initial value (Initial value), enter the URL of the Production or Testing Invoices API;
  4. Save your Environment;
  5. Select the desired Environment so Postman recognizes the created variable.

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

banner

Creating a new environment


banner

Environment settings


2. 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 to obtain the access_token through OAuth.

Follow the steps below to include the credentials and perform your first test on the Invoices API.

  1. In the imported collection, go to the /v1/authorize route and double-click to open it;
  2. Access the "Authorization" menu and make sure 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 submit the request.

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

banner

Using application credentials for request authorization


Obtaining Authorization

POST /v1/authorize

The endpoint POST /oauth/token is used to authorize the credentials of an application and obtain the necessary accesses to use other resources of the API.

Examples of Authorization

Below are examples of how to perform authorization in the Billings API:

// Developed by the Technical Consulting Team at Efí
<?php
$config = [
"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://cobrancas-h.api.efipay.com.br/v1/authorize',
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_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

Below is a code snippet representing an example of the OAuth response to your authorization request:

{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MTYyOTY2NTYsImV4cCI6MTcxNjI5NzI1NiwiZGF0YSI6eyJrZXlfaWQiOjUyOTU2MSwidHlwZSI6ImFjY2Vzc1Rva2VuIn19._d22EAjlsmuCKxTCtYDMd2ZVK04fS7xWNWSjE-JWEpc",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MTYyOTY2NTYsImV4cCI6MTcxNjI5Nzg1NiwiZGF0YSI6eyJrZXlfaWQiOjUyOTU2MSwidHlwZSI6InJlZnJlc2hUb2tlbiJ9fQ.4txXqR4g5FMQvCU3jL8LnrQ002xfEAK1EwKaJjlyCOU",
"expires_in": 600,
"expire_at": "1690986856033",
"token_type": "Bearer"
}

The table below describes the attributes present in the returned JSON.

AttributeDescriptionType
access_tokenAuthorization token to be used in other requests made to the API.string
refresh_tokenAuthorization token that will be used to update an expired access token.string
expires_inType of authorization the access_token in seconds.
Default 600
Integer (int32)
expire_atExpiration time of access_token in Timestamp ISO 8601string
token_typeType of authorization the access_token should be used with.
Default: "Bearer"
string