Pular para o conteúdo principal

Autenticação

Bem-vindo à documentação do fluxo de autenticação da API de Checkout do PicPay. Nesta página, explicaremos como autenticar e acessar nossos serviços utilizando o fluxo de autenticação OAuth 2.0 com o grant type client_credentials.

OAuth 2.0​

A autenticação da nossa API é baseada no protocolo OAuth 2.0. Esse protocolo fornece uma maneira segura de conceder acesso a recursos protegidos em nome de um cliente. Para obter mais informações sobre o OAuth 2.0, consulte a RFC 6749.

Fluxo de Autorização com Grant Type client_credentials​

O grant type client_credentials é uma variante do fluxo OAuth 2.0. Ele foi escolhido como o método de autorização para proteger nossa API. Esse grant type é ideal para cenários em que a autenticação ocorre entre sistemas, sem envolver usuários finais. Para entender mais sobre o grant type client_credentials, consulte a seção correspondente na RFC 6749.

Etapas​

Para acessar nossos serviços protegidos, é necessário obter um token de acesso seguindo as seguintes etapas:

  1. Gere as credenciais no Painel Lojista.
  2. Realize a solicitação de autorização para obter um token de acesso e autenticar suas requisições.
  3. Utilize o token de acesso como um Bearer Token nas chamadas à API para autenticação.

Obtendo as Credenciais​

As credenciais são compostas por um client_id e um client_secret. O client_id é um identificador único para o cliente e o client_secret é uma chave secreta que deve ser tratada com cuidado para evitar acesso não autorizado. Siga os passos abaixo para obter suas credenciais:

  1. Acesse o Painel Lojista e faça o login;
  2. Navegue até a seção de Integrações no menu lateral;
  3. Clique no botão "Gerar Token" da integração Checkout;
  4. Guarde com segurança o client_id e o client_secret que aparecem na tela.
Cuidado!

Este é o único momento em que o PicPay exibirá o campo client_secret. Portanto, é importante anotar essas credenciais em um local seguro antes de fechar a tela com as informações. Posteriormente, você poderá consultar essas credenciais na mesma aba, no entanto, apenas o campo client_id será exibido para fins de identificação das credenciais.

Atenção!

Caso já exista uma credencial gerada para a integração selecionada e você gere uma nova, a credencial anterior desta integração será revogada após um prazo de 7 dias.

Obtendo o Token de Acesso​

Após obter suas credenciais, você poderá solicitar um token de acesso para autenticar suas requisições à nossa API. Para isso basta fazer uma requisição ao nosso servidor de autorização passando as credenciais adquiridas no passo anterior.

  • Endpoint de Autorização: https://checkout-api.picpay.com/oauth2/token
  • Parâmetros de Requisição:
  • grant_type: Define o fluxo de concessão da autorização. Terá sempre o valor client_credentials;
  • client_id e client_secret: Obtidos na etapa anterior.

Segue um exemplo da requisição do Token de Acesso:

curl -X 'POST' \
'https://checkout-api.picpay.com/oauth2/token' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    "grant_type": "client_credentials",
    "client_id": "66b64c55-6ab9-4894-b2b0-4772472f4f72",
    "client_secret": "n9CmYbIavNTadlYFCxBVbF2345ROPgzM4"
}'

Para mais detalhes sobre a requisição do Token de Acesso vide a sessão Auth da nossa API Reference.

De Servidor para Servidor!

Essa requisição deve ser feita obrigatoriamente a partir de um sistema backend para o nosso sistema. Essa abordagem evita expor as credenciais de autenticação ao cliente final.

Tempo de Expiração

Os tokens de acesso obtidos através desse fluxo têm uma validade de apenas 5 minutos. Após esse período, será necessário gerar um novo token, com as mesmas credenciais para continuar utilizando a API.

Concorrência​

Ao utilizar o fluxo OAuth 2.0 para autenticação e autorização de acesso à nossa API, é importante considerar os desafios relacionados à concorrência durante o processo de obtenção e renovação dos tokens de acesso.

A RFC 6749 aborda alguns aspectos relevantes em relação à concorrência. Ela destaca que, durante a obtenção do token de acesso, uma solicitação simultânea de um mesmo cliente pode resultar na criação de tokens duplicados. Da mesma forma, a renovação simultânea de tokens também pode levar a problemas de concorrência.

Para lidar adequadamente com a concorrência, recomendamos seguir as melhores práticas citadas pela RFC 6749. Além disso, é importante considerar as seguintes diretrizes:

  • Utilize mecanismos de controle de concorrência em seu sistema para evitar que múltiplas solicitações criem ou renovem o mesmo token de acesso simultaneamente.
  • Implemente estratégias de armazenamento e gerenciamento de tokens que sejam eficientes e evitem conflitos durante o processo de obtenção e renovação.
  • Utilize mecanismos adequados de armazenamento em cache para minimizar as solicitações de token.

Lembramos que é responsabilidade do cliente garantir a implementação adequada de mecanismos de controle de concorrência durante o uso do fluxo OAuth 2.0. Ao seguir essas diretrizes, você ajudará a manter a consistência, segurança e integridade das operações realizadas em nossa API.

Se você tiver alguma dúvida adicional ou precisar de suporte técnico, nossa equipe estará pronta para ajudar. Entre em contato conosco através dos canais disponíveis no Portal de Suporte.