Autenticação

Sua chave de API

As chaves da Verdin têm o prefixo vrd_live_ seguido de 48 caracteres hexadecimais. Ela identifica sua conta e concede somente os escopos escolhidos na criação — trate-a como uma senha.

Authorization: Bearer vrd_live_0123456789abcdef0123456789abcdef0123456789abcdef

Onde criar sua chave

Gere e gerencie suas chaves no painel, em Desenvolvedor. A chave crua é exibida uma única vez no momento da criação — copie e guarde num cofre de segredos. Se perder, revogue e gere uma nova.

Escopos disponíveis

Cada chave deve receber apenas as permissões necessárias para sua integração. Os escopos atuais são:

• balance:read — consultar saldo.
• charges:read — listar cobranças, detalhes e QR Code.
• charges:write — criar cobranças.

Exemplo de requisição

Um bom teste inicial é consultar o saldo da sua conta. Use curl ou fetch no Node:

curl https://api.verdinpay.com/api/v1/balance \
  -H "Authorization: Bearer vrd_live_0123456789abcdef0123456789abcdef0123456789abcdef"

const res = await fetch("https://api.verdinpay.com/api/v1/balance", {
  headers: {
    Authorization: `Bearer ${process.env.VERDIN_API_KEY}`,
  },
});

const balance = await res.json();
console.log(balance); // { available: 12990, currency: "BRL" }

Requisição não autenticada

Sem um Bearer válido, a API responde 401 com o código unauthorized:

{
  "error": {
    "code": "unauthorized",
    "message": "Chave de API inválida ou ausente."
  }
}

Uma chave válida sem o escopo exigido recebe 403 com o código insufficient_scope:

{
  "error": {
    "code": "insufficient_scope",
    "message": "Esta chave precisa do escopo charges:write para executar a operação"
  }
}

Boas práticas

• Guarde a chave em variáveis de ambiente (ex.: VERDIN_API_KEY), nunca no código-fonte.
• Use uma chave por ambiente e revogue chaves antigas ao rotacionar.
• Sempre chame a API a partir do backend — o front-end nunca deve ver a chave.
• Combine com a verificação de assinatura dos webhooks para confiar nos eventos recebidos.