Tipos de chave e scopes

Os scopes são escolhidos na criação da chave (no painel). Se omitidos, aplica-se o default do tipo — o mesmo conjunto que já valia antes de os scopes serem selecionáveis, então chaves emitidas antes desta mudança continuam funcionando sem alteração.

Tipo	Scopes permitidos	Default quando omitido
PUBLIC	CREATE_PIX_TRANSACTION	CREATE_PIX_TRANSACTION
SECRET	todos os scopes	READ_BALANCE, CREATE_WITHDRAW, CREATE_REFUND

Catálogo completo de scopes:

Scope	Permite
CREATE_PIX_TRANSACTION	Criar cobranças PIX e consultar status
READ_BALANCE	Consultar saldo
CREATE_WITHDRAW	Solicitar saque
READ_WITHDRAWS	Consultar e listar saques
CREATE_REFUND	Criar reembolso
READ_ORDERS	Listar e consultar pedidos
READ_TRANSACTIONS	Listar transações
READ_PRODUCTS	Ler catálogo de produtos
WRITE_PRODUCTS	Criar e atualizar produtos
READ_COUPONS	Ler cupons
WRITE_COUPONS	Criar, atualizar e remover cupons

Cuidado

Chaves PUBLIC aceitam apenas CREATE_PIX_TRANSACTION. Scopes de leitura de dados de cliente (PII) e qualquer escrita são SECRET-only — a API rejeita a criação com 400 caso contrário.

Use a PUBLIC key apenas para criar cobranças (pode ficar no lado do cliente/checkout). Use a SECRET key apenas server-to-server (saldo, saque, reembolso, e as leituras/escritas abaixo).

A chave crua é exibida uma única vez, no momento da criação no painel — guarde-a com segurança, pois não é recuperável depois.

Toda rota da API de integração exige um scope — não há rota que aceite qualquer chave apenas por ela ser do tipo certo. A tabela da visão geral dos endpoints indica, na coluna Extra, qual scope cada rota exige. Chamar uma rota sem o scope correspondente retorna 403.