Skip to main content
A API aceita dois tipos de credencial no mesmo header. Para integrações, use a chave de API; o JWT é o que o painel usa.

​
Gerar uma chave de API

1

Faça login para obter um JWT

A resposta traz data.accessToken.
2

Crie a chave

environment é live (produção) ou test. Sem o campo, é produção — e chave de produção só existe para conta aprovada: antes da aprovação de produção, o pedido com live responde 409 com codigo: PRODUCAO_NAO_LIBERADA. Comece com uma chave de teste (Ambiente de testes).
O campo key aparece só nesta resposta. O V4 Pay guarda apenas um hash; depois disso ninguém — nem o suporte — consegue recuperar a chave. Se perder, crie outra.

​
Enviar a chave

Em todas as rotas protegidas, no header Authorization, com o prefixo Bearer:
O servidor reconhece a chave pelo prefixo v4pay_; qualquer outra coisa é tratada como JWT. O que vem depois — test_ ou live_ — é só leitura: o ambiente de verdade está gravado com a chave no servidor, e chaves antigas sem essa marca valem como produção.

​
Gerenciar chaves

Uma chave desativada ou revogada responde 401 com { "error": "Chave de API inválida ou revogada" }.

​
Erros de autenticação

Este é o único lugar da API onde error vem como string, não como objeto:

​
Boas práticas

  • Uma chave por integração, com um name que diga onde ela vive — facilita revogar só a certa.
  • Nunca coloque a chave em código de frontend nem em URL. Ela dá controle total da sua loja.
  • Guarde em variável de ambiente ou cofre de segredos.