调至内容部分
创建账户或登录
Stripe 文档徽标
/
创建账户登录

API 密钥

用 API 密钥验证 API 请求。

Stripe 会利用您账户的 API 密钥验证您的 API 请求。如果某个请求不包含有效密钥，Stripe 将返回无效请求错误。如果请求中包含已删除或过期的密钥，则 Stripe 将返回身份验证错误。

您可以通过开发人员管理平台执行 API 密钥的创建、查看、删除及轮换操作。在 API 密钥标签页中可以查看您的 v1 API 密钥。

密钥类型

默认情况下，所有账户共有四个 API 密钥：

类型说明
沙盒密钥在沙盒中，用于在服务器端对请求进行身份验证。默认情况下，您可以使用此密钥发起任意无限制的 API 请求。请将此密钥仅用于测试和开发场景，以避免意外修改真实环境中的客户数据或收款。
沙盒可发布密钥在网站或移动应用的客户端代码中用于测试请求。请将此密钥仅用于测试和开发场景，以避免意外修改真实环境中的客户数据或收款。
真实模式密钥在真实模式下，用于在服务器端对 API 请求进行身份验证。默认情况下，您可以使用此密钥发起任意无限制的 API 请求。
真实模式可发布密钥当您准备发布应用时，可在网站或移动应用的客户端代码中使用此密钥。

您的密钥与可发布密钥均可在管理平台的 API 密钥标签页中查看。如果您无法查看 API 密钥，请联系您的 Stripe 账户所有者，将您添加至团队并为您配置相应的权限。

受限 API 密钥

您可以在管理平台中生成受限 API 密钥，以启用对 API 的可自定义和限制性访问。但是，Stripe 默认不提供任何受限密钥。

如果您已登录 Stripe 账户，我们的文档会自动在代码示例中填充您的测试 API 密钥，且这些密钥值仅对您可见。如果您未登录，代码示例中会使用随机生成的 API 密钥，您可将其替换为自己的测试密钥；您也可以登录，查看自动填充了您的测试 API 密钥的代码示例。

API 密钥示例

下表展示了随机生成的密钥与可发布密钥示例：

类型值何时使用
私钥sk_test_BQokikJOvBiI2HlWgH4olfQ2在服务器端：必须要做到保密并安全地存储在您的网页或移动应用的服务器端代码内（例如在环境变量或凭据管理系统中），然后才能调用 Stripe API。请勿在网站上公开此密钥或将其嵌入移动应用程序中。
可公开pk_test_TYooMQauvdEDq54NiTphI7jx在客户端：可在网站或移动应用的客户端代码（例如 checkout.js）中公开使用，用于安全地收集支付信息（例如通过 Stripe Elements 组件）。默认情况下，Stripe Checkout 会自动安全地收集支付信息。
已限制以 rk_test_ 开头的字符串在微服务中：必须是私钥，并安全地存储在您的微服务代码中，才能调用 Stripe API。请勿在网站上公开此密钥或将其嵌入移动应用程序中。

密钥安全防护

任何人都可以利用您的真实模式密钥，代表您的账户发起 API 调用，例如创建收款或执行退款操作。请遵循这些最佳实践，确保您的 API 密钥安全。

沙盒与真实模式

所有 Stripe API 请求均在沙盒或真实模式中执行。您可以在沙盒中访问测试数据，在真实模式中访问真实的账户数据。两种模式各有一套独立的 API 密钥，且不同模式下的对象无法互通访问。例如，沙盒中的产品对象无法用于真实模式下的支付。

真实模式密钥访问

真实模式下的 API 密钥或受限 API 密钥仅可被查看一次。如果不慎遗失，将无法从管理平台中找回。遇此情况，您可以先执行轮换或删除操作，再重新生成新密钥。

类型何时使用对象如何使用考虑
沙盒使用沙盒及其关联的测试 API 密钥，和构建集成时一样。在沙盒中，卡组织和支付处理商不处理付款。API 调用返回的是模拟的对象。例如，您可以检索并使用测试用的 account、payment、customer、charge、refund、transfer、balance 和 subscription 对象。使用测试信用卡和账户。您不能接受真实支付方式或使用真实账户。Identity 不执行任何验证检查。此外，Connect account objects 不返回敏感字段。
真实模式当您准备好启动您的集成并真正收款时，使用真实模式及其关联的真实 API 密钥。在真实模式下，卡组织和支付处理商确实会处理付款。API 调用返回的是真实对象。例如，您可以检索并使用真实的 account、payment、customer、charge、refund、transfer、balance 和 subscription 对象。接受真实信用卡，可使用客户账户。您可以为信用卡和账户接受实际付款授权、收款并捕获。争议流程也更加细致，但测试流程较为简单。此外，有些支付方式的支付流程更加细致，要求更多步骤。

组织 API 密钥

