Autenticação
A API da PagusPay usa autenticação Bearer JWT. Toda requisição a um
endpoint /v1/* exige um token válido no cabeçalho Authorization.
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.paguspay.com/api/v1/balances
O token codifica organizationId, userId e scopes — a organização de
uma requisição vem sempre do token, nunca de outro estado.
Criando uma API key
Tokens de API são criados pelo painel, não pela API:
- Faça login no painel da PagusPay
- Vá em Configurações → API
- Clique em Criar API Key, selecione os scopes necessários e confirme
O valor completo do token é exibido apenas no momento da criação. Copie
imediatamente e guarde em local seguro (gerenciador de secrets, arquivo
.env) — ele não pode ser recuperado depois. Se perder, revogue e crie um
novo.
Scopes
Cada token é emitido com um ou mais scopes. Requisições são rejeitadas com
403 se os scopes do token não cobrirem o endpoint chamado.
| Scope | Concede |
|---|---|
read:balances | GET /v1/balances |
read:recipients | GET /v1/recipients |
write:recipients | POST /v1/recipients |
read:payouts | GET /v1/payout-batches, GET /v1/payout-batches/{id} |
write:payouts | POST /v1/payout-batches, POST /v1/payout-batches/{id}/submit |
Conceda apenas os scopes que uma integração realmente precisa. Um script de
importação em lote que só cria beneficiários deve receber
write:recipients, não write:payouts.
Respostas de erro
| Status | Significado |
|---|---|
401 | Token ausente, inválido, revogado ou expirado |
403 | Token válido, mas sem o scope necessário para este endpoint |
Ambos os casos retornam:
{
"message": "..."
}
O que está fora do escopo
Não existe endpoint de API para aprovar, rejeitar ou executar uma folha de pagamento. A aprovação sempre acontece no painel, por um humano, com 2FA. Veja a Introdução para entender por que essa fronteira existe.