Chaves de API e escopos

Cada chave é de uma empresa e de um ambiente, e tem um nível de acesso por recurso. A chave completa aparece uma única vez; a plataforma guarda só o hash.

Formato e envio

A chave começa com sk_test_ (ambiente de teste) ou sk_live_ (produção), seguida de 43 caracteres. Mande em toda chamada no cabeçalho Authorization: Bearer sk_…; o cabeçalho X-API-Key: sk_… também é aceito.

Para conferir uma chave sem mexer em nada, chame GET /v1/account: não exige escopo e mostra a empresa, o ambiente e os escopos.

Chave só no servidor. Nunca no navegador, no app do celular nem no git.

Criar, vencer e revogar

  • No painel, em Desenvolvedores › Chaves de API. Quem cria: Proprietário, Administrador ou Desenvolvedor, com o código do app autenticador.
  • A chave de produção só é criada depois que o cadastro da empresa é aprovado.
  • Validade de 90 dias, 365 dias ou sem vencimento, escolhida na criação.
  • Até 20 chaves ativas por ambiente.
  • Escopos e lista de IPs não mudam depois de criada: para mudar, crie outra chave, troque no seu servidor e revogue a antiga (revogar também pede o código do app autenticador).
  • Perdeu a chave? Ela não aparece de novo: revogue e crie outra.

Escopos

Cada recurso tem um nível: none, read ou write. write inclui read. Chave criada antes de um recurso existir fica com none nele: ela não ganha acesso novo sozinha.

Escopos por recurso
RecursoO que cobrereadwrite
chargesCobranças, devoluções e links de pagamentoGET /v1/charges, /v1/refunds e /v1/payment-linksCriar e cancelar cobrança, devolver, criar e alterar link
payoutsPagamentos e destinosGET /v1/payouts, /v1/beneficiaries e /v1/settlement-accountsPedir e cancelar pagamento, salvar e arquivar beneficiário
balanceSaldosGET /v1/balancesNenhuma rota de escrita
disputesDisputas (MED)GET /v1/disputes e /v1/charges/:id/disputesEvidência, defesa e explicação
webhooksEventos dos webhooksGET /v1/events e /v1/events/:idNenhuma rota de escrita (endpoints só no painel)
customersClientesGET /v1/customers e /v1/customers/:idNenhuma rota de escrita

O cadastro de endpoints de webhook continua só no painel: pela API, o escopo webhooks lê os eventos já emitidos.

Erros de autenticação

Códigos de erro
CódigoHTTPQuando acontece
API_KEY_INVALID401Chave ausente, fora do formato, desconhecida, revogada ou vencida.
API_KEY_SCOPE403A chave não tem o nível pedido pela rota no recurso.
IP_NOT_ALLOWED403A chave tem lista de IPs e a chamada veio de outro.
MERCHANT_NOT_ACTIVE403Chave sk_live_ de empresa que ainda não está ativa. Use o ambiente de teste.
MERCHANT_SUSPENDED403A empresa está suspensa: a API recusa as chamadas.
MERCHANT_BLOCKED403A empresa está bloqueada: a API recusa as chamadas.
RATE_LIMITED429Mais de 1.200 chamadas por minuto com a mesma chave.

Lista de IPs em Lista de IPs.