Claves de API
Utiliza las claves de API para autenticar las solicitudes de API.
Stripe autentica tus solicitudes de API con 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.
Tipos de claves
By default, all accounts have a total of four API keys, two in a sandbox and two in live mode:
- Sandbox secret key: Use this key to authenticate requests on your server when you’re testing in a sandbox. By default, you can use this key to perform any API request without restriction. Reserve this key for testing and development to make sure that you don’t accidentally modify your live customers or charges.
- Sandbox publishable key: Use this key for testing purposes in your web or mobile app’s client-side code. Reserve this key for testing and development to make sure that you don’t accidentally modify your live customers or charges.
- 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.
Your secret and publishable keys are in the Dashboard in the API keys tab. 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.
Claves de API restringidas
You can generate restricted API keys in the Dashboard to enable customizable and limited access to the API. However, Stripe doesn’t offer any restricted keys by default.
When you’re logged in to Stripe, our documentation automatically populates code examples with your test 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.
La siguiente tabla muestra ejemplos generados aleatoriamente de claves de API de prueba secretas y publicables:
| Type | Value | Cuándo usar |
|---|---|---|
| Secretas | sk_ | **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 | 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. |
| Restringidas | Una cadena que comienza con rk_ | 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. |
Comparación entre el entorno de prueba y el modo activo
Todas las solicitudes de API de Stripe se realizan en el entorno de prueba o en el modo activo. Usa el entorno 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, en el entorno de prueba un 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 podrás recuperarla desde el Dashboard. En ese caso, rótala o elimínala y crea una nueva.
| Type | Cuándo usar | Objects | Cómo usar | Considerations |
|---|---|---|---|---|
| sandboxes | Use a sandbox, and its associated test API keys, as you build your integration. In a sandbox, card networks and payment providers don’t process payments. | 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. | 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 | 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. | Disputes have a more nuanced flow and a simpler testing process. Also, some payment methods have a more nuanced flow and require more steps. |
Rota una clave de API
La rotación de una clave revoca y se genera una clave de reemplazo. Puedes rotar una clave en el momento o programar la rotación luego de un determinado tiempo. Rota una clave en escenarios como los siguientes ejemplos:
- 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 rotar una clave de API, haz lo siguiente:
- Abre la página de claves de API.
- En la fila de la clave que deseas rotar, haz clic en el menú de contenido adicional () y selecciona Rotar clave.
- Elige una fecha de vencimiento en el menú desplegable Vencimiento.
- Haz clic en Rotar 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.
Al rotar una clave publicable, el nombre de la clave de reemplazo siempre es Publishable key. Al rotar una clave secreta, el nombre de la clave de reemplazo siempre es Secret key. Al rotar una clave restringida, el nombre de la clave de reemplazo es el mismo que el de la clave que se rotó. Para cambiar el nombre de una clave secreta o restringida, haz clic en su menú de contenido adicional y selecciona Editar clave.
Visualiza los registros de solicitudes de API
Para abrir los registros de solicitudes de API, haz clic en el menú de contenido adicional () de una clave y, luego, selecciona Ver registros de solicitudes. Si abres los registros, irás al Dashboard principal de Stripe.
Claves secretas y restringidas
Usa el Dashboard para crear, eliminar, mostrar y modificar claves secretas y restringidas.
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 existente, haz clic en el menú de contenido adicional () y selecciona Duplicar clave en la fila de la clave que deseas clonar. En este caso, el valor predeterminado de 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 desee acceder la nueva clave, selecciona el permiso que deseas otorgar a la clave. Si usas Connect, también puedes seleccionar el permiso para permitir esta clave cuando accedas a 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.
Elimina una clave de API secreta o restringida
Si eliminas una clave, el código que la use ya no podrá realizar llamadas API. Después de eliminar una clave, crea una nueva 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.
- Localiza la clave que quieres eliminar en la lista de Claves estándar o Claves restringidas. Haz clic en el menú de contenido adicional () en la fila de esa clave y, a continuación, selecciona Eliminar clave.
- Si estás seguro de que quieres eliminar la clave, haz clic en Eliminar clave en el cuadro de diálogo Eliminar clave de API. De lo contrario, haz clic en Cancelar.
Revela una clave de API secreta en un entorno de prueba
Con los entornos de prueba, puedes revelar una clave de API secreta todas las veces que quieras.
Para revelar una clave secreta en el entorno de prueba, haz lo siguiente:
- En el Dashboard para desarrolladores, selecciona la pestaña claves de API.
- En la lista Claves estándar, haz clic en Mostrar clave de prueba en la fila Clave secreta.
- 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
En el modo activo, Stripe solo te muestra una clave de API secreta o restringida una vez (por motivos de seguridad). Guarda la clave en un lugar 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 rotarla o eliminarla y crear otra.
No puedes revelar una clave secreta en el modo activo que hayas creado
Después de crear una clave de API secreta o restringida en modo activo, la mostramos antes de que la guardes. Debes copiar la clave antes de guardarla, ya que no podrás copiarla más tarde. Solo puedes mostrar una clave secreta predeterminada o una clave generada por una rotación programada.
Para revelar una clave secreta o restringida en el modo activo y adjuntar una nota, haz lo siguiente:
Nota
El enlace “Claves de API” se abre en modo activo.
- En el Dashboard para desarrolladores, selecciona la pestaña claves de API.
- Haz clic en Mostrar clave activa en la lista de Claves estándar o en de Claves restringidas en la fila de la clave que quieres mostrar.
- 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 selecciona Editar clave.
- En el campo Nota, ingresa la ubicación donde guardaste la clave y 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.
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
Puede especificar cualquier rango de enrutamiento entre dominios sin clases (CIDR) válido. Por ejemplo, un rango válido podría ser 100., especificado como 100.. Todas las direcciones en el rango deben comenzar con 100..
- Abre la página de claves de API.
- Haz clic en el menú de contenido adicional () en la lista de Claves estándar o de Claves restringidas en la fila de la clave que deseas mostrar, y selecciona Administrar restricciones de IP.
- Haz clic en Limitar el uso a un conjunto de direcciones IP.
- Introduce una dirección o intervalo de direcciones IP:
- Introduce una dirección IP individual en el campo Dirección IP.
- Introudce el rango de direcciones IP en la notación de enrutamiento entre dominios sin clases (CIDR). En el campo Dirección IP, introduce la primera dirección del rango. En el campo CIDR, introduce el tamaño del prefijo de red.
- También puedes seleccionar la pestaña Administrar de manera masiva e introducir direcciones IP individuales y rangos de direcciones IP, separados por espacios. Los cambios que realices en una pestaña aparecerán en la otra pestaña.
- Para agregar otra dirección o rango, haz clic en + Agregar.
- Haz click en Guardar.
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.
- Haz clic en el menú de contenido adicional () en la fila de la clave que deseas cambiar 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.
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 con las prácticas recomendadas de las claves secretas de la API.