Skip to main content

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 - charge modification;
  • cob.read - Get charge;
  • pix.write - Pix modification;
  • pix.read - Get Pix;
  • pix.send - Request for Pix sending;
  • webhook.write - webhook modification;
  • webhook.read - Get webhook;
  • payloadlocation.write - create payload location;
  • payloadlocation.read - Permission to query locations;
  • gn.pix.send.read - Get sent Pix;
  • gn.pix.evp.write - create/remove evp key;
  • gn.pix.evp.read - list evp key;
  • gn.balance.read - check account balance;
  • gn.settings.write - create/modify account settings;
  • gn.settings.read - list account settings;

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.

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

Illustration of steps for create a new application integrated with 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.

banner

Steps to create the certificate

banner

Window for creating the certificate

banner

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:

     # 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:

    # 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í.

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

    The following routes are still available to communicate your application, but will be discontinued soon. We suggest that you use the routes mentioned earlier.

    EnvironmentBase Route
    Productionhttps://api-pix.gerencianet.com.br
    Sandboxhttps://api-pix-h.gerencianet.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.


    Postman Collection for 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.


    banner

    Creating a new environment

    banner

    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.

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

    banner

    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:

    // 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

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

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

    AttributeDescriptionType
    access_tokenAuthorization token to be used in other requests made to the API.string
    token_typeType of authorization the access_token should be used with.
    Default: "Bearer"
    string
    expires_inExpiration time of the access_token in seconds.
    Default: 3600
    Integer (int32)
    scopeList of scopes that the authorized application has access to. Scopes are separated by space.string