如果您在组织中有多个 Stripe 商家账户，您可以在组织级别配置单个 API 密钥。组织级别 API 密钥提供以下功能：

  • 任意账户访问权限：可以使用组织 API 密钥，访问组织内任意账户的资源。
  • 精细化权限控制：可以对组织 API 密钥进行权限限制，使其仅拥有针对特定资源的只读或读写权限。
  • 集中化管理：您可以在组织的管理平台的 API 密钥标签页中，创建并管理组织 API 密钥。

行为

组织 API 密钥的行为与账户级 API 密钥不同，包括：

  • 他们没有公钥。将所有组织 API 密钥视为私钥。
  • 无论其权限级别如何，它们都具有相同的 sk_org 前缀。
  • 使用组织 API 密钥发出的所有 API 请求都必须包含 Stripe-Context 标头，以识别受影响的账户。
  • 使用组织 API 密钥发出的所有 API 请求都必须包含 Stripe-Version 头，以确保贵组织集成的一致性和可预测性。

使用组织 API 密钥

使用组织 API 密钥时，还必须：

  • 通过包含 Stripe-Version 头来指定 API 版本。使用 Stripe SDK 时，SDK 会自动设置 API 版本。
  • 通过包含 Stripe-Context 头来识别受 API 请求影响的账户。

例如，给定以下组织结构：

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

您可以使用组织 API 密钥访问独立账户的余额。也可以使用相同的密钥对平台 Connect 子账户进行相同的调用。

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}}
"

在上述代码示例中，请将 {{CONTEXT}} 替换为对应的值：

  • 对于独立账户，请使用 acct_1aTnTtAAB0hHJ26p。
  • 对于 Connect 子账户，请使用能够同时标识平台和关联账户的路径，格式参考 acct_1R3fqDP6919yCiFv/acct_1032D82eZvKYlo2C。

在使用组织密钥的任何 API 请求中，您必须使用上下文和 API 版本来指定相关账户。

组织没有可发布 API 密钥，因为它们无法接受付款。您可以使用组织 API 密钥，为组织内的任意账户创建 PaymentIntent，但在执行客户端操作时，必须使用已有的、特定于账户的可发布密钥。

私钥和受限密钥

您可以通过管理平台，执行密钥和受限密钥的创建、查看、修改、删除及轮换操作。

创建 API 密钥

您可以创建 API 密钥或受限 API 密钥。其中，受限 API 密钥仅拥有您所指定的访问权限等级。

创建 API 密钥

  1. 在 API 密钥标签页中，点击创建密钥。
  2. 在弹出的对话框中，输入 Stripe 通过邮件或短信发送给您的验证码。如果对话框未自动跳转，可点击继续。
  3. 在密钥名称字段中输入名称，然后点击创建。
  4. 点击密钥内容即可复制该密钥。
  5. 保存密钥的值。以后无法再检索到它。
  6. 在添加备注字段中输入您保存该密钥的位置，然后点击完成。

创建受限 API 密钥

  1. 在 API 密钥标签页中，请执行以下任一操作：
    • 如需创建新的受限密钥，点击创建受限密钥。该密钥的所有权限默认均为无权限。
    • 如需克隆现有密钥，点击目标密钥对应的溢出菜单 ()，然后选择复制密钥。新克隆密钥的各项权限默认与被克隆的密钥保持一致。
  2. 在密钥名称字段中输入名称。如果您是克隆现有密钥，新密钥的默认名称将与被克隆的密钥名称一致。
  3. 针对您希望新密钥能够访问的每一项资源，选择对应的权限：无、只读或读写。如果您使用了 Connect，还可以设置该密钥在访问 Connect 子账户时所拥有的权限。
  4. 点击创建密钥。
  5. 在弹出的对话框中，输入 Stripe 通过邮件或短信发送给您的验证码。如果对话框未自动跳转，可点击继续。
  6. 点击密钥内容即可复制该密钥。
  7. 保存密钥的值。以后无法再检索到它。
  8. 在添加备注字段中输入您保存该密钥的位置，然后点击完成。

显示 API 密钥

您可以在沙盒或真实模式中显示 API 密钥或受限 API 密钥。

在真实模式下，出于安全考虑，Stripe 仅会向您展示一次 API 密钥。请将密钥妥善保存在不会丢失的位置。为了方便记忆存储位置，您可以在管理平台中为该密钥添加备注。如果不慎遗失密钥，您可以执行轮换或删除操作，再重新生成新密钥。

显示真实模式下的密钥

在真实模式下创建私钥或受限 API 密钥后，我们会在您保存它之前显示它。保存前必须复制密钥，因为之后不能再复制。您只能显示默认私钥或由预定轮换产生的密钥。

