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.

Create an application

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".

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

Use an existing application

To use an application already registered in your account and use it for integration with the Billings API, follow the steps below:

1. Access your account and click on the "API" item in the left menu;
2. Click on "Aplicações" and choose the application you want to edit. Then, click on the three dots and select "Configurações".
3. Enable the Billings API and choose the scope to release the Production/Sandbox environments;
4. With the selected scope, click on "Continuar".

Steps to edit an application

Edits required for an application's access to 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:

Environment	Base Route
Production	https://cobrancas.api.efipay.com.br
Sandbox	https://cobrancas-h.api.efipay.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

This is the link to our Collection, which we will keep updated with the endpoints of the Efí 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.

Creating a new environment

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).

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:

PHP

// 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>";
?>

Node

// Developed by the Technical Consulting Team at Efí

"use strict";
const https = require("https");
var axios = require("axios");
var fs = require("fs");

// Insert the values of your Pix development 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");

// Consumption in development of the POST oauth/token route
var config = {
  method: "POST",
  url: "https://cobrancas-h.api.efipay.com.br/v1/authorize",
  headers: {
    Authorization: "Basic " + auth,
    "Content-Type": "application/json",
  },
  data: data,
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

#Developed by the Technical Consulting Team at Efí

import requests
import base64

credentials = {
  "client_id": "YOUR-CLIENT-ID",
  "client_secret": "YOUR-CLIENT-SECRET",
}

auth = base64.b64encode(
  (f"{credentials['client_id']}:{credentials['client_secret']}"
   ).encode()).decode()

url = "https://cobrancas-h.api.efipay.com.br/v1/authorize"  #For the Sandbox 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)

print(response.text)

.Net

// Developed by the Technical Consulting Team at Efí

using System;
using System.Security.Cryptography.X509Certificates;
using System.Collections.Generic;
using RestSharp;

namespace Exemplos
{
  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://cobrancas-h.api.efipay.com.br/v1/authorize");
      var request = new RestRequest(Method.POST);

      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);
    }
  }
}

Ruby

#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";

url = URI("https://cobrancas-h.api.efipay.com.br/v1/authorize") #For the Sandbox environment 

https = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

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

Java

// 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()));
      
    URL url = new URL ("https://cobrancas-h.api.efipay.com.br/v1/authorize"); //For the Sandbox 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();
  }
}

Go

// 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://cobrancas-h.api.efipay.com.br/v1/authorize"// Base route, Sandbox or production
  method := "POST"

  payload := strings.NewReader(`{"grant_type": "client_credentials"}`)

  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

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

Response

{
   "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.

Attribute	Description	Type
access_token	Authorization token to be used in other requests made to the API.	string
refresh_token	Authorization token that will be used to update an expired access token.	string
expires_in	Type of authorization the access_token in seconds. Default 600	Integer (int32)
expire_at	Expiration time of access_token in Timestamp ISO 8601	string
token_type	Type of authorization the access_token should be used with. Default: "Bearer"	string