Pular para o conteúdo principal

Credenciais, Certificado e Autorização

Nesta página você encontra informações sobre credenciais, certificado e autorização da API Pix.


A API Pix Efí oferece recursos avançados para integração com sua aplicação, permitindo que você crie soluções personalizadas e ofereça opções de pagamento inovadoras aos seus clientes. Com nossa API é possível criar cobranças, verificar os Pix recebidos, devolver e enviar Pix.

Para integrar a API Pix Efí ao seu sistema ou sua plataforma, é necessário ter uma Conta Digital Efí. Uma vez com acesso, você poderá obter as credenciais e o certificado necessários para a comunicação com a API Pix Efí.

Veja a seguir como obter as credenciais, certificados e detalhes sobre a autorização e segurança da sua integração com a Efí.

Segurança no gerenciamento de credenciais

Dentro dos sistemas integrados à nossa API, é importante que as operações de login e a alteração das chaves de integração sejam realizadas com segurança. Sugerimos a implementação de autenticação de dois fatores e outras práticas de segurança.


Obtendo as credenciais da aplicação

Um integrador pode criar quantas aplicações desejar. Para cada aplicação são gerados 2 pares de chaves Client_Id e Client_Secret, sendo um par para utilização em ambiente de Produção (?) e outro para Homologação (?).

Utilizando a API Pix Efí, o integrador pode gerar transações Pix (pagamentos e recebimentos), configurar Webhooks para o recebimento de notificações via callbacks e acessar as funcionalidades exclusivas da Conta Digital Efí. Para isso, é necessário ativar os escopos necessários em sua aplicação.

Entendendo os escopos de aplicação

Ao criar ou editar uma aplicação em sua Conta Efí, você precisará configurar os escopos que a aplicação terá acesso. A escolha desses escopos define quais ações uma aplicação estará autorizada a realizar via API.

Os escopos disponíveis na API Pix Efí estão listados abaixo com suas respectivas descrições de permissão:

  • cob.write - alteração de cobranças;
  • cob.read - consulta de cobranças;
  • pix.write - alteração de Pix;
  • pix.read - consulta de Pix;
  • pix.send - requisitar envio de Pix;
  • webhook.write - alteração do webhook;
  • webhook.read - consulta do webhook;
  • payloadlocation.write - criar location do payload;
  • payloadlocation.read - Permissão para consulta de locations;
  • gn.pix.send.read - consultar Pix enviados;
  • gn.pix.evp.write - criar/remover chave evp;
  • gn.pix.evp.read - listar chave evp;
  • gn.balance.read - buscar saldo da conta;
  • gn.settings.write - criar/modificar configurações da conta;
  • gn.settings.read - listar configurações da conta;

Criar uma aplicação ou configurar uma já existente

Veja como criar uma aplicação ou aproveitar uma aplicação já existente para integrar com a API Pix Efí.

Para criar uma aplicação para utilização da API Pix siga os passos abaixo:

  1. Acesse sua conta e clique no item "API" na parte inferior do menu à esquerda da conta Efí;
  2. Clique em "Criar aplicação"
  3. Habilite a API Pix e escolha os escopos que deseja liberar em ambiente de Produção e Homologação (você pode editá-los no futuro);
  4. Com os escopos selecionados, clique em "Continuar".
banner

Ilustração dos passos para a criação de uma nova aplicação integrada à API Pix


Gerando um certificado P12

Todas as requisições devem conter um certificado de segurança que será fornecido pela Efí dentro da sua conta, no formato PFX(.p12). Essa exigência está descrita na íntegra no manual de segurança do PIX.

Atenção!

O download do certificado é feito imediatamente após a sua criação. Não será possível realizar o download do mesmo certificado em outro momento, por isso, armazene-o em local seguro em seu computador.


Para gerar o seu certificado, basta seguir os passos abaixo:

  1. Acesse o item "API" no menu inferior a esquerda da conta Efí;
  2. No menu à esquerda, clique em "Meus Certificados";
  3. Na nova janela selecione o ambiente ao qual pertencerá o certificado (Produção ou Homologação)
  4. Clique em "Novo Certificado" (botão azul);
  5. Atribua uma descrição ao certificado para identificá-lo no futuro;
  6. Confirme a criação do certificado;
  7. Por fim, baixe o certificado e clique em prosseguir.

Os passos para a criação de um certificado estão ilustrados na imagem a seguir.

banner

Passos para a criação do certificado

banner

Janela para a criação do certificado

banner

Janela de download do certificado gerado

Vale ressaltar que um mesmo certificado pode ser usado por diversas aplicações da sua conta digital. Ainda assim, você pode gerar até cinco certificados para cada ambiente (Produção ou Homologação).


Conversão de certificado P12 para o formato PEM

Informação

Em algumas linguagens as chaves precisarão ser convertidas para o formato .pem. Utilize as informações desta seção apenas se esse for o seu caso.


