Uma API de pagamento precisa saber quem pede cada cobrança e cada saque. Usuário e senha servem para pessoas. Para sistemas, a credencial é a chave de API, enviada em toda requisição.
Na API da xFlow
As credenciais são criadas no painel, em Desenvolvedores > Chaves de API. Cada uma tem duas partes:
| Parte | Prefixo | Visibilidade |
|---|---|---|
| Chave pública | pk_live_ |
Sempre visível no painel. |
| Segredo | sk_live_ |
Exibido uma única vez, na criação. |
A autenticação é HTTP Basic: a chave pública vai como usuário e o segredo como senha. Para integrar sem dinheiro real, crie uma chave no ambiente Teste, com os prefixos pk_test_ e sk_test_. Ela usa os mesmos endpoints, toda resposta traz livemode: false, e dá para criá-la antes da aprovação do cadastro. O passo a passo está em API Pix sandbox.
Como proteger
- Só no servidor. O segredo não vai para o navegador, para o app nem para um repositório versionado. Use variáveis de ambiente ou um cofre de segredos.
- Revogue ao primeiro sinal. A revogação no painel é imediata. Crie uma credencial nova e troque no servidor.
- Restrinja por IP. Com a allowlist de IP configurada no painel, chamadas de fora da lista recebem
401, mesmo com a credencial certa. - Separe teste e produção. Variáveis diferentes para cada ambiente evitam cobrar de verdade durante os testes.
O segredo da chave de API não é o segredo que assina os webhooks. Cada endpoint de webhook tem o seu, usado no HMAC. As demais camadas estão na página de segurança.
Exemplo
const cred = Buffer.from(
process.env.XFLOW_PUBLIC_KEY + ":" + process.env.XFLOW_SECRET_KEY
).toString("base64");
const res = await fetch("https://app.xflowpayments.com/api/v1/balance", {
headers: { Authorization: "Basic " + cred },
});Com a credencial ausente, inválida ou revogada, a resposta é 401 unauthorized. Os outros erros estão em erros da API Pix.
Termos relacionados
- HMAC: a assinatura dos webhooks, com um segredo à parte.
- API REST: o modelo em que cada chamada se autentica sozinha.
- Rate limit: o limite de chamadas de cada conta.