Documentação
Última atualização: 21 de outubro de 2026
Como se conectar à API do VipPay e se identificar. As rotas de cobrança ainda estão em construção.
Cobranças, devoluções, lojistas e webhooks ainda não estão disponíveis. Esta página cobre a conexão e a autenticação, que já funcionam, e cresce junto com as rotas.
- 1. Conexão
- 2. Autenticação
- 3. Chaves e ambientes
- 4. Permissões
- 5. Limite de uso
- 6. Respostas de erro
- 7. O que vem a seguir
01Conexão
O endereço da API é https://api.vippay.com.br. Só aceita HTTPS.
Para conferir que a API está no ar, chame GET /health. Não precisa de chave.
curl https://api.vippay.com.br/health
{"status":"ok"}02Autenticação
Toda rota de negócio exige a chave no cabeçalho Authorization, no formato Bearer.
curl https://api.vippay.com.br/ROTA \
-H "Authorization: Bearer vp_live_SUA_CHAVE"Você nunca informa de qual conta é a chamada: a conta vem da chave. Uma chave só enxerga os dados da própria conta.
03Chaves e ambientes
- A chave começa com
vp_live_(produção) ouvp_test_(teste), seguida de 43 caracteres. - O ambiente vem da chave, não de um parâmetro da chamada. A chave de teste não mexe com dinheiro real.
- Cada conta pode ter várias chaves ativas por ambiente, cada uma com um nome, por exemplo uma por aplicação.
- A chave aparece uma única vez, na hora em que é criada. O VipPay guarda só uma impressão dela, não o texto: se perder, gere outra.
- A chave pode ter validade, se você escolher uma ao criá-la. Revogar vale na chamada seguinte.
Por enquanto o VipPay emite as chaves. Peça a sua em contato@vippay.com.br. A criação pelo painel está em construção.
04Permissões
Cada chave leva uma lista de permissões, no formato grupo:leitura ou grupo:escrita. Escrever não inclui ler: se a aplicação faz as duas coisas, a chave precisa das duas.
| Grupo | Para quê |
|---|---|
cobrancas | Criar e consultar cobranças. |
devolucoes | Pedir e consultar devoluções. |
lojistas | Cadastrar e consultar lojistas. |
webhooks | Configurar o aviso de pagamento. |
Uma chave tem ao menos uma permissão. Exemplo: cobrancas:leitura.
05Limite de uso
Cada chave pode fazer até 60 chamadas por minuto. O contador zera a cada minuto cheio. Passou disso, a API responde 429 com o cabeçalho Retry-After, que traz os segundos até o fim do minuto.
06Respostas de erro
As recusas voltam sem corpo. Vale o código de status.
| Código | Quando |
|---|---|
401 | Chave ausente, mal formada, inexistente, revogada ou vencida. A resposta é a mesma nos cinco casos. |
403 | A chave é válida, mas não tem a permissão que a rota exige. |
429 | Passou de 60 chamadas no minuto. Espere o tempo de Retry-After. |
503 | Não deu para conferir a chave agora. Tente de novo. Na dúvida, a API recusa e nunca libera. |
07O que vem a seguir
Ainda em construção, sem data:
- Cobranças por Pix, imediatas e com vencimento.
- Devoluções.
- Cadastro de lojistas.
- Webhook com o aviso de pagamento.
- Criação e revogação de chaves pelo painel.
O exemplo da página inicial mostra a forma pretendida de criar uma cobrança. O contrato final sai junto com as rotas, e esta página passa a descrevê-lo.