Pular para o conteúdo principal

Autenticação

Bem-vindo à documentação do fluxo de autenticação do One-Click PicPay. Nesta página, explicaremos como autenticar e acessar nossos serviços.

info

A solução de PicPay One-Click não está disponível para todos os nossos lojistas. Se interessou? Basta entrar em contato através do e-mail pic.premium@atendimento.picpay.com demonstrando interesse.

Obtenção do client_id e client_secret#

Após o registro do aplicativo, o PicPay compartilhará com o e-commerce as credenciais de acesso, na forma de um client_id e client_secret.

Um pouco mais sobre o client_id#

O client ID é uma sequência exposta publicamente usada pela API de serviço para identificar o aplicativo e também para criar URLs de autorização que são apresentadas aos usuários.

Um pouco mais sobre o client_secret#

O client secret é usado para autenticar a identidade do aplicativo na API de serviço quando o aplicativo solicita o acesso à conta de um usuário e deve ser mantido privado entre o aplicativo e a API.

Como funciona?#

O fluxo básico de autenticação e autorização consiste na geração de um código após o usuário digitar seu login/senha em uma interface do PicPay.

Com o código gerado, o e-commerce deve gerar um token que será utilizado em toda comunicação server to server com o PicPay. Este token possibilitará que o usuário efetue as seguintes operações (dependendo do escopo configurado):

  • Processar pagamentos;
  • Reembolsar pagamentos;
  • Obter informações do usuário;

Redirecionando usuário para o aplicativo PicPay#

Inicialmente, seu e-commerce deverá redirecionar seus clientes para o aplicativo do PicPay. Para isso, seu e-commerce deverá gerar a URL, que deverá conter seu client_id e url de redirecionamento. Exemplo:

img

Breve explicação sobre os parâmetros da URL acima:

  • client_id: Identificador da aplicação fornecido pelo PicPay;
  • redirect_uri: URL de redirecionamento para onde o serviço redireciona o agente do usuário após a concessão de um código de autorização.
  • response_type: Deve ser igual a code, especificando que seu aplicativo está solicitando uma concessão de código de autorização
  • state: Sequência de caracteres utilizada para associar a sessão do serviço consumidor a um identificador de sessão, ajudando a prevenir ataques de repetição. Pode ser um valor aleatório, desde que não seja fácil de deduzir. Embora não obrigatório, é recomendado o uso desse recurso.

Solicitando a autorização do usuário#

Ao utilizar a URL do passo anterior, o cliente será redirecionado para o aplicativo do PicPay, para realizar a biometria e realizar o fluxo de consentimento da conexão.

Atenção

O cliente poderá conceder ou não as permissões. Sua aplicação deverá estar preparado para receber os dois tipos de resposta.

Após o consentimento inicial, o PicPay não solicitará novamente as permissões ao cliente.

Obtendo o código de autorização#

Caso o cliente autorize o aplicativo no passo anterior, o usuário será redirecionado para a URL de retorno indicada.

O código de autorização será enviado como um parâmetro junto a URL indicada e deverá ser utilizado para a geração dos tokens no passo seguinte.

img

Solicitação dos tokens#

Para realizar as solicitações de pagamento, reembolso ou consulta de informações, o e-commerce deverá informar um token válido como um dos parâmetros do header de cada requisição.

Para tanto, o e-commerce deverá solicitar um access token com o código de autorização obtido e o client_id e o client_secret.

Exemplo de requisição de token:

curl -X POST \
https://api.picpay.com/oneclick/oauth2/token \
-H "Content-Type='application/x-www-form-urlencoded'" \
-d "grant_type=authorization_code" \
-d "client_id=CLIENT_ID" \
-d "code=AUTHORIZATION_CODE"

Caso esteja tudo certo, enviaremos o token como no exemplo abaixo:

{
"access_token": "ACCESS_TOKEN",
"expires_in": 300, // tempo em segundos
"refresh_expires_in": 1800,
"refresh_token": "REFRESH_TOKEN",
"token_type": "bearer",
"id_token": "ID_TOKEN",
"not-before-policy": 1585954424,
"session_state": "fa158d89-9228-45c6-8486-e159f28b5bd5",
"scope": "openid email profile"
}
Tempo de expiração de um token

O tempo de expiração do token será exibido em segundos. Após a expiração o token deverá ser atualizado através do refresh_token.

A duração dos tokens poderá ser configurada na criação e configuração das credenciais pelo PicPay.

Atualização dos tokens#

Após um período predeterminado, o access_token concedido à aplicação irá expirar, sendo necessária a solicitação de um novo access_token. Para isso, utiliza-se um refresh_token, gerado na mesma solicitação do access_token (ver Autenticação e Autorização). Abaixo um exemplo de requisição:

curl -X POST \
https://api.picpay.com/oauth2/token \
-H "Content-Type='application/x-www-form-urlencoded'" \
-d "grant_type=refresh_token" \
-d "client_id=CLIENT_ID" \
-d "client_secret=CLIENT_SECRET" \
-d "refresh_token=REFRESH_TOKEN"
Fluxo de atualização de tokens

O fluxo de atualização de tokens precisa ser obrigatoriamente previsto em sua aplicação dado que o refresh_token irá expirar em algum momento.