Ir a contenido
Crea una cuenta o inicia sesión
Logotipo de la documentación de Stripe
/
Crear cuentaIniciar sesión
Resumen
Control de versiones
Actualiza tu versión de la API
Essentials
Herramientas
Stripe para Visual Studio Code
Funciones
Alertas de estado de StripeCargas de archivos
Soluciones de IA
Protocolo de Contexto del ModeloCrea flujos de trabajo para la facturación SaaS con IA agéntica
Seguridad y privacidad
Rastreo web de Stripebot
Ampliar Stripe
Socios
Certificación de socio

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.

Utiliza el Dashboard para desarrolladores para crear, revelar, eliminar y rotar claves API. Puedes acceder a tus claves API v1 en la pestaña Claves API.

Tipos de claves

De forma predeterminada, todas las cuentas tienen un total de cuatro claves API:

TipoDescripción
Clave secreta del entorno de pruebasAutentica peticiones en tu servidor cuando estés haciendo pruebas en un entorno de pruebas. De forma predeterminada, puedes usar esta clave para realizar cualquier petición a la API sin restricciones. Reserva esta clave para pruebas y desarrollo para asegurarte de no modificar accidentalmente tus clientes o cargos activos.
Clave publicable del entorno de pruebasPrueba las solicitudes en el código del lado del cliente de tu aplicación web o móvil. Reserva esta clave para pruebas y desarrollo para asegurarte de no modificar accidentalmente tus clientes o cargos activos.
Clave secreta en modo activoUsa 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 activoUsa 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.

Tus claves secretas y publicables están en la pestaña claves API del Dashboard. Si no puedes ver tus claves API, pídele al propietario de tu cuenta de Stripe que te añada a su equipo con los permisos adecuados.

Claves de API restringidas

Puedes generar claves de API restringidas en el Dashboard para permitir un acceso limitado y personalizable a la API. Sin embargo, Stripe no ofrece ninguna clave restringida de forma predeterminada.

Si has iniciado sesión en Stripe, nuestra documentación rellena los ejemplos de código con tus claves API de prueba. Solo tú puedes ver estos valores. Si no ha iniciado sesión, nuestros ejemplos de código incluyen claves API generadas aleatoriamente que puedes sustituir por tus claves de prueba. O puedes iniciar sesión para ver los ejemplos de código rellenados con tus claves API de prueba.

Ejemplos de claves de API

La siguiente tabla muestra ejemplos generados aleatoriamente de claves secretas y publicables:

TipoValorCuándo usarlo
Secretask_test_BQokikJOvBiI2HlWgH4olfQ2En 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.
Publicablepk_test_TYooMQauvdEDq54NiTphI7jxDel lado del cliente: están a disposición del público en el código del lado del cliente de tu aplicación web o para dispositivos móviles (como checkout.js) para recopilar información de pago de forma segura, como con Stripe Elements. De forma predeterminada, Stripe Checkout reúne de forma segura los datos de pago.
RestringidoUna 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 del modo activo para realizar una llamada a la API en nombre de tu cuenta, como crear un aceptar pagos o realizar un reembolso. Sigue estas prácticas recomendadas para mantener seguras tus claves API secretas.

Entorno de prueba frente a modo activo

Todas las solicitudes de API de Stripe se realizan en el sandbox o en live mode. Utiliza 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 API y los objetos de un modo no están disponibles en el otro. Por ejemplo, un objeto de producto de entorno 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.

TipoCuándo usarloObjetosCómo se usaConsideraciones
Entornos de pruebaUsa un entorno de prueba y sus claves de API de prueba asociadas a medida que crees tu integración. En un entorno 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.Utiliza cuentas y tarjetas de crédito de prueba. No puedes aceptar métodos de pago reales ni trabajar con cuentas reales.Identidad no efectúa comprobaciones de verificación. Además, los objetos de cuentas de Connect no devuelven campos confidenciales.
Modo activoUsa 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 requieren más pasos.

Claves de API de organización

Si tienes varias cuentas de empresa de Stripe en una organización, puedes configurar una única clave API a nivel de organización. Las claves de API de nivel de organización proporcionan la siguiente funcionalidad:

  • Acceso a cualquier cuenta: puedes usar las claves API de la organización para acceder a los recursos de cualquier cuenta dentro de la organización.
  • Permisos detallados: restringe las claves API organizativas para otorgar permiso de lectura o escritura solo a recursos específicos.
  • Gestión centralizada: crea y gestiona claves API organizativas en la pestaña claves API del Dashboard de tu organización.

Comportamiento

Las claves de API de organización se comportan de manera diferente a las claves de API de nivel de cuenta, incluyendo:

  • No tienen una clave publicable. Trata todas las claves de API de la organización como claves secretas.
  • Todos tienen el mismo prefijo sk_org, independientemente de sus niveles de permiso.
  • Todas las peticiones de API realizadas con una clave de API de organización deben incluir el encabezado Stripe-Context para identificar la cuenta afectada.
  • Todas las peticiones de API realizadas con una clave de API de la organización deben incluir el encabezado Stripe-Version para garantizar la coherencia y la previsibilidad en todas las integraciones de tu organización.

