Credentials, Certificate and Authorization

On this page, you'll find information about credentials, certificates and authorization for the Pix API.

The Efí's Pix API offers advanced resources for integrating with your application, allowing you to create custom solutions and offer innovative payment options to your customers. With our API, you can create charges, check received Pix payments, refund, and send Pix payments.

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

See below how to obtain credentials, certificates, and details about the authorization and security of 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 done securely. We suggest implementing two-factor authentication and other security practices.

Getting application credentials

An integrator can create as many applications as he wants. For each application, 2 pairs of keys Client_Id and Client_Secret are generated, one pair for use in Production environment (?) and another for Sandbox environment (?).

Using the Efí's Pix API, the integrator can generate Pix transactions (payments and receipts), configure Webhooks for receiving notifications via callbacks, and access the exclusive features of the Efí Digital Account. To do this, it's necessary to activate the necessary scopes in your application.

Understanding application's scopes

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

The available scopes in the Efí's Pix API are listed below with their respective permission descriptions:

• cob.write - Create Immediate Charge;
• cob.read - Get Charge;
• pix.write - Refund request;
• pix.read - Get Pix;
• pix.send - Request for Pix sending;
• gn.pix.send.read - Get Pix sent through;
• webhook.write - Setting Pix Webhook;
• webhook.read - Get webhook information;
• payloadlocation.write - Create payload location;
• payloadlocation.read - Get registered locations;
• gn.pix.evp.write - Create EVP Key;
• gn.pix.evp.read - List EVP Keys;
• gn.balance.read - Get Account Balance;
• gn.settings.write - Create/modify account settings;
• gn.settings.read - List account settings;
• gn.reports.write - Request Reconciliation Statement;
• gn.reports.read - Request Download Reconciliation Statement;
• cobv.write - Create Due Charge;
• cobv.read - Get Due Charge;
• gn.split.read - Get Payment Split Configuration;
• gn.split.write - Payment Split Configuration;
• lotecobv.read - Create/Update batch of due charges;
• lotecobv.write - GET batch of due charges;
• gn.infractions.write - Submitting a defense for a MED infraction;
• gn.infractions.read - List account MED infractions;
• gn.qrcodes.pay - Pay QR Code Pix;
• gn.receipts.read - Get Receipts;
• rec.read - Get Automatic Pix recurrence;
• rec.write - Create Automatic Pix recurrence;
• solicrec.read - Get Automatic Pix recurrence Confirmation Request;
• solicrec.write - Create Automatic Pix recurrence Confirmation Request;
• cobr.read - Get Automatic Pix charge;
• cobr.write - Create Automatic Pix charge;
• payloadlocationrec.read - Get registered Automatic Pix recurrence locations;
• payloadlocationrec.write - Create Automatic Pix recurrence payload location;
• webhookrec.read - Get Automatic Pix recurrence webhook information;
• webhookrec.write - Setting Automatic Pix recurrence webhook;
• webhookcobr.read - Get Automatic Pix charge webhook information;
• webhookcobr.write - Setting Automatic Pix charge Webhook;

Create an application or configure an existing one

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

Create an application

To create an application for using the Pix API, follow the steps below:

1. Access your account and click on the "API" item at the bottom of the left menu of the Efí account;
2. Click on "Criar aplicação";
3. Enable the Pix 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 "Continuar".

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

Use an existing application

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

1. Access your account and click on the "API" item at the bottom of the left menu of the Efí account;
2. Click on "Aplicações". Then, choose the application to be edited, click on the three dots and select "Configurações";
3. Enable the Pix API and choose the scopes you want to release in Production and Sandbox environments (you can edit them whenever you want);
4. With the selected scopes, click "Continuar".

Steps until editing an application

Edits necessary for an application's access to the Pix API

Generating a P12 Certificate

All requests must contain a security certificate provided by Efí within your account, in the format PFX (.p12). This requirement is fully described in the PIX Security Manual.

Attention!

