En esta página
Claves de API
Crea claves de API Payment o Payout, entiende sus alcances y prefijos, rota las credenciales sin riesgo y separa el acceso de prueba del real.
Paymos emite dos tipos de clave por entorno, cada uno limitado a un conjunto fijo de operaciones. Una credencial Payment filtrada no puede mover fondos: el alcance se comprueba de forma centralizada en cada petición, así que una clave Payment nunca llega a un endpoint de retiros, sea cual sea la ruta por la que entre.
Tipos de clave
| Tipo | Prefijo | Alcance |
|---|---|---|
| Payment | pk_ |
Crear facturas, leer su estado, gestionar canales de pago y leer sus depósitos |
| Payout | rk_ |
Crear retiros, cancelar retiros, leer saldos |
Los secretos de API usan el prefijo sk_. Los secretos de firma de webhooks usan whsec_.
Entornos
Cada credencial pertenece a un único entorno. El entorno va codificado en el prefijo:
| Entorno | Modificador del prefijo | Ejemplo |
|---|---|---|
| Producción | _live_ |
pk_live_…, rk_live_… |
| Sandbox | _test_ |
pk_test_…, rk_test_… |
Un comercio configurado por completo tiene cuatro identificadores de clave de API (pk_live_…, pk_test_…, rk_live_…, rk_test_…) y dos secretos de webhook (whsec_live_…, whsec_test_…).
Detalles del alcance
La separación de alcances se aplica de forma centralizada, no ruta por ruta: el nivel de acceso se deduce del tipo de clave en cada petición, así que una clave Payment solo alcanza los endpoints de dinero entrante y una clave Payout solo los de retiros.
Los canales de pago están del lado del dinero que entra. Los ocho endpoints de canales y depósitos piden una clave Payment y responden 403 payment_key_required a una clave Payout, igual que los retiros rechazan una clave Payment.
Los saldos son el reparto que más sorprende: GET /v1/balances pide una clave Payout. La clave Payment vive en los servidores de la tienda, viaja en cada despliegue y es la que acaba filtrándose, así que no se le da vista de lo que tienes acumulado. Lee saldos desde el mismo sitio donde lanzas los retiros.
Payout tiene además una protección extra. Una credencial Payout permanece inactiva hasta que añades una lista blanca de IP: mientras no haya al menos una IP autorizada en el panel, se rechaza cualquier petición. Una clave Payout recién generada no puede mover fondos por sí sola.
Una clave Payout puede sacar fondos de tu saldo en Paymos: trátala como la contraseña de tu banco. La lista blanca de IP es el muro entre una clave robada y tu dinero, así que mantenla lo más estrecha posible e incluye solo las IP de los servidores que realmente llaman a la API de retiros.
Ciclo de vida
| Estado | Descripción |
|---|---|
| Active | La credencial está operativa y acepta peticiones |
| Revoked | Estado final. La credencial queda desactivada de forma permanente y no se puede reactivar |
Buenas prácticas de seguridad
- —No expongas nunca los secretos de API en código de cliente
- —Rota los secretos periódicamente desde el panel: un periodo de gracia mantiene válido el secreto anterior durante la transición
- —Usa credenciales distintas para producción y sandbox
- —Restringe las credenciales Payout por dirección IP
- —Guarda los secretos de API solo en variables de entorno o en un gestor de secretos
El esquema de firma HMAC-SHA256 que usa estas credenciales está en Autenticación.