Autenticación
Todas las rutas /v1/* se autentican con una clave de API:
Authorization: Bearer sk_live_...
X-API-Key: sk_live_... se acepta igualmente, para los clientes HTTP que reservan Authorization
para otra cosa.
Claves de prueba y claves reales
| Prefijo | Modo | Dinero real |
|---|---|---|
sk_test_… |
Prueba | No — todo el código se ejecuta (enrutamiento, comisiones, validaciones), ningún movimiento de dinero |
sk_live_… |
Producción | Sí |
Los objetos creados en modo de prueba llevan is_test: true y nunca aparecen en sus informes de
producción.
El modo de prueba no cubre el pago instantáneo. Las familias PI y tontine rechazan las claves de prueba: hablan con un sistema externo que no tiene entorno de pruebas por nuestra parte.
El secreto existe una sola vez
Al crear (o rotar) una clave, el secreto se muestra una vez. Del lado del servidor sólo se guarda su huella HMAC: nadie — ni el soporte — puede devolvérselo. ¿Perdido? Haga una rotación: la clave antigua queda revocada y la nueva se muestra una vez.
¿Por qué mi clave responde client_inactive?
Una clave se emite en cuanto se registra, pero no admite ninguna llamada mientras la cuenta no
esté validada (expediente KYB aprobado, cuenta en estado active). Es la puerta de cumplimiento:
se abre con la validación y se cierra de inmediato en caso de suspensión — la misma clave, sin
ningún otro cambio.
Alcances
Cada clave lleva alcances, y una operación fuera de alcance responde 403 insufficient_scope:
cobrar, pagar, reembolsar, leer, gestionar los webhooks. Emita la clave más estrecha que haga el
trabajo — una clave de lectura para sus informes no necesita poder pagar.
Idempotencia
En las creaciones (POST /v1/payments, POST /v1/payouts, POST /v1/refunds…), pase una cabecera
Idempotency-Key de su elección — por ejemplo su referencia de pedido. Un reenvío con la misma
clave devuelve la operación original, nunca un duplicado; la misma clave con un cuerpo distinto se
rechaza con 409.
Una clave por operación, nunca por objeto padre. Un cobro puede reembolsarse en varias veces: una clave de idempotencia que lleve el identificador del pago haría pasar el segundo reembolso parcial por un reenvío del primero. Éxito para el comercio, cliente sin reembolsar.
Límite de peticiones
300 peticiones por minuto y por clave. Por encima, 429 con una cabecera Retry-After — respétela
en lugar de reintentar de inmediato.
Buenas prácticas
- Una clave por entorno (producción, staging), nunca compartida entre servicios.
- El secreto vive en un gestor de secretos, nunca en el código ni en el front.
- Rotación inmediata ante la menor duda — sin corte si despliega la clave nueva antes de revocar la antigua.