Todos os endpoints disponibilizados pela API da Geopagos requerem autenticação para fim de validação das permissões de visualização e edição do usuário. Adicionalmente, todo usuário da API é associado a uma Company. Na descrição dos endpoints, quando houver referências à "company autenticada", isso se refere à company com a qual o usuário autenticado na requisição é associado.
A autenticação para o teste dos endpoints nesta documentação é realizada da seguinte forma:
- O campo "username" deve ser preenchido com
"jwt"ou"hash_key", de acordo com o tipo de chave de autenticação utilizada. - O campo "password" deve ser preenchido com a chave de autenticação.
Quando outros clientes HTTPS forem usados, a autenticação deve ser realizada pelo esquema HTTPS Basic, ou seja: Deve ser definido um header chamado Authorization na requisição, cujo valor deve ser a codificação em Base64 da concatenação do valor "username" conforme definido acima, seguido de um caractere dois-pointos (:), seguido da chave de autenticação.
Por exemplo:
Dada a "hash_key" hash_1234, o valor do header de autenticação na mensagem deve ser base64("hash_key:hash_1234"). O valor codificado dessa string é "aGFzaF9rZXk6aGFzaF8xMjM0". Assim, deve ser enviado o header Authorization: Basic aGFzaF9rZXk6aGFzaF8xMjM0 nas requisições realizadas via cliente HTTPS.
"jwt" versus "hash_key": qual usar?
O JWT deve ser utilizado por humanos. Isto é, usuários que se autenticam com username e password. Esta forma de autenticação vincula o usuário ao seu contexto na company, trazendo então uma camada de permissionamento.
Já a hash_key deve ser utilizada por não-humanos. Ou seja, APIs e outros serviços devem utilizá-la, já que a hash_key não vincula um usuário ao seu contexto de autenticação; ela está vinculada estritamente à company que realiza a requisição.
Caso você deva utilizar a hash_key e ainda não tenha uma, entre em contato conosco para que fornecê-la de forma segura.
Atenção ao utilizar a hash_key
A hash_key é um chave estática e que permite realizar uma série de operações em nome do PSP ou do estabelecimento ao qual ela pertence. Assim, é de extrema importância que a mesma seja armazenada de forma segura, e que de maneira alguma ela seja exposta, por exemplo, em aplicações no frontend.
A hash_key é uma forma válida de autenticação, mas não a retornamos nos nossos endpoints.