Autenticação e autorização
Sobre este guia#
Neste guia vamos descrever o passo-a-passo para que você obtenha um token de acesso para processar pagamentos online com o PicPay através de nossa solução de pagamentos logada.
Antes de começar#
Registro do aplicativo#
Antes de iniciar sua integração, você deve possuir credenciais válidas. Para este produto, o processo de criação de credenciais pode ser realizado pelo Painel Logista. Saiba mais sobre como gerenciar suas credenciais.
info
A solução de PicPay 1-Click não está disponível para todos os nossos lojistas. Se interessou? Basta entrar em contato através do e-mail negocios@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 tela de login e senha#
Inicialmente, seu e-commerce deverá redirecionar seus clientes para a página de login e senha do PicPay. Para isso, seu e-commerce deverá gerar a URL, que deverá conter seu client_id e url de redirecionamento. Exemplo:
Breve explicação sobre os parametros 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 acode, especificando que seu aplicativo está solicitando uma concessão de código de autorizaçãostate: 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 uma página de login e senha ou aplicativo do PicPay, dependendo do tipo de fluxo que for escolhido pelo painel logista. Seu cliente deverá então efetuar o login através de seu usuário e senha do PicPay.
Após o login, o cliente deverá revisar as permissões solicitadas pelo aplicativo.
Informação
As permissões solicitadas irão depender das configurações de escopo setadas no momento da criação das credenciais.
Atenção
O cliente poderá conceder ou não as permissões. Sua aplicação deverá estar preparada para receber os dois tipos de resposta.
Após o concentimento 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.
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 no passo 3 e o client_id e o client_secret.
Exemplo de requisição de token:
Caso esteja tudo certo, enviaremos o token como no exemplo abaixo:
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 pre-determinado, 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:
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. Caso o token não seja atualizado o usuário deverá fazer login e senha novamente.
Próximos passos#
Com um access_token válido, seu aplicativo poderá efetuar cobranças, reembolsos ou consultar algumas informações básicas dos usuários. Confira abaixo os próximos passos:
Obtendo ajuda#
Esperamos ter ajudado com este artigo! Caso tenha restado alguma dúvida, você pode consultar o nosso FAQ ou entrar em contato através do e-mail negocios@atendimento.picpay.com.