在沙盒中显示 API 密钥

  1. 在 API 密钥标签页的标准密钥列表中，点击密钥行对应的显示测试密钥。您可以不限次数地查看该 API 密钥。
  2. 点击密钥内容即可复制该密钥。
  3. 保存密钥的值。
  4. 点击隐藏测试密钥。

在真实模式下显示密钥或受限 API 密钥

  1. 在真实模式下的 API 密钥标签页中，在标准密钥或受限密钥列表内，点击您想要查看的密钥对应的显示真实密钥。
  2. 点击密钥内容即可复制该密钥。
  3. 保存密钥的值。
  4. 点击隐藏测试密钥。
  5. 点击目标密钥对应的溢出菜单 ()，然后选择编辑密钥，为该密钥添加备注。
  6. 在备注字段中输入您保存该密钥的位置，然后点击保存。

注意

在 Stripe 推出此功能之前创建的密钥，在被查看后不会自动隐藏，您需要点击隐藏真实密钥，手动隐藏这些密钥。

限制 API 密钥的访问 IP 地址

您可以将 API 密钥或受限 API 密钥的访问权限，限制在特定的 IP 地址段或一个或多个具体的 IP 地址范围内。

所填 IP 地址必须采用 IPv4 协议，且您可以指定任意有效的 CIDR 地址段。例如，您可以将 100.10.38.0 - 100.10.38.255 这个地址段表示为 100.10.38.0/24，该地址段内的所有 IP 地址均以 100.10.38 开头。

  1. 在 API 密钥标签页的标准密钥或受限密钥列表中，点击您想要显示的密钥对应的溢出菜单 ()。

  2. 选择管理 IP 限制 > 限制仅允许指定 IP 地址访问。

  3. 请执行以下任一操作：

    • 在 IP 地址字段中输入单个 IP 地址。
    • 如需添加 IP 地址段，请在 IP 地址字段中输入该地址段的起始地址（采用无类别域间路由 (CIDR) 表示法），并在 CIDR 字段中输入网络前缀长度。

    您也可以在批量管理标签页中输入单个 IP 地址或 IP 地址段（多个地址之间用空格分隔）。在任一标签页中进行的修改，都会同步显示在另一标签页中。

  4. 如需添加其他 IP 地址或 IP 地址段，点击 + 添加。

  5. 点击保存。

修改 API 密钥的名称或备注

  1. 在 API 密钥标签页中，点击您想要修改的密钥对应的溢出菜单（）。
  2. 选择编辑密钥。
  3. 请执行以下操作：
    • 如需修改密钥名称，可在密钥名称字段中输入新的名称。
    • 如需修改备注内容，可在备注字段中输入新的备注文本。
  4. 点击保存。

删除 API 密钥

如果您删除一个 API 密钥或受限 API 密钥，必须重新生成新密钥，并更新所有使用该已删除密钥的代码。所有依赖已删除密钥的代码将无法再发起 API 调用。

注意

不能删除公钥。

  1. 在API 密钥标签页的标准密钥或受限密钥列表中，点击您想要删除的密钥对应的溢出菜单 ()。
  2. 选择删除密钥。
  3. 在弹出的对话框中，点击删除密钥；如果您不想继续执行删除操作，可点击取消。

轮换 API 密钥

轮换 API 密钥会吊销原密钥，并生成一个可立即使用的新密钥。您也可以为 API 密钥设置定时轮换计划。替换后的密钥命名规则如下：

  • 替换后的可发布密钥名称固定为可发布密钥。
  • 替换后的密钥名称始终为密钥。
  • 替换后的受限密钥名称与被轮换的密钥名称相同。

您可以通过编辑操作，修改 API 密钥或受限 API 密钥的名称。

以下情境需要执行 API 密钥轮换操作：

  • 如果您在真实模式下遗失了 API 密钥或受限 API 密钥，且无法从管理平台中找回。
  • 如果 API 密钥或受限 API 密钥遭到泄露，您需要吊销该密钥以阻止所有可能利用此密钥发起的恶意 API 请求。
  • 如果您的政策要求按特定间隔轮换密钥。

轮换 API 密钥

  1. 在 API 密钥标签页中，点击您想要轮换的密钥对应的溢出菜单（）。
  2. 选择轮换密钥。
  3. 从有效期下拉菜单中选择一个有效期。如果选择立即，旧密钥将被删除；如果指定具体时间，密钥名称下方会显示该密钥的剩余有效时长。
  4. 点击轮换 API 密钥。
  5. 点击密钥内容即可复制该密钥。
  6. 保存密钥的值。以后无法再检索到它。
  7. 在添加备注字段中输入您保存该密钥的位置，然后点击保存或完成。

查看 API 请求日志

如需打开 API 请求日志，请点击任意密钥对应的溢出菜单 ()，然后选择查看请求日志。打开日志后，系统会将您重定向至 Stripe 管理平台。

相关指南
测试您的集成应用
测试用例