Referencia de la API
La API pública de Paygumi es REST sobre HTTPS con JSON. Esta referencia se genera automáticamente desde la especificación OpenAPI (versión 0.1.0).
URL base
https://api.paygumi.comTodas las rutas públicas empiezan por /v1. Las fechas van en RFC 3339 (UTC), los montos en centavos enteros (amount_in_cents, sin decimales) y las tasas en puntos básicos.
Autenticación
Envía tu API key en la cabecera Authorization de cada petición, desde tu backend (nunca desde el navegador):
Authorization: Bearer pgm_test_...API key del tenant: pgm_live_ o pgm_test_ seguido de 32 bytes
aleatorios en base62 (43 caracteres). Se muestra una sola vez al crearla;
Paygumi guarda solo su SHA-256. Una llave revocada o desconocida
responde 401 unauthorized. Límite: 100 peticiones por segundo por
llave (429 rate_limited con Retry-After).
El prefijo de la llave elige el entorno: pgm_test_ trabaja en sandbox y pgm_live_ en producción. Los datos de un entorno no se ven desde el otro. Más en Primeros pasos.
Paginación
Los listados se paginan por cursor: ?limit=50&starting_after=<id> devuelve { "data": [...], "has_more": true }. Para la página siguiente, pasa en starting_after el id del último elemento.
Errores
Los errores usan códigos HTTP y siempre el mismo cuerpo. Decide por error.code (estable); message es solo para humanos. Toda respuesta trae la cabecera X-Request-Id, igual a error.request_id.
| Campo | Tipo | Descripción |
|---|---|---|
errorobligatorio | object | |
error.typeobligatorio | string | Categoría pública. Estados HTTP: invalid_request (400, 405, 413, 415, 422 validación, 409 estado inválido), conflict (409), not_found (404), unauthorized (401), forbidden (403), rate_limited (429), gateway_error (502), internal (500; sin detalles). Valores: |
error.codeobligatorio | string | Identificador estable en snake_case (ej. plan_archived, route_not_found). |
error.messageobligatorio | string | Texto legible; no se debe parsear. |
error.param | string | Campo de la entrada que causó el error, si aplica (ej. plan_id). |
error.resource_id | string | En algunos 409, el id del recurso que causó el conflicto (ej. customer_external_id_taken trae el id del cliente que ya tiene ese external_id). |
error.request_id | string | Igual al header X-Request-Id. |
{
"error": {
"type": "invalid_request",
"code": "plan_archived",
"message": "El plan está archivado.",
"param": "plan_id",
"request_id": "req_01JB86R800ABCDEFGHJKMNPQRS"
}
}