Usa claves API de organización

Cuando usas una clave de API de organización, también debes:

  • Especifica una versión de la API incluyendo el encabezado Stripe-Version. Cuando se usa un SDK de Stripe, el SDK establece automáticamente la versión de la API.
  • Identifica la cuenta afectada por la petición de la API incluyendo el encabezado Stripe-Context.

Por ejemplo, dada la siguiente estructura organizativa:

Organization (org_6SD3oI0eSQemPzdmaGLJ5j6)
  ├── Platform account  (acct_1R3fqDP6919yCiFv)
  |   └── Connected account (acct_1032D82eZvKYlo2C)
  └── Standalone account (acct_1aTnTtAAB0hHJ26p)

Puedes utilizar la clave de la API de la organización para acceder al saldo de la cuenta independiente. También puedes usar la misma clave para hacer la misma llamada para la cuenta conectada a la plataforma.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/balance \
  -u {{ORG_SECRET_KEY}}: \
  -H "Stripe-Version: {{STRIPE_API_VERSION}}" \
  -H "Stripe-Context: 
{{CONTEXT}}
"

En el ejemplo de código anterior, reemplaza {{CONTEXT}} por el valor correspondiente:

  • Para la cuenta independiente, usa acct_1aTnTtAAB0hHJ26p.
  • Para la cuenta conectada, utiliza una ruta que identifique tanto a la plataforma como a la cuenta conectada, siguiendo el formato acct_1R3fqDP6919yCiFv/acct_1032D82eZvKYlo2C.

Debes especificar la cuenta relevante utilizando el contexto y la versión API en cualquier solicitud de API mediante una clave de organización.

Las empresas no tienen claves de API para publicar porque no pueden aceptar pagos. Puedes usar la clave API de tu organización para crear un PaymentIntent para cualquier cuenta de tu organización, pero debes usar claves para publicar específicas de la cuenta existentes para las operaciones con el cliente.

Claves secretas y restringidas

Usa el Dashboard para crear, revelar, modificar, eliminar y rotar claves secretas y restringidas.

Crear una clave API

Puedes crear una clave API secreta o una clave API restringida. Una clave API restringida solo permite el nivel de acceso que especifiques.

Para crear una clave de API secreta, haz lo siguiente:

  1. En la pestaña Claves API, haz clic en Crear clave secreta.
  2. En el cuadro de diálogo, introduce el código de verificación que Stripe te enviará por correo electrónico o mensaje de texto. Si el cuadro de diálogo no aparece automáticamente, haz clic en Continuar.
  3. Introduce un nombre en el campo Nombre de la clave y, a continuación, haz clic en Crear.
  4. Haz clic en el valor clave para copiarlo.
  5. Guarda el valor de la clave. No podrás recuperarlo más tarde.
  6. En el campo Añadir una nota, introduce la ubicación donde has guardado la clave y haz clic en Listo.

Para crear una clave de API restringida, haz lo siguiente:

  1. En la pestaña claves API, realiza una de las siguientes acciones:
    • Para crear una nueva clave restringida, haz clic en Crear clave restringida. El valor predeterminado para todos los permisos es Ninguno.
    • Para copiar una clave existente, haz clic en el menú adicional () y, a continuación, elige Duplicar clave. En este caso, el valor predeterminado para cada permiso es su valor en la clave copiada.
  2. Introduce un nombre en el campo Nombre de clave. Si has copiado una clave existente, el nombre predeterminado es el nombre de la clave copiada.
  3. 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.
  4. Haz clic en Crear clave.
  5. En el cuadro de diálogo, introduce el código de verificación que Stripe te enviará por correo electrónico o mensaje de texto. Si el cuadro de diálogo no aparece automáticamente, haz clic en Continuar.
  6. Haz clic en el valor clave para copiarlo.
  7. Guarda el valor de la clave. No podrás recuperarlo más tarde.
  8. En el campo Añadir una nota, introduce la ubicación donde has guardado la clave y haz clic en Listo.

Revelar una clave API

Puedes revelar una clave API secreta o restringida en un entorno de pruebas o en 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.

Revelar claves secretas en modo activo

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 porque no podrás copiarla más tarde. Solo puedes revelar una clave secreta predeterminada o una clave generada mediante una rotación programada.

Para revelar una clave API secreta en un entorno de pruebas

  1. En la pestaña claves API, en la lista Claves Standard, haz clic en Revelar clave de prueba en la fila Clave secreta. Puedes revelar la clave API secreta tantas veces como quieras.
  2. Haz clic en el valor clave para copiarlo.
  3. Guarda el valor de la clave.
  4. Haz clic en Ocultar clave de prueba.

