Autenticação da API

A API de pagamentos não usa OAuth, JWT nem um cabeçalho Bearer tradicional. A autenticação é feita através de um parâmetro chamado code, que identifica de forma única sua conta e a carteira Liquid associada a ela. Esse código deve ser enviado em todas as requisições:

• Em requisições GET, como parâmetro na query string (?code=SEU_CODIGO).
• Em requisições POST, como campo no corpo JSON da requisição.

Não existe, portanto, um cabeçalho Authorization obrigatório nas chamadas que você faz para a API de pagamentos — o próprio valor de code é a credencial que autentica e identifica a origem da chamada.

O código de integração é gerado na seção de configurações do seu painel de conta, depois que sua conta é aprovada pela equipe de compliance. Não é necessário nenhum fluxo adicional de emissão de token: o mesmo código continua válido até que você o revogue ou solicite sua troca via suporte.

• Nunca inclua o código em JavaScript executado no navegador do usuário final ou em aplicativos mobile distribuídos publicamente.
• Faça as chamadas à API sempre a partir do seu backend, nunca diretamente do cliente.
• Não versione o código em repositórios públicos — use variáveis de ambiente ou um cofre de segredos.
• Se suspeitar que o código foi exposto, solicite sua substituição ao suporte imediatamente.

Quando você habilita o modo de webhook genérico em uma cobrança (informando uma URL de callback), a plataforma envia uma notificação HTTP POST para essa URL assim que o pagamento é confirmado. Essa chamada de saída é autenticada com o cabeçalho:

O mesmo esquema de autenticação (Basic) é usado nos endpoints internos que recebem notificações do provedor de pagamento. Antes de confiar no conteúdo de qualquer chamada recebida no seu endpoint de callback e executar uma ação sensível (como liberar um produto), seu listener deve validar esse cabeçalho Authorization contra o token combinado com a plataforma — chamadas sem o cabeçalho correto devem ser rejeitadas com 401 Unauthorized. O formato do cabeçalho segue o esquema padrão descrito na RFC 7617 (The 'Basic' HTTP Authentication Scheme).

O formato exato do esquema de segurança (basicAuth) está declarado na especificação OpenAPI, na seção securitySchemes da referência Swagger. Para o passo a passo completo de implementação de um endpoint de webhook (validação, resposta rápida, idempotência), veja o artigo Webhooks e notificações em tempo real.

O ambiente de sandbox usa exatamente o mesmo mecanismo de autenticação (parâmetro code e, para webhooks, Authorization: Basic), porém com endpoints e credenciais próprias de teste, isoladas de produção. Consulte a especificação em /sandbox/api-docs.