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.

Create an application

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

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

Use an existing application

To use use an application already registered in your account and integrate it with the Open Finance API, follow these steps:

1. Access your Efí account and click on "API" in the bottom-left menu;
2. Select "Aplicações". Choose the application you want to edit, click on the three dots and select "Configurações";
3. Enable the Open Finance API and choose the scopes you want to release in Production and Sandbox environments (you can edit them whenever you want);
4. After selecting the desired scopes, click on "Continuar".

Steps to editing an application

Edits required for an application to access 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.

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

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

Creating a new environment

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.

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

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.

PHP

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

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 path to your .p12 certificate within your project
var certificado = fs.readFileSync("./certificado.p12");

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

const agent = new https.Agent({
  pfx: certificado,
  passphrase: "",
});
// Consumption in development of the POST oauth/token route
var config = {
  method: "POST",
  url: "https://pix.api.efipay.com.br/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);
});

Python

#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://pix.api.efipay.com.br/oauth/token"  #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,
                          cert=certificado)

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 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://pix.api.efipay.com.br/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);
    }
  }
}

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

certfile = File.read("certificado.pem") #  The certfile variable is the directory where your certificate in .pem format should be inserted

url = URI("https://pix.api.efipay.com.br/oauth/token") #For the Sandbox 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

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()));
  
    //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://pix.api.efipay.com.br/oauth/token"); //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://pix.api.efipay.com.br/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.opb.participants.read gn.opb.payment.pix.send gn.opb.payment.pix.read..."
}