Claves de API
Utiliza las claves de API para autenticar las peticiones de API.
Stripe autentica tus peticiones de API usando las claves de API de tu cuenta. Si una petición no incluye ninguna clave válida, Stripe devuelve un error de petición no válida. Si una petición incluye una clave eliminada o caducada, Stripe devuelve un error de autenticación.
Usa el Dashboard de desarrolladores para crear, revelar, eliminar y cambiar claves de API. Para acceder a tus claves de API v1, elige la pestaña Claves de API en tu Dashboard.
El modo de prueba frente al modo activo
Todas las peticiones de API de Stripe se realizan en el modo de prueba o en el modo activo. Utiliza el modo de prueba para acceder a los datos de prueba y el modo activo para acceder a los datos de la cuenta real. Cada modo tiene su propio conjunto de claves de API. No se puede acceder a los objetos de un modo desde el otro. Por ejemplo, un objeto de producto del modo de prueba no puede formar parte de un pago en modo activo.
Acceso con clave en modo activo
Solo puedes revelar una clave de API secreta o restringida del modo activo una vez. Si la pierdes, no podrás recuperarla desde el Dashboard. En ese caso, debes cambiarla, eliminarla o crear una nueva.
| Tipo | Cuándo usarlo | Objetos | Cómo se usa | Consideraciones |
|---|---|---|---|---|
| modo de prueba | Usa el modo de prueba y sus claves de API de prueba asociadas a medida que crees tu integración. En el modo de prueba, las redes de tarjetas y los proveedores de servicios de pago no procesan pagos. | Las llamadas a la API devuelven objetos simulados. Por ejemplo, puedes recuperar y usar objetos de prueba de account, payment, customer, charge, refund, transfer, balance y subscription. | Use test credit cards and accounts. You can’t accept real payment methods or work with real accounts. | Identity doesn’t perform any verification checks. Also, Connect account objects don’t return sensitive fields. |
| modo activo | Usa el modo activo y sus claves de API activas asociadas cuando estés listo para lanzar tu integración y aceptar dinero real. En el modo activo, las redes de tarjetas y los proveedores de servicios de pago sí procesan pagos. | Las llamadas a la API devuelven objetos reales. Por ejemplo, puedes recuperar y usar objetos reales de account, payment, customer, charge, refund, transfer, balance y subscription. | Acepta tarjetas de crédito reales y trabaja con cuentas de clientes. Puede aceptar autorizaciones de pago reales, cargos y capturas para tarjetas de crédito y cuentas. | Disputes have a more nuanced flow and a simpler testing process. Also, some payment methods have a more nuanced flow and require more steps. |
Claves secretas y publicables
Todas las cuentas tienen un total de cuatro claves de API de forma predeterminada: dos para el modo de prueba y dos para el modo activo:
- Clave secreta en modo de prueba: usa esta clave para autenticar solicitudes en tu servidor cuando estés en el modo de prueba. De forma predeterminada, puedes usar esta clave para realizar cualquier petición de API sin restricciones.
- Clave publicable en modo de prueba: usa esta clave para realizar pruebas en el código del lado del cliente de tu web o aplicación móvil.
- Clave secreta en modo activo: usa esta clave para autenticar peticiones en tu servidor cuando estés en modo activo. De forma predeterminada, puedes usar esta clave para realizar cualquier petición de API sin restricciones.
- Clave publicable en modo activo: usa esta clave cuando estés listo para lanzar tu aplicación en el código del lado cliente de tu aplicación web o móvil.
Pruebas y tareas de desarrollo
Usa solo las claves de API de prueba para pruebas y tareas de desarrollo. De esta manera, no modificarás por error cargos o clientes en modo activo.
You can find your secret and publishable keys in API keys. When you’re logged in, Stripe’s documentation automatically populates code examples with your test mode API keys (only you can see these values). If you’re not logged in, our code examples include randomly generated API keys. You can replace them with your own test keys or log in to see the code examples populated with your test API keys. If you can’t view your API keys, ask the owner of your Stripe account to add you to their team, with the proper permissions.
La siguiente tabla muestra ejemplos generados aleatoriamente de claves de API de prueba secretas y publicables:
Claves de API restringidas
The Dashboard can also generate restricted API keys, enabling customizable and limited access to the API. However, Stripe doesn’t offer any restricted keys by default.
| Tipo | Valor | Cuándo usarlo |
|---|---|---|
| Secreta | sk_ | En el lado del servidor: debe ser secreta y almacenarse de forma segura en el código del lado del servidor de tu aplicación web o móvil (como en una variable de entorno o sistema de administración de credenciales) para llamar a las API de Stripe. No expongas esta clave en un sitio web ni la insertes en una aplicación móvil. |
| Publicable | pk_ | On the client side: Can be publicly accessible in your web or mobile app’s client-side code (such as checkout.js) to securely collect payment information, such as with Stripe Elements. By default, Stripe Checkout securely collects payment information. |
| Restringido | Una cadena que comienza con rk_ | En microservicios: debe ser secreta y almacenarse de forma segura en tu código de microservicios para llamar a las API de Stripe. No expongas esta clave en un sitio web ni la insertes en una aplicación móvil. |
Protege tus claves
Cualquier persona puede usar tu clave secreta de API en modo activo para realizar cualquier llamada a la API en nombre de tu cuenta, como crear un cargo o realizar un reembolso. Para mantener seguras tus claves, sigue las mejores prácticas de claves secretas de API.
Cómo personalizar el acceso a la API con claves de API restringidas
Para proporcionar acceso limitado a la API, crea claves de API restringidas. Puedes configurar una clave de API restringida para permitir el acceso de lectura o escritura a la referencia API específica. Cuando utilices microservicios que interactúen con la API en tu nombre, define claves restringidas que permitan solo el acceso mínimo que requieren esos microservicios. Por ejemplo, si utilizas un servicio de supervisión de disputas, crea una clave restringida que solo proporcione acceso de lectura a los recursos relacionados con las disputas. Esa clave permite que el servicio obtenga los datos que necesita, pero no le permite realizar ningún cambio ni acceder a ningún otro dato.
Las claves restringidas no pueden interactuar con muchas partes de la API de Stripe, ya que solo están diseñadas para reducir el riesgo al usar o crear microservicios. No utilices claves restringidas como alternativa a las claves de API secretas o publicables de tu cuenta durante el desarrollo de tu integración con Stripe.
Errores de permiso
Si usas una clave de API restringida en una llamada a la que esa API no tiene acceso, Stripe generará un error de permiso.
Cómo limitar las direcciones IP que pueden enviar peticiones de API
Puedes mejorar la seguridad de una clave secreta o restringida si limitas las direcciones IP que pueden usarla para enviar solicitudes de API. Además, puedes restringir una clave a una o más direcciones IP o a un rango de direcciones IP.
Cómo revelar una clave de API secreta para el modo de prueba
En el modo de prueba, puedes revelar una clave de API secreta tantas veces como quieras.
Para revelar una clave secreta en el modo de prueba, haz lo siguiente:
- En el Dashboard de desarrolladores, elige la pestaña Claves de API.
- En la lista Claves estándar, en la fila Clave secreta, haz clic en Revelar clave de prueba.
- Para copiar el valor de la clave, haz clic en él.
- Guarda el valor de la clave.
- Haz clic en Ocultar clave de prueba.
Cómo revelar una clave de API secreta o restringida para el modo activo
Por seguridad, en modo activo, Stripe solo te muestra una clave de API secreta o restringida una vez. Almacena la clave en un lugar seguro donde no la pierdas. Para ayudarte a recordar dónde la has almacenado, puedes dejar una nota sobre la clave en el Dashboard. Si pierdes la clave, puedes cambiarla o eliminarla y crear otra.
No puedes revelar una clave secreta del modo activo que hayas creado
Después de crear una clave de API secreta o restringida en modo activo, mostramos el valor antes de guardarlo. Debes copiar el valor antes de guardarlo porque no puedes revelarlo más tarde. Solo puedes revelar una clave secreta predeterminada o una clave generada por un cambio programado.
Para revelar una clave secreta o restringida en modo activo y adjuntar una nota, haz lo siguiente:
Nota
Este enlace API keys se abre en modo activo.
- En el Dashboard de desarrolladores, elige la pestaña Claves de API.
- En la lista Claves estándar o en la lista Claves restringidas, en la fila correspondiente a la clave que deseas mostrar, haz clic en Revelar clave activa.
- Para copiar el valor de la clave, haz clic en él.
- Guarda el valor de la clave.
- Haz clic en Ocultar clave de prueba.
- Haz clic en el menú de desbordamiento () ubicado junto a la clave y, a continuación, elige Editar clave….
- En el campo Nota, introduce la ubicación donde guardaste la clave y luego haz clic en Guardar.
- Si has creado la clave antes de que Stripe incorporara esta función, haz clic en Ocultar clave activa.
Nota
Las claves que creaste antes de que Stripe introdujera esta función no se ocultan automáticamente cuando se revelan. Debes ocultarlas de forma manual.
Cómo cambiar una clave de API
Si se cambia una clave, esta se revoca y se genera una clave de reemplazo. Puedes cambiar una clave inmediatamente o programar el cambio de una clave después de un determinado tiempo. Debes cambiar una clave en escenarios como los descritos en los siguientes ejemplos:
- Si estás en modo activo y pierdes una clave secreta o restringida, no podrás recuperarla desde el Dashboard y deberás reemplazarla.
- Si una clave secreta o restringida se ve comprometida, debes revocarla para bloquear cualquier petición de API potencialmente maliciosa que pueda usarla.
- Tu política requiere que se cambien las claves en intervalos determinados.
Para cambiar una clave de API, haz lo siguiente:
- Abra la página de claves de API.
- En la fila de la clave que deseas cambiar, haz clic en el menú de desbordamiento () y, a continuación, elige Cambiar clave….
- Elige una fecha de caducidad en el menú desplegable Caducidad.
- Haz clic en Cambiar clave de API.
- El cuadro de diálogo muestra el nuevo valor de la clave. Para copiarlo, haz clic en él.
- Guarda el valor de la clave. No podrás recuperarlo más tarde.
- En el campo Añadir una nota, introduce la ubicación donde has guardado la clave y haz clic en Listo o Guardar.
Si eliges Ahora para la Caducidad, eliminaremos la clave anterior. Si has elegido otro momento, podrás ver el tiempo restante hasta que la clave expire debajo de su nombre.
Independientemente del tiempo de caducidad de la clave anterior, la nueva clave estará lista para usarse de inmediato.
Al cambiar una clave publicable, el nombre de la clave de reemplazo es siempre Publishable key. Al cambiar una clave secreta, el nombre de la clave de reemplazo es siempre Secret key. Al cambiar una clave restringida, el nombre de la clave de reemplazo es el mismo que el de la clave cambiada. Para cambiar el nombre de una clave secreta o restringida, haz clic en su menú de desbordamiento y elige Editar clave….
Cómo eliminar una clave de API secreta o restringida
Si eliminas una clave, cualquier código que use esa clave ya no podrá realizar llamadas a la API. Crea una nueva clave y actualiza el código para usarla.
Nota
No puedes eliminar una clave publicable.
Para eliminar una clave, haz lo siguiente:
- En el Dashboard de desarrolladores, elige la pestaña Claves de API.
- Busca la clave que deseas eliminar en la lista Claves estándar o Claves restringidas. Haz clic en el icono del menú de desbordamiento () en la fila de esa clave y luego elige Eliminar clave….
- En el cuadro de diálogo «Eliminar clave de API», si estás seguro de que deseas eliminar la clave, haz clic en Eliminar clave. De lo contrario, haz clic en Cancelar.
Cómo crear una clave de API secreta
Para crear una clave de API secreta, haz lo siguiente:
- Abra la página de claves de API.
- Haz clic en Crear clave secreta.
- Stripe envía un código de verificación a tu dirección de correo electrónico o en un mensaje de texto. (Al igual que con cualquier correo electrónico o mensaje de texto, es posible que no llegue de inmediato). Introduce el código en el cuadro de diálogo. Si el cuadro de diálogo no continúa de manera automática, haz clic en Continuar.
- Introduce un nombre en el campo Nombre de la clave.
- Haz clic en Crear.
- El cuadro de diálogo muestra el nuevo valor de la clave. Para copiarlo, haz clic en él.
- Guarda el valor de la clave. No podrás recuperarlo más tarde.
- En el campo Añadir una nota, introduce la ubicación donde has guardado la clave y haz clic en Listo.
Cómo crear una clave de API restringida
Una clave de API restringida solo permite el nivel de acceso que especifiques.
Para crear una clave de API restringida, haz lo siguiente:
- Abra la página de claves de API.
- Puedes crear una clave restringida desde cero o comenzar por clonar una clave restringida existente.
- Para crear una clave restringida desde cero, haz clic en Crear clave restringida. En este caso, el valor predeterminado para todos los permisos es Ninguno.
- Para clonar una clave existente, en la fila de la clave que deseas clonar, haz clic en el menú de desbordamiento () y, a continuación, elige Duplicar clave…. En este caso, el valor predeterminado para cada permiso es su valor en la clave clonada.
- En el campo Nombre de clave, introduce un nombre. Si has clonado una clave existente, el nombre predeterminado es el nombre de la clave clonada.
- Para cada recurso al que deseas que acceda la nueva clave, elige el permiso para que esta clave lo permita. Si usas Connect, también puedes elegir el permiso para que esta clave lo permita al acceder a las cuentas conectadas. Los permisos disponibles son Ninguno, Lectura o Escritura.
- Haz clic en Crear clave.
- Stripe envía un código de verificación a tu dirección de correo electrónico o en un mensaje de texto. (Al igual que con cualquier correo electrónico o mensaje de texto, es posible que no llegue de inmediato). Introduce el código en el cuadro de diálogo. Si el cuadro de diálogo no continúa de manera automática, haz clic en Continuar.
- El cuadro de diálogo muestra el nuevo valor de la clave. Para copiarlo, haz clic en él.
- Guarda el valor de la clave. No podrás recuperarlo más tarde.
- En el campo Añadir una nota, introduce la ubicación donde has guardado la clave y haz clic en Listo.
Cómo limitar las claves secretas o restringidas a una lista o un rango de direcciones IP
Para limitar las peticiones de API que usan una clave a una o varias direcciones IP específicas o a un rango de direcciones IP, haz lo siguiente:
Rangos de direcciones IP válidos
Puedes especificar cualquier rango de CIDR válido. Por ejemplo, un rango válido podría ser 100., especificado como 100.. Todas las direcciones del rango deben comenzar por 100..
- Abra la página de claves de API.
- En la lista Claves estándar o en la lista Claves restringidas, en la fila correspondiente a la clave que deseas mostrar, haz clic en el menú de desbordamiento () y, a continuación, elige Administrar restricciones de direcciones IP….
- Haz clic en **Limitar el uso a un conjunto de direcciones IP **.
- Introduce una dirección IP o un rango de direcciones IP:
- En el caso de una dirección IP individual, introdúzcala en el campo Dirección IP.
- Para un rango de direcciones IP, introduce el rango en la notación de enrutamiento entre dominios sin clases (CIDR). En el campo Dirección IP, introduce la primera dirección en el rango. En el campo CIDR, introduce el tamaño del prefijo de red.
- También puedes seleccionar la pestaña Gestionar de forma masiva e introducir direcciones IP individuales y rangos, separados por espacios. Los cambios que realices en una pestaña se harán también en la otra pestaña.
- Para añadir otra dirección o intervalo, haz clic en + Añadir.
- Haz clic en Guardar.
Cómo cambiar el nombre o la nota de una clave de API secreta o restringida
Para cambiar el nombre o el texto de la nota de una clave secreta o restringida, haz lo siguiente:
- Abra la página de claves de API.
- En la fila de la clave que quieres cambiar, haz clic en el menú de desbordamiento () y elige Editar clave….
- Si deseas cambiar el nombre, introduce el nuevo nombre en Nombre de la clave.
- Si deseas cambiar el texto de la nota, en Nota, introduce el nuevo texto de la nota.
- Haz clic en Guardar.
Cómo ver los registros de las peticiones de API
Para abrir los registros de peticiones de API, haz clic en el menú de desbordamiento () de cualquier clave y, a continuación, elige Ver registros de peticiones. Al abrir los registros, regresarás al Dashboard principal de Stripe.