Autenticação

Toda requisição à API da OrcaPay precisa ser autenticada com uma chave de API enviada no header X-Api-Key.

Obtendo sua chave

As chaves são geradas no console da OrcaPay, na seção de Chaves de API. Ao criar uma chave você define:

• Nome — identificação da chave (único por estabelecimento).
• Escopos — quais operações a chave pode executar (ao menos um é obrigatório).
• Expiração — data opcional a partir da qual a chave deixa de funcionar.

As chaves têm o prefixo op_live_ e o valor completo é exibido uma única vez, no momento da criação. Guarde-o em local seguro — a OrcaPay armazena apenas um hash da chave e não é possível recuperá-la depois.

Usando a chave

Envie a chave no header X-Api-Key:

curl https://api.orcapay.com.br/payments \
  -H "X-Api-Key: op_live_..." \
  -H "Content-Type: application/json"

Requisições sem chave, com chave inválida, revogada ou expirada retornam 401 Unauthorized.

A chave identifica o seu estabelecimento: não envie nenhum header adicional de identificação (como ID do estabelecimento) — a OrcaPay resolve tudo a partir da chave, e headers de identidade enviados pelo cliente são ignorados por segurança. A única exceção é o establishmentId usado pelo SDK de criptografia de cartão, que aparece na URL da chave pública e você encontra no console.

Escopos

Cada chave carrega um conjunto de escopos que limita o que ela pode fazer:

Escopo	Permite
payments:pix	Criar pagamentos Pix
payments:card	Criar pagamentos com cartão
payments:read	Consultar e listar pagamentos
payments:cancel	Cancelar pagamentos
payments:refund	Estornar pagamentos
payments:link	Criar e gerenciar links de pagamento

Uma requisição feita com chave sem o escopo necessário retorna 403 Forbidden com código FORBIDDEN.

Revogação e expiração

• Chaves podem ser revogadas a qualquer momento pelo console, com registro do motivo. A revogação é imediata e irreversível.
• Chaves com data de expiração são desativadas automaticamente após essa data.
• Cada uso da chave é registrado (endpoint, método e IP de origem), permitindo auditoria pelo console.

Boas práticas de segurança

• Nunca exponha sua chave em código front-end, repositórios ou logs.
• Armazene a chave em variáveis de ambiente ou em um cofre de segredos.
• Crie chaves com o menor conjunto de escopos necessário para cada integração.
• Se uma chave vazar, revogue-a imediatamente pelo console e gere uma nova.