Caso precise converter o certificado utilizando um sistema operacional Windows, você pode utilizar o nosso conversor disponível no GitHub.

Para gerar o seu certificado com este conversor, basta seguir os passos abaixo:

  1. Clone ou baixe o conversor pelo repositório no GitHub.;
  2. Certifique-se de que o arquivo .p12 esteja no mesmo diretório que o script;
  3. Execute o arquivo conversor_p12_para_pem.bat;
  4. Se o arquivo .p12 estiver protegido por senha, o script solicitará que você insira a senha do certificado. Se você não inserir uma senha, o script considerará uma senha vazia "".
  5. O script irá converter o arquivo .p12 para .pem no mesmo diretório e o arquivo .pem gerado terá o mesmo nome do arquivo .p12, com a extensão .pem.

  • Caso precise de separar a chave Privada do seu certificado, após a conversão, o script perguntará se você deseja separar a chave privada em um arquivo separado. Responda "S" ou "s" para sim.
  • Assim a chave privada será exportada para um arquivo separado com o mesmo nome do arquivo .p12, mas com a extensão _key.pem.

    Atenção!

    É importante destacar que você pode usar um único certificado para várias aplicações na sua conta digital. No entanto, você tem a opção de gerar até cinco certificados para cada ambiente, seja ele de Produção ou Homologação.


    Conversão de certificado com OpenSSL

    É possível também converter o certificado utilizando o comando o OpenSSL para realizar essa conversão de formato entre as chaves:

     # Gerar certificado e chave em único arquivo
    openssl pkcs12 -in certificado.p12 -out certificado.pem -nodes -password pass:""

    Se for necessário separar a chave privada do certificado durante a conversão, use o comando abaixo, também com o OpenSSL:

    # Gerar certificado e chave separadas
    openssl pkcs12 -in path.p12 -out newfile.crt.pem -clcerts -nokeys -password pass:"" #certificado
    openssl pkcs12 -in path.p12 -out newfile.key.pem -nocerts -nodes -password pass:"" #chave privada

    Informação

    O processo de conversão do certificado pode pedir a senha do certificado. Se isso ocorrer, informe vazio.


    Rotas base

    Nesta documentação você perceberá referências à Rotas base ou URL's base para ambientes de Produção ou Homologação. Essas rotas são, na verdade, a URL na qual a API Pix Efí se encontra. Assim, quando nos referirmos aos endpoints, fica implícito que esses trechos de URL também compõem a rota final do recurso desejado.

    Utilize as rotas abaixo para realizar a comunicação da sua aplicação com os ambientes de produção e homologação oferecidos pela Efí.

    AmbienteRota base
    Produçãohttps://pix.api.efipay.com.br
    Homologaçãohttps://pix-h.api.efipay.com.br

    Autorização com OAuth2

    O mecanismo de permissão das solicitações feitas à API Pix Efí é compatível com o protocolo OAuth2. Isso significa que ele segue um conjunto de regras e padrões para autorizar as requisições feitas à API.

    O objetivo do OAuth2

    Para autorizar todas as chamadas feitas à API, é necessário obter um token de acesso (access_token). Esse token é usado para verificar se uma determinada aplicação tem permissão para utilizar o endpoint solicitado na API.

    Como é feita a autenticação das requisições

    A autenticação é realizada usando HTTP Basic Auth, que requer o Client_Id e Client_Secret da aplicação que você criou na sua conta Efí. Com essa autenticação, o OAuth pode fornecer as informações sobre as permissões concedidas à aplicação, permitindo autorizar ou negar as solicitações com base nessa informação.

    Atenção!

    O Certificado P12/PEM gerado nos passos anteriores é obrigatório em todas as requisições feitas à API Pix, inclusive na requisição de autorização.


    Collection Postman API PIX


    Configurando o Postman para testes

    Dica

    O uso do software Postman é opcional. Os próximos parágrafos explicam como configurá-lo. Caso não deseje usar o Postman para testes, você pode avançar para o tópico Obter Autorização.


    Antes de prosseguir com a configuração do Postman, você deverá ter:

    1. Um par de credenciais chamado Client_Id e Client_Secret de uma aplicação que você cadastrou na sua Conta Efí;
    2. Um certificado P12/PEM que você gerou conforme mostrado nos passos anteriores;
    3. O software Postman instalado no seu computador. Caso não o tenha, você pode baixá-lo aqui.

    1. Criando um Environment

    A criação de um Environment no Postman é necessária para que algumas automações embutidas na collection funcionem. Essas automações foram desenvolvidas fecilitar os testes para os desenvolvedores.

    Com essas automações, você só precisa solicitar autorização uma vez e o access_token será armazenado como uma variável de ambiente (environment) no Postman, pronto para ser utilizado nas próximas requisições.

    Para criar um Environment, siga os seguinte passos:

    1. Pressione Ctrl+N e, ao abrir o atalho, escolha "Environment";
    2. Atribua um nome preferencialmente especificando se esse Environment será apontado para o ambiente de Produção ou Homologação;
    3. Crie a variável efi-pix-api e como valor inicial (Initial value) insira a URL da API Pix de Produção ou Homologação;
    4. Salve o seu Environment;
    5. Selecione o Environment desejado para que o Postman reconheça a variável criada.

    No exemplo a seguir, foi criado um Environment apontado para o ambiente de Homologação da API Pix.

    Dica

    Repita os passos acima para dessa vez ter um Environment apontado para o ambiente de Produção. Assim você poderá simplesmente alternar entre os Environments e suas requisições já estarão apontadas corretamente.


    banner

    Criando um novo environment

    banner

    Configurações do environment


    2. Configurando o certificado no Postman

    Todas as requisições feitas à API Pix Efí precisam do certificado gerado em sua conta Efí. Portanto, para facilitar seus testes utilizando o Postman, siga os passos a seguir para configurar o uso do certificado durante as requisições de maneira automática:

    1. Clique no ícone de engrenagem no canto superior direito do Postman;
    2. Depois, clique em "Settings" para abrir as configurações;
    3. Na aba superior, clique em "Certificates";
    4. Em seguida, clique em "Add Certificate";
    5. Na janela de configuração do novo certificado, preencha o campo "Host" com a Rota base do ambiente ao qual o certificado pertence (Produção ou Homologação);
    6. Utilize o campo "PFX File" para indicar ao Postman onde está localizado o arquivo do seu certificado .p12. Fique atento ao formato do arquivo, aqui deve ser usado o certificado em .p12;
    7. Finalize clicando em "Add" para salvar suas configurações.

    Seguindo esses passos, o Postman usará o certificado para quaisquer requisições feitas ao Host do ambiente configurado.

    Dica

    É ideal que você configure o certificado do ambiente de homologação, mas você também pode repetir os passos acima para configurar o Postman com um certificado para o ambiente de Produção.


    As imagens abaixo ilustram o passo a passo da configuração do certificado.

    banner

    Acessando as configurações do Postman

    banner

    Adicionando um novo certificado no Postman

    banner

    Configurações do certificado


    3. Atribuindo o Client_Id e Client_Secret no Postman

    Para configurar o Postman corretamente, você precisa adicionar as credenciais da sua aplicação da conta Efí. Essas credenciais são usadas para o Basic Auth e para obter o access_token usando o OAuth.

    Siga os passos a seguir para incluir as credenciais e realizar o seu primeiro teste na API Pix:

    1. Na collection importada, localize a rota /oauth/token e clique duas vezes para abri-la;
    2. Acesse o menu "Authorization" e verifique se o "Type" (tipo de autorização) está selecionado como "Basic Auth";
    3. Nos campos "username" e "password" preencha com as credenciais da sua aplicação, Client_Id e Client_Secret, respectivamente;
    4. Para testar, clique no botão "Send" para enviar a requisição

    Após esses passos, uma resposta em formato JSON será exibida, contendo o access_token, token_type, expires_in e scope (como na imagem abaixo).

    banner

    Uso das credenciais de uma aplicação para autorização de requisições


    Obter Autorização

    POST /oauth/token

    O endpoint POST /oauth/token é usado para autorizar as credenciais de uma aplicação e obter os acessos necessários para utilizar os outros recursos da API.

    Atenção!

    É necessário incluir o certificado P12/PEM na requisição de autorização para que o servidor da API crie uma conexão segura.



    Exemplos de autorização utilizando o certificado .P12

    Para a utilização do Pix, é necessário que o cliente e o servidor se comuniquem através de uma conexão verificada. Essa verificação é feita pelo certificado bidirecional (.PEM ou .P12), onde tanto o servidor quanto o cliente possuem uma chave privada e uma chave pública para garantir a identidade um do outro.

    Portanto, para fazer qualquer requisição HTTP à API Pix, incluindo a solicitação de autorização pelo OAuth2, é necessário que o certificado .P12 ou .PEM esteja presente nos cabeçalhos da requisição.

    A seguir, apresentamos exemplos de como realizar a autorização na API Pix Efí, incorporando esse certificado na requisição:

    //Desenvolvido pela Consultoria Técnica da 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", // Rota base, homologação ou produção
    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"], // Caminho do certificado
    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>";
    ?>

    Exemplo de resposta da autorização

    A seguir, o trecho de código representa um exemplo de resposta do OAuth à sua requisição de autorização:

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

    A tabela abaixo descreve os atributos presentes no JSON retornado.

    AtributoDescriçãoTipo
    access_tokenToken de autorização a ser usado nas outras requisições feitas à API.string
    token_typeTipo de autorização na qual o access_token deve ser usado
    Padrão: "Bearer"
    string
    expires_inTempo de expiração do access_token em segundos.
    Padrão 3600
    Integer (int32)
    scopeLista de escopos aos quais a aplicação autorizada possui acesso. Os escopos estão separados por espaço.string