Cómo revelar una clave de API secreta o restringida en modo activo

  1. En la pestaña Claves API en modo activo, en la lista Claves estándar o Claves restringidas, haz clic en Revelar clave activa para la clave que quieras revelar.
  2. Haz clic en el valor clave para copiarlo.
  3. Guarda el valor de la clave.
  4. Haz clic en Ocultar clave de prueba.
  5. Haz clic en el menú adicional () y elige Editar clave para la clave en la que quieres añadir una nota.
  6. En el campo Nota, introduce la ubicación donde guardaste la clave y luego haz clic en Guardar.

Nota

Las claves que has creado antes de que Stripe introdujera esta función no se ocultan automáticamente cuando se revelan. Debes ocultarlas de forma manual haciendo clic en Ocultar clave activa.

Limitar una clave API a determinadas direcciones IP

Puedes limitar una clave API secreta o restringida a un rango de direcciones IP o a una o más direcciones IP específicas.

Las direcciones IP deben usar el protocolo IPv4. Puedes especificar cualquier rango de CIDR válido. Por ejemplo, un rango válido podría ser 100.10.38.0 - 100.10.38.255, especificado como 100.10.38.0/24. Todas las direcciones del rango deben comenzar por 100.10.38.

  1. En la pestaña Claves API, en la fila de la clave que deseas eliminar, haz clic en el menú adicional () y elige Claves estándar o Claves restringidas.

  2. Selecciona Gestionar restricciones de IP > Limitar el uso a un conjunto de direcciones IP.

  3. Realiza una de las siguientes acciones:

    • Introduce una dirección IP particular en el campo Dirección IP.
    • Para un rango de direcciones IP, introduce la primera dirección en la nota 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 particulares y rangos, separados por espacios. Los cambios que realices en una pestaña se harán también en la otra pestaña.

  4. Para añadir otra dirección o rango de IP, haz clic en + Añadir.

  5. Haz clic en Guardar.

Cambiar el nombre o la nota de una clave de API

  1. En la pestaña Claves API, haz clic en el menú adicional () para ver la clave que quieres cambiar.
  2. Selecciona Editar clave.
  3. Haz lo siguiente:
    • Para cambiar el nombre, introduce un nuevo nombre en el campo Nombre de la clave.
    • Para cambiar el texto de la nota, introduce el nuevo texto de la nota en el campo Nota.
  4. Haz clic en Guardar.

Eliminar una clave API

Si eliminas una clave API secreta o restringida, debes crear una nueva y actualizar cualquier código que utilice la clave eliminada. Cualquier código que utilice la clave eliminada ya no podrá realizar llamadas a la API.

Nota

No puedes eliminar una clave publicable.

  1. En la pestaña Claves API, en la fila de la clave que deseas eliminar, haz clic en el menú adicional () y elige Claves estándar o Claves restringidas.
  2. Selecciona Eliminar clave.
  3. En el cuadro de diálogo, haz clic en Eliminar clave. Si ya no quieres eliminar la clave, haz clic en Cancelar.

Rotar una clave API

Al rotar una clave API se revoca y se genera una clave de reemplazo lista para usarse de inmediato. También puedes programar que una clave API rote después de un cierto tiempo. La clave de reemplazo se nombra de la siguiente manera:

  • El nombre de la clave de reemplazo para publicar siempre es Clave para publicar.
  • El nombre de la clave secreta siempre es Clave secreta.
  • El nombre de la clave restringida de reemplazo es el mismo que el de la clave rotada.

Puedes volver a nombrar una clave API secreta o restringida editando la clave.

Rota una clave API en situaciones como:

  • Si pierdes una clave API secreta o restringida en modo activo y no puedes recuperarla desde el Dashboard.
  • Si una clave API secreta o restringida se ve comprometida, debes revocarla para bloquear cualquier solicitud de API potencialmente maliciosa que pueda usarla.
  • Si tu política requiere que se cambien las claves en intervalos determinados.

Para rotar una clave API

  1. En la pestaña Claves API, haz clic en el menú adicional () de la clave que quieres rotar.
  2. Selecciona Rotar clave.
  3. Selecciona una fecha de caducidad en el menú desplegable Caducidad. Si eliges Ahora, se elimina la clave antigua. Si especificas una hora, el tiempo restante hasta que caduque la clave se mostrará debajo del nombre de dicha clave.
  4. Haz clic en Rotar clave API.
  5. Haz clic en el valor clave para copiarlo.
  6. Guarda el valor de la clave. No podrás recuperarlo más tarde.
  7. En el campo Añadir una nota, introduce la ubicación donde guardaste la clave y luego haz clic en Guardar o Listo.

Ver registros de solicitudes de la API

Para abrir los registros de solicitudes de API, haz clic en el menú adicional () de cualquier clave y, a continuación, elige Ver registros de solicitudes. Al abrir los registros, regresarás al Dashboard de Stripe.

Guías relacionadas
Prueba tu integración
Pruebas de casos de uso