Ir a contenido
Crea una cuenta o Inicia sesión
Logotipo de Stripe Docs
/
Crear una cuentaIniciar sesión
Resumen
Control de versiones
Actualiza tu versión de API
Essentials
Herramientas
Stripe para Visual Studio Code
Funcionalidades
Alertas de estado de StripeCargas de archivos
Soluciones de IA
Protocolo de contexto del modeloCrea flujos de trabajo de facturación para SaaS con IA de agente
Seguridad y privacidad
Araña web Stripebot
Amplía Stripe
Socios
Certificación de socio

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 para desarrolladores con el fin de 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 de entorno de pruebasAutentica solicitudes en tu servidor cuando estás haciendo pruebas en un entorno de pruebas. De forma predeterminada, puedes usar esta clave para realizar cualquier solicitud API sin restricciones. Reserva esta clave para pruebas y desarrollo a fin de asegurarte de no modificar accidentalmente tus clientes o cargos activos.
Clave publicable de 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 a fin de asegurarte de no modificar accidentalmente tus clientes o cargos activos.
Clave secreta modo activoAutentica 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 modo activoCuando estés listo para lanzar tu aplicación, usa esta clave en el código del lado del 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 titular de tu cuenta de Stripe que te agregue a su equipo con los permisos adecuados.

Claves de API restringidas

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

Si iniciaste sesión en Stripe, nuestra documentación completa los ejemplos de código con tus claves API de prueba. Solo tú puedes ver estos valores. Si no iniciaste sesión, nuestros ejemplos de código incluyen claves API generadas aleatoriamente que puedes reemplazar con tus claves de prueba. O puedes iniciar sesión para ver los ejemplos de código completados con tus claves API de prueba.

Ejemplos de claves API

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

TipoValorCuándo usar
Secretassk_test_BQokikJOvBiI2HlWgH4olfQ2**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.
Publicablespk_test_TYooMQauvdEDq54NiTphI7jxDel lado del cliente: son de acceso 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 recopila la información de pago de forma segura.
RestringidasUna 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

Cualquiera puede usar tu clave secreta en modo activo para realizar una llamada API en nombre de tu cuenta, por ejemplo, aceptar pagos o realizar un reembolso. Mantén tus claves API secretas seguras con estas prácticas recomendadas.

Comparación entre el entorno de prueba y el modo activo

Todas las solicitudes 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 con el fin de acceder a los datos de la cuenta real. Cada modo tiene su propio conjunto de claves API. Los objetos en un modo no son accesibles en el otro. Por ejemplo, un objeto producto del entorno de prueba no puede formar parte de un pago en modo activo.

Acceso a las claves en modo activo

Solo puedes 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.

TipoCuándo usarObjetosCómo usarConsideraciones
Entornos de pruebaUsa un entorno de prueba y sus claves de API de prueba asociadas mientras creas tu integración. En el entorno de prueba, las redes de tarjetas y los proveedores de servicios de pago 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 account de Connect no devuelven campos confidenciales.
Modo activoCuando 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 requieren más pasos.

Claves de API de la organización

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

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

Comportamiento

Las claves de API de la organización se comportan de manera diferente a las claves de API a nivel de la cuenta, e incluyen lo siguiente:

  • No tienen una clave publicable. Debes tratar todas las claves de API de la organización como claves secretas.
  • Todas tienen el mismo prefijo sk_org, independientemente de sus niveles de permisos.
  • Todas las solicitudes de API realizadas con una clave de API de la organización deben incluir el encabezado Stripe-Context para identificar la cuenta afectada.
  • Todas las solicitudes 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 de API de la organización

Cuando usas una clave de API de la organización, también debes hacer lo siguiente:

  • Para especificar una versión de API, incluye el encabezado Stripe-Version. Al usar un SDK de Stripe, el SDK establece automáticamente la versión de la API.
  • Identifica la cuenta afectada por la solicitud de la API. Para ello, incluye 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 usar la clave de API de la organización para acceder al saldo de la cuenta independiente. También puedes usar la misma clave para realizar la misma llamada correspondiente a la cuenta conectada de 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, utilizar una ruta que identifique tanto a la plataforma como a la cuenta conectada, siguiendo el formato acct_1R3fqDP6919yCiFv/acct_1032D82eZvKYlo2C.

Debes especificar la cuenta correspondiente usando el contexto y la versión API en cualquier solicitud API que use una clave de organización.

