Autenticação

Integrações de servidor usam uma API key secreta. O app do seller usa o token da sessão do usuário. As rotas do checkout hospedado são públicas e se protegem pelo segredo da sessão.

API keys

Envie a chave no cabeçalho Authorization de toda requisição:

Exemplo shell

curl -sS "https://api.v2.wolfpayteste.online/v1/orders" -H "Authorization: Bearer $WOLF_API_KEY"

Criação: no painel do seller, em API keys. Só uma sessão humana cria, lista ou revoga chaves — uma API key nunca gerencia outras chaves.
Formato: nesta edição toda chave é sk_test_.... Uma chave sk_live_ é recusada com 401: não existe dinheiro real no Wolf Sandbox.
Segredo exibido uma única vez. A Wolf guarda só o hash. Se perdeu o segredo, crie outra chave e revogue a antiga.
Validade: expires_at é opcional (no futuro e em até 365 dias). Chave vencida ou revogada responde 401 AUTHENTICATION_REQUIRED e aparece como expired/revoked na listagem.
Onde guardar: só no servidor (variável de ambiente ou cofre de segredos). Nunca em navegador, app móvel ou repositório.
Rotação: crie a chave nova, publique-a na sua aplicação e revogue a antiga.

Escopos

Cada rota exige um ou mais escopos (a referência lista os de cada operação). Sem o escopo a resposta é 403 FORBIDDEN. Conceda só o necessário.

Escopo	Permite
`payments:read`	Ler PaymentIntents, linha do tempo, reembolsos e disputas.
`payments:write`	Criar e confirmar PaymentIntents (também de pedidos) e usar o simulador.
`refunds:write`	Criar reembolsos (junto com `payments:read`).
`products:read`	Ler produtos.
`products:write`	Criar produtos e mudar o status (junto com `products:read`).
`offers:read`	Ler ofertas e Payment Links; criar sessões de checkout.
`offers:write`	Criar ofertas e Payment Links e mudar o status (junto com `offers:read`).
`orders:read`	Ler pedidos.
`orders:write`	Criar, cancelar e expirar pedidos.
`reports:read`	Ler o painel.
`finance:read`	Ler saldos, journals, repasses e liquidações sintéticos.
`webhooks:write`	Gerenciar endpoints de webhook, testar e reenviar entregas.
`api-keys:write`	Gerenciar API keys — só vale para sessão humana do app do seller.
`checkout.exports:create`	Checkout Builder (congelado, OPEN-009): indisponível nesta edição.
`checkout.exports:read`	Checkout Builder (congelado, OPEN-009): indisponível nesta edição.

Sessão do app do seller

O painel usa o token de sessão do usuário (Authorization: Bearer <JWT>). Um usuário com mais de uma organização envia wolf-organization-id; sem ele a API responde 409 TENANT_SELECTION_REQUIRED. Estas operações exigem sessão humana e recusam API keys:

get /v1/api-keys — Listar API keys
post /v1/api-keys — Criar API key
post /v1/api-keys/{id}/revoke — Revogar API key
get /v1/me/organizations — Listar minhas organizações
get /v1/organization/closure-request — Consultar pedido de encerramento
post /v1/organization/closure-request — Pedir o encerramento da organização
post /v1/organizations — Criar organização
patch /v1/organizations/current — Atualizar a organização atual
post /v1/payouts — Solicitar saque sintético
post /v1/webhooks/endpoints/{id}/rotate-secret — Rotacionar signing secret
Criar endpoint de webhook no modo live (POST /v1/webhooks/endpoints), porque revela o signing secret.

Rotas públicas do checkout

O checkout hospedado não usa API key. A leitura e o pagamento de uma sessão exigem o client_secret (csec_...) dela, que o checkout guarda em cookie httpOnly; abrir um Payment Link é público e limitado por IP.

get /v1/public/checkout-sessions/{id} — Ler sessão pública (polling)
post /v1/public/checkout-sessions/{id}/lead — Registrar os dados do comprador (etapa 1)
post /v1/public/checkout-sessions/{id}/pay — Pagar sessão de checkout
post /v1/public/checkout-sessions/{id}/pix/simulate-payment — Simular pagamento do Pix da sessão
post /v1/public/checkout-sessions/{id}/reconcile — Reconciliar pagamento da sessão
get /v1/public/payment-links/{id}/session — Abrir sessão de um Payment Link

Erros de autenticação

401 AUTHENTICATION_REQUIRED: sem credencial, credencial inválida, vencida ou revogada.
403 FORBIDDEN: credencial válida sem o escopo, ou operação que exige sessão humana.
409 TENANT_SELECTION_REQUIRED: sessão com várias organizações sem wolf-organization-id.

Um id de outro seller sempre responde 404 RESOURCE_NOT_FOUND: a organização vem da credencial, nunca da requisição.