Skip to main content

Autenticação

A autenticação da API de Chargeback do PicPay é realizada utilizando o protocolo OAuth 2.0, especificamente o Grant Type “client_credentials”, para garantir uma forma segura de conceder acesso a recursos protegidos. Este fluxo de autenticação é ideal para cenários de autenticação entre sistemas (server-to-server), sem a necessidade de interação com usuários finais.

OAuth 2.0​

O OAuth 2.0 é um protocolo padrão para autorização que permite que sistemas concedam acesso controlado a APIs sem expor as credenciais do usuário. Esse protocolo garante a segurança no processo de autenticação e na autorização de acesso a dados sensíveis. Para mais informações sobre o protocolo OAuth 2.0, consulte a RFC 6749.

Fluxo de Autorização com Grant Type client_credentials​

O grant type client_credentials é utilizado para autenticação entre sistemas, onde um backend do estabelecimento realiza a autenticação com a API, sem a necessidade de interação com o usuário final. Este método é adequado para integrações automatizadas com a API de Chargeback do PicPay.

Para detalhes adicionais sobre o grant type client_credentials, consulte a seção correspondente na RFC 6749.

Etapas para autenticação​

Para acessar os serviços protegidos pela API de Chargeback do PicPay, siga as etapas abaixo para obter um token de acesso:

  1. Solicitação de Credenciais:
    Acessar o Painel do Lojista, no menu Integrações e gerar as credenciais específicas necessárias para a integração com a API de Chargeback do PicPay em cada ambiente:
  • Ambiente Produtivo: Selecionar o filtro Contestações e gerar ou renovar as credenciais no box ContestaçõesTela do Painel do Lojista mostrando credenciais de contestações em produção
  • Ambiente Sandbox: Selecionar o filtro Credenciais de teste e gerar ou renovar as credenciais no box ContestaçõesTela do Painel do Lojista mostrando credenciais de contestações no ambiente sandbox
  1. Solicitação do Token de Acesso:
    Após a obtenção das credenciais, faça uma requisição ao servidor de autorização para obter o token de acesso.
  2. Autenticação com Token:
    Utilize o token de acesso obtido (access_token) como Bearer Token nas requisições subsequentes à API para autenticação.

Solicitação do Token de Acesso​

Após receber as credenciais, você poderá solicitar o token de acesso fazendo uma requisição ao servidor de autorização. A seguir, o exemplo de como realizar essa requisição:

  • Endpoint de Autorização:
    Produção: https://acquirer-platform.svc.picpay.com/oauth2/token
    Sandbox: https://acquirer-platform.svc.ppay.me/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 ao solicitar as credenciais.

Exemplo de Requisição para Obtenção do Token de Acesso:

curl -X 'POST' \
  'https://acquirer-platform.svc.picpay.com/oauth2/token' \
--header 'Content-Type: application/json' \
--header 'Cookie: AWSALBAPP-0=_remove_; AWSALBAPP-1=_remove_; AWSALBAPP-2=_remove_; AWSALBAPP-3=_remove_' \
--data '{
    "grant_type": "client_credentials",
    "client_id": "e650d65c-3734-4e1b-a970-a46d1eae2963",
    "client_secret": "Dsh4FlZTtNlniRI7lWYcLkCEJRzaL8vU"
}'

Exemplo de retorno da requisição de autenticação

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOi",
    "expires_in": 300,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 1619744579,
    "scope": "credential.client_secret.rotate chargeback",
    "seller-acquirer-id": "0000000001",
    "authorization_details": [
        {
            "type": "authorized_account",
            "account_id": "10bfb021-09d4-4001-9036-a88d12345",
            "fingerprint": "d923165d-2886-49b9-80b5-f3f2633b7cfe",
            "display_name": "PicPay"
        }
    ]
}

Considerações Importantes​

  1. Requisição Server-to-Server: A requisição de autenticação deve ser feita a partir de um sistema backend, nunca do lado do cliente, para evitar exposição de credenciais sensíveis.
  2. Tempo de Expiração do Token: Os tokens de acesso obtidos por meio do fluxo client_credentials têm validade de 5 minutos. Após esse período, um novo token deverá ser gerado com as mesmas credenciais para continuar realizando requisições à API.
  3. Concorrência na Obtenção de Tokens: Durante a obtenção ou renovação de tokens de acesso, é importante considerar a possibilidade de concorrência. A RFC 6749. recomenda o uso de mecanismos de controle de concorrência para evitar a criação de tokens duplicados. Além disso, deve-se garantir o uso eficiente de armazenamento e cache para minimizar a necessidade de requisições redundantes de tokens.

Para garantir a integridade e segurança do processo, siga as melhores práticas para gerenciamento de tokens e controle de concorrência.