Claves de API
Stripe autentica tus peticiones de API usando las claves de API de tu cuenta. Si una petición no incluye una 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 en un modo desde el otro. Por ejemplo, un en modo de prueba objeto de producto 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 . | Usa cuentas y tarjetas de crédito de prueba. No puedes aceptar métodos de pago reales o trabajar con cuentas reales. | Identity no hace comprobaciones de verificación. Además, los objetos de cuenta de Connect no devuelven campos confidenciales. |
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. | Las disputas tienen un flujo con algunos matices y un proceso de prueba más sencillo. Además, algunos métodos de pago tienen un flujo con más matices y exigen dar más pasos. |
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.
Puedes encontrar tus claves secretas y publicables en la página de Claves de API en el Dashboard de desarrolladores. Mientras estás conectado, la documentación de Stripe rellena automáticamente los ejemplos de código con tus claves de API en modo de prueba. (Solo tú puedes ver estos valores). Si no has iniciado sesión, nuestros ejemplos de código incluyen claves de API generadas de forma aleatoria. Reemplázalos por tus propias claves de prueba o inicia sesión para ver los ejemplos de código que se han completado con tus claves de API de prueba. Si no puedes ver las claves de API, pídele al titular de tu cuenta de Stripe que te añada a su equipo con los permisos adecuados.
La siguiente tabla muestra ejemplos generados aleatoriamente de claves de API de prueba secretas y publicables:
Claves de API restringidas
El Dashboard también puede incluir claves de API restringidas, que permiten un acceso limitado personalizable a la API. Stripe no proporciona ninguna clave restringida de forma predeterminada.
Tipo | Valor | Cuándo usarlo |
---|---|---|
Secreta | 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 | En el lado del cliente: puede ser de acceso público en el código del lado del cliente de tu aplicación web o móvil (como checkout.js) para recopilar información de pago de forma segura, como sucede con Stripe Elements. De forma predeterminada, Stripe Checkout recopila de forma segura la información de pago. | |
Restringido | Una cadena que comienza con rk_test_ | 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 especificado.
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
Si especificas un rango de direcciones IP, solo pueden abarcar el cuarto byte de la dirección. Todas las direcciones en el rango deben tener los mismos tres primeros bytes. Por ejemplo, un rango válido podría ser 100.10.38.1-100.10.38.12
, especificado como 100.10.38.1/12
. Todas las direcciones en el rango deben comenzar con 100.10.38
.
- 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 Restringir las direcciones IP que pueden usar la clave de API.
- Introduce una lista o un rango de direcciones IP:
- Para obtener una lista de direcciones IP, introduce la primera dirección IP en los campos. Para cada dirección IP adicional, haz clic en **+ Añadir dirección IP ** e introduce la dirección.
- Para un rango de direcciones IP, haz clic en CIDR y, a continuación, introduce el rango en la notación de enrutamiento entre dominios sin clases (CIDR). En los tres primeros campos, introduce los tres primeros números de las direcciones IP en el rango. En los campos cuarto y quinto, introduce el cuarto número de la primera y la última dirección en el rango, respectivamente.
- Haz clic en Guardar.
Atajos
Pulsa Ctrl+V o ⌘+V con una dirección IP válida en tu portapapeles para introducir texto en todos los campos.
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.