Claves de API
Stripe autentica tus solicitudes de API usando las claves de API de tu cuenta. Si una solicitud no incluye una clave válida, Stripe muestra un error de solicitud no válida. Si una solicitud incluye una clave eliminada o vencida, Stripe muestra 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, selecciona la pestaña Claves de API en tu Dashboard.
Modo de prueba versus modo activo
Todas las solicitudes de API de Stripe se realizan en el modo de prueba o en el modo activo. Usa 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. Los objetos en un modo no son accesibles en el otro. Por ejemplo, un en el modo de prueba objeto Product no puede formar parte de un pago en el modo activo.
Acceso a las claves en modo activo
Solo puede revelar una clave de API secreta o restringida en el modo activo una vez. Si la pierdes, no puedes recuperarla desde el Dashboard. En ese caso, cámbiala o elimínala y crea una nueva.
Type | Cuándo usar | Objects | Cómo usar | Considerations |
---|---|---|---|---|
modo de prueba | Cuando creas tu integración, usa el modo de prueba y sus claves de API de prueba asociadas. En el modo de prueba, las redes de tarjetas y los proveedores de servicios de pagos no procesan los pagos. | Las llamadas de la API devuelven objetos simulados. Por ejemplo, puedes recuperar y usar objetos de prueba del tipo account , payment , customer , charge , refund , transfer , balance y subscription . | Usa tarjetas de crédito y cuentas de prueba. No puedes aceptar métodos de pago reales ni trabajar con cuentas reales. | Identity no realiza comprobaciones de verificación. Además, los objetos de cuenta de Connect no devuelven campos confidenciales. |
modo activo | Cuando tengas todo listo para lanzar tu integración y aceptar dinero real, usa el modo activo y sus claves de API activas asociadas. En el modo activo, las redes de tarjetas y los proveedores de servicios de pago procesan los pagos. | Las llamadas de la API devuelven objetos reales. Por ejemplo, puedes recuperar y usar objetos reales del tipo 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, cargos y capturas reales de tarjetas de crédito y cuentas. | Las disputas tienen un flujo con más matices y un proceso de prueba más simple. Además, algunos métodos de pago tienen un flujo con más matices y exigen que se tomen más medidas. |
Claves secretas y publicables
Por defecto, todas las cuentas tienen un total de cuatro claves de API: dos para el modo de prueba y dos para el modo activo.
- Clave secreta del modo de prueba: usa esta clave para autenticar solicitudes en tu servidor cuando esté en modo de prueba. De forma predeterminada, puedes usar esta clave para realizar cualquier solicitud de API sin restricciones.
- Clave publicable del modo de prueba: usa esta clave para realizar pruebas en el código del lado del cliente de tu aplicación web o para dispositivos móviles.
- Clave secreta del modo activo: usa esta clave para autenticar solicitudes en tu servidor cuando esté en modo activo. De forma predeterminada, puedes usar esta clave para realizar cualquier solicitud de API sin restricciones.
- Clave publicable del modo activo: cuanto tengas todo listo para lanzar tu aplicación, usa esta clave en el código del lado del cliente de tu aplicación web o para dispositivos móviles.
Pruebas y tareas de desarrollo
Usa únicamente tus claves de API de prueba para realizar pruebas y tareas desarrollo. Esto garantiza que no modifiques accidentalmente tus clientes o cargos activos.
Puedes encontrar tus claves secretas y publicables en la página 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 las claves de API del modo de prueba. (Solo tú puedes ver estos valores). Si no iniciaste sesión, nuestros ejemplos de código incluyen claves de API generadas aleatoriamente. Reemplázalas con tus propias claves de prueba o inicia sesión para ver los ejemplos de código rellenados con tus propias claves de API de prueba. Si no puedes ver tus claves de API, pídele al titular de tu cuenta de Stripe que te agregue 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.
Type | Value | Cuándo usar |
---|---|---|
Secretas | **En el lado del servidor **: Debe ser secreto 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 incrustes en una aplicación móvil. | |
Publishable | **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 con Stripe Elements. De forma predeterminada, Stripe Checkout recopila de forma segura la información de pago. | |
Restringidas | Una cadena que comienza con rk_test_ | En microservicios: Debe ser secreto y almacenarse de forma segura en tu código de microservicio para llamar a las API de Stripe. No expongas esta clave en un sitio web ni la incrustes en una aplicación móvil. |
Protege tus claves
Cualquier persona puede usar tu clave de API secreta en el modo activo para realizar una llamada API en nombre de tu cuenta, como crear un cargo o realizar un reembolso. Mantén tus claves seguras siguiendo las mejores prácticas de las claves secretas de la API.
Personaliza 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 recursos de API específicos. Cuando uses 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 usas un servicio de monitoreo 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 tienen el objetivo de disminuir el riesgo cuando se usan o se crean microservicios. No uses 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 permisos
Si usas una clave de API restringida en una llamada a la que no tiene acceso, Stripe genera un error de permiso.
Limita las direcciones IP que puedan enviar solicitudes de API
Puedes aumentar la seguridad de una clave secreta o restringida si limitas las direcciones IP que puedan 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.
Revela una clave de API secreta para el modo de prueba
En el modo de prueba, puedes revelar una clave de API secreta todas las veces que quieras.
Para revelar una clave secreta en el modo de prueba, haz lo siguiente:
- En el Dashboard para desarrolladores, selecciona la pestaña claves de API.
- En la lista Claves estándar, en la fila Clave secreta, haz clic en Revelar clave de prueba.
- Haz clic en el valor de la clave para copiarlo.
- Guarda el valor de la clave.
- Haz clic en Ocultar clave de prueba.
Revela una clave de API secreta o restringida para el modo activo
Por motivos de seguridad, Stripe te muestra una clave de API secreta o restringida solo una vez en el modo activo. Guarda la clave en un lugar seguro donde no la pierdas. Para ayudarte a recordar dónde la guardaste, puedes dejar una nota en la clave en el Dashboard. Si pierdes la clave, puedes cambiarla o eliminarla y crear otra.
No puedes revelar una clave secreta en el modo activo que hayas creado
Luego de que creas una clave de API secreta o restringida en modo activo, te mostramos el valor antes de guardarla. Tienes que copiar el valor antes de guardarla, porque luego no podrás volver a verlo. Solo puedes revelar una clave secreta predeterminada o una clave generada por una cambio programado.
Para revelar una clave secreta o restringida en el modo activo y adjuntar una nota, haz lo siguiente:
Nota
El enlace API keys
se abre aquí en modo activo.
- En el Dashboard para desarrolladores, selecciona 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 revelar, haz clic en Revelar clave activa.
- Haz clic en el valor de la clave para copiarlo.
- Guarda el valor de la clave.
- Haz clic en Ocultar clave de prueba.
- Haz clic en el menú de contenido adicional () junto a la clave y, luego, selecciona Editar clave….
- En el campo Nota, ingresa la ubicación donde guardaste la clave y, luego, haz clic en Guardar.
- Si creaste la clave antes de que Stripe agregara esta funcionalidad, haz clic en Ocultar clave activa.
Nota
Las claves que creaste antes de que Stripe incorporara esta funcionalidad no se ocultan automáticamente cuando se revelan. Debes ocultarlas manualmente.
Cambia una clave de API
Cuando se cambia una clave, esta se revoca y se genera otra de reemplazo. Puedes cambiar una clave en el momento o programar su cambio pasado determinado tiempo. Es necesario cambiar la clave en escenarios como los siguientes:
- Si estás en modo activo y pierdes una clave secreta o restringida, no puedes recuperarla desde el Dashboard y tienes que reemplazarla.
- Si una clave secreta o restringida se ve comprometida, tienes que revocarla para bloquear las solicitudes de API potencialmente maliciosas que puedan usarla.
- Tu política requiere cambiar las claves cada cierto período de tiempo.
Para cambiar una clave de API, haz lo siguiente:
- Abre la página de claves de API.
- En la fila de la clave que deseas cambiar, haz clic en el menú de contenido adicional (), luego selecciona Cambiar clave….
- Elige una fecha de vencimiento en el menú desplegable Vencimiento.
- Haz click en Cambiar clave de API.
- El cuadro de diálogo muestra el nuevo valor de la clave. Haz clic en él para copiarlo.
- Guarda el valor de la clave. No puedes recuperarlo más tarde.
- En el campo Agregar una nota, ingresa la ubicación donde guardaste la clave y haz clic en Listo o Guardar.
Si seleccionas Ahora para el Vencimiento, eliminaremos la clave anterior. Si seleccionaste un momento diferente, podrás ver el tiempo que queda hasta el vencimiento de la clave debajo de su nombre.
Independientemente de cuándo vencía la clave anterior, la nueva puede usarse de inmediato.
Cuando cambias una clave publicable, el nombre de la clave de reemplazo es siempre Publishable key
. Cuando cambias una clave secreta, el nombre de la clave de reemplazo es siempre Secret key
. Cuando cambias una clave restringida, el nombre de la clave de reemplazo es el mismo que el de la que se cambió. Para cambiar el nombre de una clave secreta o restringida, haz clic en su menú de contenido adicional y selecciona Editar clave….
Elimina una clave de API secreta o restringida
Si eliminas una clave, todos los códigos que usen esa clave ya no podrán realizar llamadas 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 para desarrolladores, selecciona 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 ícono del menú de contenido adicional () en la fila de esa clave y, luego, selecciona Eliminar clave….
- Si confirmas que deseas eliminar la clave, en el cuadro de diálogo Eliminar clave de API, haz clic en Eliminar clave. De lo contrario, haz clic en Cancelar.
Crea una clave de API secreta
Para crear una clave de API secreta, haz lo siguiente:
- Abre la página de claves de API.
- Haz click en **Crear clave secreta **.
- Stripe envía un código de verificación a tu dirección de correo electrónico o mediante un mensaje de texto. (Como sucede con cualquier correo electrónico o mensaje de texto, es posible que no llegue de inmediato). Ingresa el código en el cuadro de diálogo. Si el cuadro de diálogo no continúa automáticamente, haz clic en Continuar.
- Ingresa un nombre en el campo Nombre de la clave.
- Haz click en Crear.
- El cuadro de diálogo muestra el nuevo valor de la clave. Haz clic en él para copiarlo.
- Guarda el valor de la clave. No puedes recuperarlo más tarde.
- En el campo Agregar una nota, ingresa la ubicación donde guardaste la clave y haz clic en Listo.
Crea 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:
- Abre la página de claves de API.
- Puedes crear una clave restringida desde cero o comenzar por clonar una clave restringida que ya existe.
- 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 que ya existe, en la fila de la clave que deseas clonar, haz clic en el menú de contenido adicional () y, a continuación, selecciona Duplicar clave…. En este caso, el valor predeterminado para cada permiso es su valor en la clave clonada.
- En el campo Nombre de la clave, ingresa un nombre. Si clonaste una clave existente, el nombre predeterminado es el nombre de la clave clonada.
- Para cada recurso al que deseas que acceda la nueva clave, selecciona el permiso para que esta clave lo permita. Si usas Connect, también puedes seleccionar el permiso para que esta clave lo permita cuando se acceda a las cuentas conectadas. Los permisos disponibles son Ninguno, Lectura o Escritura.
- Haz click en Crear clave.
- Stripe envía un código de verificación a tu dirección de correo electrónico o mediante un mensaje de texto. (Como sucede con cualquier correo electrónico o mensaje de texto, es posible que no llegue de inmediato). Ingresa el código en el cuadro de diálogo. Si el cuadro de diálogo no continúa automáticamente, haz clic en Continuar.
- El cuadro de diálogo muestra el nuevo valor de la clave. Haz clic en él para copiarlo.
- Guarda el valor de la clave. No puedes recuperarlo más tarde.
- En el campo Agregar una nota, ingresa la ubicación donde guardaste la clave y haz clic en Listo.
Limita las claves secretas o restringidas a una lista o rango de direcciones IP
Para limitar las solicitudes de API con una clave a una o más direcciones IP específicas o a un rango de direcciones IP, ten en cuenta 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
.
- Abre 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 revelar, haz clic en el menú de contenido adicional () y, a continuación, selecciona Administrar restricciones de IP….
- Haz clic en Restringir las direcciones IP que puedan usar la clave de API.
- Ingresa una lista o rango de direcciones IP:
- Para obtener una lista de direcciones IP, ingresa la primera dirección IP en los campos. Para cada dirección IP adicional, haz clic en Agregar otra dirección IP e ingresa la dirección.
- Para un rango de direcciones IP, haz clic en CIDR, luego ingresa el rango en la notación de enrutamiento entre dominios sin clases (CIDR). En los tres primeros campos, ingresa los tres primeros números de las direcciones IP en el rango. En los campos cuarto y quinto, ingresa el cuarto número de la primera y la última dirección en el rango, respectivamente.
- Haz click en Guardar.
Atajo
Pulsa Ctrl+V o ⌘+V con una dirección IP válida en el portapapeles para ingresar texto en todos los campos.
Cambia 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:
- Abre la página de claves de API.
- En la fila de la clave que deseas cambiar, haz clic en el menú de contenido adicional () y selecciona Editar clave….
- Si deseas cambiar el nombre, ingresa el nuevo en Nombre de la clave.
- Si deseas cambiar el texto de la nota, ingresa el nuevo texto en Nota.
- Haz click en Guardar.
Visualiza los registros de solicitudes de API
Para abrir los registros de solicitudes de API, haz clic en el menú de contenido adicional () para una clave y, luego, selecciona Ver registros de solicitudes. Si abres los registros, irás al Dashboard principal de Stripe.