Authentication
PagusPay's API uses Bearer JWT authentication. Every request to a /v1/*
endpoint requires a valid token in the Authorization header.
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.paguspay.com/api/v1/balances
The token encodes organizationId, userId, and scopes — the organization
for a request always comes from the token, never from any other state.
Creating an API key
API tokens are created from the dashboard, not the API:
- Log in to the PagusPay dashboard
- Go to Settings → API
- Click Create API Key, select the scopes it needs, and confirm
The full token value is displayed only at creation time. Copy it
immediately and store it somewhere safe (secret manager, .env file) — it
cannot be retrieved again. If you lose it, revoke it and create a new one.
Scopes
Each token is issued with one or more scopes. Requests are rejected with
403 if the token's scopes don't cover the endpoint being called.
| Scope | Grants |
|---|---|
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 |
Grant only the scopes an integration actually needs. A batch-import script
that only creates recipients should get write:recipients, not
write:payouts.
Error responses
| Status | Meaning |
|---|---|
401 | Token missing, invalid, revoked, or expired |
403 | Token valid but missing the scope required for this endpoint |
Both cases return:
{
"message": "..."
}
What's out of scope
There is no API endpoint to approve, reject, or execute a payout batch. Approval always happens in the dashboard, by a human, with 2FA. See the Introduction for why this boundary exists.