Las organizaciones no tienen claves API publicables porque no pueden aceptar pagos. Esto significa que puedes usar la clave API de tu organización con el fin de crear PaymentIntent para cualquier cuenta de tu organización, pero debes usar claves publicables específicas de la cuenta existentes para las operaciones del lado del 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 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, ingresa el código de verificación que Stripe te envía por correo electrónico o mensaje de texto. Si el cuadro de diálogo no continúa automáticamente, haz clic en Continuar.
  3. Ingresa un nombre en el campo Nombre de la clave y luego haz clic en Crear.
  4. Haz clic en el valor clave para copiarlo.
  5. Guarda el valor de la clave. No puedes recuperarlo más tarde.
  6. En el campo Agregar una nota, ingresa la ubicación donde guardaste 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 clonar una clave que ya existe, haz clic en el menú de opciones () y, a continuación, selecciona Duplicar clave. En este caso, el valor predeterminado para cada permiso es su valor en la clave clonada.
  2. 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.
  3. Para cada recurso al que deseas que acceda la nueva clave, selecciona el permiso apropiado: Ninguno, Lectura o Escritura. Si usas Connect, también puedes seleccionar el permiso para que esta clave lo permita cuando se acceda a las cuentas conectadas.
  4. Haz click en Crear clave.
  5. En el cuadro de diálogo, ingresa el código de verificación que Stripe te envía por correo electrónico o mensaje de texto. Si el cuadro de diálogo no continúa automáticamente, haz clic en Continuar.
  6. Haz clic en el valor clave para copiarlo.
  7. Guarda el valor de la clave. No puedes recuperarlo más tarde.
  8. En el campo Agregar una nota, ingresa la ubicación donde guardaste la clave y haz clic en Listo.

Mostrar una clave API

Puedes revelar una clave API secreta o una clave API restringida en un entorno de prueba o modo activo.

En modo activo, Stripe te muestra una clave API solo una vez (por motivos de seguridad). Guarda la clave en un lugar donde no la pierdas. Para recordarte 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.

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, 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 API secreta en un entorno de prueba

  1. En la pestaña Claves API, en la lista Claves estándares, 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.

Para 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ándares o Claves restringidas, haz clic en Revelar clave activa para la clave que quieres 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ú de opciones () y selecciona Editar clave para la clave a la que deseas agregar una nota.
  6. En el campo Nota, ingresa la ubicación donde guardaste la clave y, luego, haz clic en Guardar.

Nota

Las claves que creaste antes de que Stripe incorporara esta funcionalidad no se ocultan automáticamente cuando se revelan. Debes ocultarlas de forma manual haciendo clic en Ocultar clave activa.

Limitar una clave API a ciertas 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 IP en el rango deben comenzar con 100.10.38.

  1. En la pestaña Claves API, en la lista Claves estándares o Claves restringidas, haz clic en el menú de opciones () y selecciona la clave que deseas revelar.

  2. Selecciona Gestionar restricciones 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 el rango de direcciones IP, introduce la primera dirección del rango que usa la notación de enrutamiento entre dominios sin clases (CIDR) en el campo Dirección IP. Introduce el tamaño del prefijo de red en el campo CIDR.

    También puedes introducir direcciones y rangos de IP particulares en la pestaña Administrar de manera masiva, separados por espacios. Los cambios que realices en una pestaña aparecerán en la otra pestaña.

  4. Para agregar otra dirección o rango IP, haz clic en + Agregar.

  5. Haz click en Guardar.

Cambia el nombre o la nota de una clave API

  1. En la pestaña Claves API, haz clic en el menú de opciones () para ver la clave que quieres cambiar.
  2. Selecciona Editar clave.
  3. Haz lo siguiente:
    • Para cambiar el nombre, ingresa un nuevo nombre en el campo Nombre de la clave.
    • Si desea cambiar el texto de la nota, ingresa el nuevo texto en el campo Nota.
  4. Haz click 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 API.

Nota

No puedes eliminar una clave publicable.

  1. En la pestaña claves API en la lista Claves estándaresoClaves restringidas, haz clic en el menú de opciones () para eliminar la clave que quieras.
  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.

Rota una clave de API

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

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

Puedes cambiar el nombre de una clave de API secreta o restringida editando la clave.

Rotar una clave API en escenarios como los siguientes:

  • 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, tienes que revocarla para bloquear cualquier solicitud API potencialmente nociva que puedan usar la clave.
  • Si tu política requiere rotar las claves a ciertos intervalos.

Para rotar una clave API

  1. En la pestaña Claves API, haz clic en el menú de opciones () para ver la clave que quieres rotar.
  2. Selecciona Rotar clave.
  3. Selecciona una fecha de vencimiento en el menú desplegable Vencimiento. Si eliges Ahora, se elimina la clave antigua. Si especificas una hora, el tiempo restante hasta que venza la clave se muestra debajo del nombre de la clave.
  4. Haz clic en Rotar clave de API.
  5. Haz clic en el valor clave para copiarlo.
  6. Guarda el valor de la clave. No puedes recuperarlo más tarde.
  7. En el campo Agregar nota, ingresa la ubicación donde guardaste la clave y, luego, haz clic en Guardar o Listo.

Ver registros de solicitudes API

Para abrir los registros de solicitudes API, haz clic en el menú de opciones () de una clave y, luego, selecciona Ver registros de solicitudes. Si abres los registros, irás al Dashboard de Stripe.

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