Autenticação

Todas as requisições à API ActivePayments devem ser autenticadas usando API Keys. Este guia explica como gerar e usar suas credenciais.

API Keys

A autenticação é feita através de um par de chaves:

Public Key (ActivePayments_pk_xxx): Identificador público da sua conta. Pode ser exposto em logs sem comprometer a segurança.
Secret Key (ActivePayments_sk_xxx): Chave secreta que deve ser mantida em segurança. Nunca exponha em código frontend ou repositórios públicos.

Como Autenticar

Envie suas credenciais no header Authorization no seguinte formato:

Formato do Header

Authorization: ApiKey {public_key}:{secret}

Exemplo prático

cURL
curl -X POST https://api.ActivePayments.com.br/api/v1/charges \
  -H "Authorization: ApiKey ActivePayments_pk_abc123:ActivePayments_sk_xyz789" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100, "customerName": "João", "customerCpf": "12345678901"}'

Gerando suas API Keys

Acesse o Dashboard

Faça login em sua conta e navegue até Configurações → API Keys.

Crie uma nova key

Clique em "Nova API Key" e defina um nome descritivo como "Produção" ou "Integração E-commerce".

Salve o Secret

O secret será exibido apenas uma vez. Guarde-o em um local seguro como um gerenciador de senhas ou variável de ambiente.

ImportanteSe você perder o secret, precisará gerar uma nova API Key. A key anterior pode ser revogada sem afetar suas transações.

Permissões (Scopes)

Ao criar uma API Key, você pode definir as permissões específicas:

Scope	Descrição
`payments:read`	Consultar cobranças e transações
`payments:write`	Criar novas cobranças PIX
`balance:read`	Consultar saldo da conta
`webhooks:manage`	Gerenciar endpoints de webhook

Lista de IPs Permitidos

Para maior segurança, você pode restringir o uso da API Key a IPs específicos. Configure isso em Configurações → Regras de Segurança, por API Key. Os IPs são exigidos nos saques; sem IP fixo, use o Saque via Secret (header x-withdrawal-secret) — veja Autorização do saque.

DicaEm produção, recomendamos sempre configurar IPs permitidos para evitar uso não autorizado caso suas credenciais sejam comprometidas.

Erros de Autenticação

A API retorna os seguintes erros relacionados à autenticação:

Código HTTP	Mensagem	Causa
`401`	API Key inválida	Public key não existe
`401`	Secret inválido	Secret não corresponde à key
`401`	API Key desativada	Key foi revogada
`401`	API Key expirada	Key passou da data de expiração
`401`	IP não autorizado	IP não está na whitelist

Limites de Requisições (Rate Limit)

Para garantir a estabilidade da API, aplicamos limites de requisições:

Recurso	Limite	Janela
`API Geral`	100 requisições	Por minuto
`POST /charges`	30 requisições	Por minuto
`GET /balance`	60 requisições	Por minuto

Rate Limit ExcedidoAo exceder o limite, você receberá um erro 429 Too Many Requests. Aguarde o tempo indicado no header Retry-After antes de tentar novamente.

Proteção de Dados (LGPD)

A API ActivePayments processa dados pessoais como CPF e nome do cliente. Você, como integrador, deve garantir conformidade com a Lei Geral de Proteção de Dados (LGPD):

Consentimento: Obtenha consentimento do cliente para enviar seus dados ao ActivePayments
Finalidade: Use os dados apenas para processamento de pagamentos
Minimização: Envie apenas os dados estritamente necessários
Armazenamento: Não armazene dados sensíveis desnecessariamente

Nosso CompromissoO ActivePayments armazena dados de forma criptografada e segue as diretrizes da LGPD. Para mais informações, consulte nossa Política de Privacidade.

Boas Práticas de Segurança

Nunca exponha o secret no frontend - Use apenas em seu servidor backend.
Use variáveis de ambiente - Não hardcode credenciais no código.
Rotacione keys periodicamente - Gere novas keys a cada 6-12 meses.
Configure IP whitelist - Restrinja o acesso aos IPs do seu servidor.
Use keys diferentes por ambiente - Separe produção, staging e desenvolvimento.
Monitore uso - Verifique regularmente o histórico de uso das suas API Keys.

Próximo passoAprenda a Criar uma Cobrança PIX.