Autenticación
La API de PagusPay usa autenticación Bearer JWT. Toda solicitud a un
endpoint /v1/* requiere un token válido en el encabezado Authorization.
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.paguspay.com/api/v1/balances
El token codifica organizationId, userId y scopes — la organización de
una solicitud siempre proviene del token, nunca de otro estado.
Creación de una API key
Los tokens de API se crean desde el panel, no desde la API:
- Inicie sesión en el panel de PagusPay
- Vaya a Configuración → API
- Haga clic en Crear API Key, seleccione los scopes necesarios y confirme
El valor completo del token se muestra solo en el momento de la
creación. Cópielo de inmediato y guárdelo en un lugar seguro (gestor de
secretos, archivo .env) — no se puede recuperar después. Si lo pierde,
revóquelo y cree uno nuevo.
Scopes
Cada token se emite con uno o más scopes. Las solicitudes se rechazan con
403 si los scopes del token no cubren el endpoint llamado.
| Scope | Otorga |
|---|---|
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 |
Otorgue solo los scopes que una integración realmente necesita. Un script de
importación masiva que solo crea beneficiarios debe recibir
write:recipients, no write:payouts.
Respuestas de error
| Estado | Significado |
|---|---|
401 | Token ausente, inválido, revocado o expirado |
403 | Token válido, pero sin el scope necesario para este endpoint |
Ambos casos devuelven:
{
"message": "..."
}
Qué queda fuera del alcance
No existe endpoint de API para aprobar, rechazar o ejecutar un lote de pago. La aprobación siempre ocurre en el panel, por un humano, con 2FA. Vea la Introducción para entender por qué existe este límite.