The certificate download is done immediately after its creation. It will not be possible to download the same certificate at another time, so store it securely on your computer.

To generate your certificate, simply follow the steps below:

1. Access the "API" item in the bottom left menu of the Efí account;
2. In the left menu, click on "My Certificates";
3. In the new window, select the environment to which the certificate will belong (Production or Sandbox);
4. Click on "New Certificate" (blue button);
5. Assign a description to the certificate to identify it in the future;
6. Confirm the certificate creation;
7. Finally, download the certificate and click continue.

The steps for creating a certificate are illustrated in the image below.

Steps to create the certificate

Window for creating the certificate

Download window for the generated certificate

It is worth noting that the same certificate can be used by several applications in your digital account. Still, you can generate up to five certificates for each environment (Production or Sandbox).

Conversion of P12 certificate to PEM format

Information

In some languages, keys need to be converted to the .pem format. Use the information in this section only if this is the case.

If you need to convert the certificate using a Windows operating system, you can use our converter available on GitHub.

To generate your certificate with this converter, simply follow the steps below:

1. Clone or download the converter from the GitHub repository;
2. Make sure the .p12 file is in the same directory as the script;
3. Run the conversor_p12_para_pem.bat file;
4. If the .p12 file is password protected, the script will prompt you to enter the certificate password. If you do not enter a password, the script will consider it an empty password "";
5. The script will convert the .p12 file to .pem in the same directory, and the generated .pem file will have the same name as the .p12 file, with the .pem extension.

If you need to separate the Private Key from your certificate, after conversion, the script will ask if you want to separate the private key into a separate file. Answer "Y" or "y" for yes.

Thus, the private key will be exported to a separate file with the same name as the .p12 file, but with the _key.pem extension.

Caution!

It is important to note that you can use a single certificate for multiple applications in your digital account. However, you have the option to generate up to five certificates for each environment, whether it is Production or Sandbox.

Certificate Conversion with OpenSSL

It is also possible to convert the certificate using the OpenSSL command to perform this format conversion between keys:

Shell

 # Generate certificate and key in a single file
openssl pkcs12 -in certificado.p12 -out certificado.pem -nodes -password pass:""

If it is necessary to separate the private key from the certificate during the conversion, use the command below, also with OpenSSL:

Shell

# Generate separate certificate and key
openssl pkcs12 -in path.p12 -out newfile.crt.pem -clcerts -nokeys -password pass:"" #certificate
openssl pkcs12 -in path.p12 -out newfile.key.pem -nocerts -nodes -password pass:"" #private key

Information

The certificate conversion process may request the certificate password. If this occurs, provide empty.

Base Routes

In this documentation, you will notice references to Base Routes or URLs for Production or Sandbox environments. These routes are actually the URL where the Efí Pix API is located. Thus, when referring to endpoints, it is implicit that these URL segments also compose the final route of the desired resource.

Use the routes below to communicate your application with the production and Sandbox environments offered by Efí.

Environment	Base Route
Production	https://pix.api.efipay.com.br
Sandbox	https://pix-h.api.efipay.com.br

Authorization with OAuth2

The permission mechanism for requests made to the Efí Pix API is compatible with the OAuth2 protocol. This means that it follows a set of rules and standards to authorize requests made to the API.

The Purpose of OAuth2

To authorize all calls made to the API, it is necessary to obtain an access token (access_token). This token is used to verify if a particular application has permission to use the requested endpoint in the API.

How Request Authentication Is Done

Authentication is performed using HTTP Basic Auth, which requires the Client_Id and Client_Secret of the application you created in your Efí account. With this authentication, OAuth can provide information about the permissions granted to the application, allowing authorization or denial of requests based on this information.

Attention!

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

Accept-Encoding Header Configuration

It may be necessary to set the Accept-Encoding header depending on the need to obtain the size of the Response Body before processing:

• Accept-Encoding: gzip - If it is not necessary to check the size of the Response Body before processing it:
• Response Body < 1000 bytes: no compression will be applied, and Content-Length will be returned.
• Response Body >= 1000 bytes: compression will be applied, the Transfer-Encoding: chunked header will be returned, and Content-Length will not be included.
• Accept-Encoding: * or Accept-Encoding: identity - If it is necessary to check the size of the Response Body before processing it:
• Response Body of any size: Content-Length will be returned.

Postman Collection for Pix API

This is the link to our Collection that we will keep updated with the endpoints of the Efí Pix API.

Setting Postman for tests

Tip

The use of Postman software is optional. The next few paragraphs explain how to configure it. If you don't want to use Postman for testing, you can move on to the next topic Obtaining Authorization.

Before proceeding with the Postman setup, you should have:

1. A pair of credentials called Client_Id and Client_Secret from an application that you registered in your Efí Account;
2. A P12/PEM certificate that you generated as shown in the previous steps;
3. The Postman software installed on your computer. If you don't have it, you can download it here.

1. Creating an Environment

Creating an Environment in Postman is necessary for some built-in automations in the collection to work. These automations were developed to facilitate testing for developers.

With these automations, you only need to request authorization once, and the access_token will be stored as an environment variable in Postman, ready to be used in subsequent requests.

To create an Environment, follow these steps:

1. Press Ctrl+N and, when the shortcut opens, choose "Environment";
2. Assign a name preferably specifying whether this Environment will be pointed to the Production or Sandbox environment;
3. Create the variable efi-pix-api and as the initial value, enter the URL of the Production or Sandbox Pix API;
4. Save your Environment;
5. Select the desired Environment so that Postman recognizes the created variable.

In the example below, an Environment pointed to the Sandbox environment of the Pix API was created.

Tip

Repeat the above steps to create an Environment pointed to the Production environment. This way, you can simply switch between Environments, and your requests will already be correctly pointed.

Creating a new environment

Environment settings

2. Setting the certificate in Postman

All requests made to the Efí Pix API require the certificate generated in your Efí account. Therefore, to facilitate your testing 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. Next, click on "Add Certificate";
5. In the new certificate configuration window, fill in the "Host" field with the base URL of the environment to which the certificate belongs (Production or Sandbox);
6. Use the "PFX File" field to indicate to Postman where your .p12 certificate file is located. Pay attention to the file format; here, the .p12 certificate should be used;
7. Finally, click "Add" to save your settings.

By following these steps, Postman will use the certificate for any requests made to the configured environment host.

Tip

It is ideal that you configure the certificate for the Sandbox environment, but you can also repeat the above steps 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 configure Postman correctly, you need to add the credentials of your application from the Efí account. These credentials are used for Basic Auth and to obtain the access_token using OAuth.

Follow the steps below to include the credentials and perform your first test on the Pix API:

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

After these steps, a JSON response will be displayed, containing the access_token, token_type, expires_in, and scope (as in the image below).

Using application credentials for request authorization

Obtaining Authorization

POST /oauth/token

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.

Attention!

It is necessary to include the P12/PEM certificate in the authorization request so that the API server can establish a secure connection.

Examples of Authorization using the .P12 certificate

To use Pix, it's necessary for the client and the server to communicate through a verified connection. This verification is done by the bidirectional certificate (.PEM or .P12), where both the server and the client have a private key and a public key to ensure each other's identity.

Therefore, to make any HTTP request to the Pix API, including the OAuth2 authorization request, it's necessary for the .P12 or .PEM certificate to be present in the request headers.

Below are examples of how to perform authorization in the Pix API Efí, 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

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

Response

{
   "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
   "token_type": "Bearer",
   "expires_in": 3600,
   "scope": "cob.read cob.write pix.read pix.write"
}

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
token_type	Type of authorization the access_token should be used with. Default: "Bearer"	string
expires_in	Expiration time of the access_token in seconds. Default: 3600	Integer (int32)
scope	List of scopes that the authorized application has access to. Scopes are separated by space.	string