On this page

Permissions 参考

Stripe Apps 使用权限系统控制对 Stripe API 资源的访问。每个权限必须在应用 manifest 中明确声明，并附有清晰的目的说明。用户在安装应用时批准这些权限。

管理 Permissions

声明 Permissions

在 stripe-app.json manifest 中添加 permissions：

{
  "permissions": [
    {
      "permission": "customer_read",
      "purpose": "Read customer profiles to sync with Brevo contacts"
    },
    {
      "permission": "customer_write",
      "purpose": "Update customer metadata with Brevo sync status"
    }
  ]
}

通过 CLI 授予 Permissions

在开发过程中，您可以使用 Stripe CLI 授予 permissions：

# 授予特定权限
stripe apps grant permission "customer_read" \
  --purpose "Read customer profiles to sync with Brevo contacts"

# 授予多个权限
stripe apps grant permission "charge_read" \
  --purpose "Access payment data for event tracking"

stripe apps grant permission "event_read" \
  --purpose "Subscribe to real-time Stripe events"

Permissions 最佳实践

最小必要原则：只请求应用实际使用的权限
清晰目的：编写非技术用户能理解的目的说明
为 read+write 提供理由：如果同时需要读写权限，请在每个目的中说明原因
定期审查：更新应用时移除不再需要的权限

Tip

请求过多权限是应用被拒绝最常见的原因之一。只请求您需要的权限。

按产品分类的 Permissions

核心

资源	Permission	描述
Account	`account_read`	读取账户详情和设置
Account	`account_write`	更新账户设置
Balance	`balance_read`	查看账户余额和交易
Customer	`customer_read`	读取客户档案、元数据和支付方式
Customer	`customer_write`	创建、更新或删除客户记录
Event	`event_read`	读取并订阅账户事件
File	`file_read`	读取已上传文件和文件链接
File	`file_write`	上传文件并创建文件链接
Mandate	`mandate_read`	读取支付授权
Product	`product_read`	读取产品目录和价格
Product	`product_write`	创建、更新或删除产品和价格
Token	`token_read`	读取已 tokenize 的支付数据
Webhook Endpoint	`webhook_endpoint_read`	读取 webhook endpoint 配置
Webhook Endpoint	`webhook_endpoint_write`	创建、更新或删除 webhook endpoints

支付

资源	Permission	描述
Charge	`charge_read`	读取付款 charges 和退款
Charge	`charge_write`	创建 charges、capture 付款、发起退款
Dispute	`dispute_read`	读取支付争议和证据
Dispute	`dispute_write`	提交争议证据并回应争议
Payment Intent	`payment_intent_read`	读取 payment intent 详情和状态
Payment Intent	`payment_intent_write`	创建、确认或取消 payment intents
Payment Method	`payment_method_read`	读取已保存的支付方式
Payment Method	`payment_method_write`	将支付方式附加或分离到客户
Payout	`payout_read`	读取 payout 详情和计划
Payout	`payout_write`	创建或取消 payouts
Refund	`refund_read`	读取退款详情
Refund	`refund_write`	创建或更新退款
Setup Intent	`setup_intent_read`	读取 setup intent 详情
Setup Intent	`setup_intent_write`	创建或确认 setup intents

账单

资源	Permission	描述
Coupon	`coupon_read`	读取折扣券和促销码
Coupon	`coupon_write`	创建、更新或删除优惠券
Credit Note	`credit_note_read`	读取信用票据
Credit Note	`credit_note_write`	创建或作废信用票据
Invoice	`invoice_read`	读取发票详情、行项目和状态
Invoice	`invoice_write`	创建、更新、最终确认或作废发票
Invoice Item	`invoice_item_read`	读取待处理发票项目
Invoice Item	`invoice_item_write`	创建或删除发票项目
Plan	`plan_read`	读取订阅计划和价格
Plan	`plan_write`	创建、更新或删除计划
Price	`price_read`	读取价格配置
Price	`price_write`	创建或更新价格
Quote	`quote_read`	读取价格报价
Quote	`quote_write`	创建、最终确认或接受报价
Subscription	`subscription_read`	读取订阅详情、计划和状态
Subscription	`subscription_write`	创建、更新或取消订阅
Subscription Schedule	`subscription_schedule_read`	读取订阅计划表
Subscription Schedule	`subscription_schedule_write`	创建、更新或释放订阅计划表
Usage Record	`usage_record_read`	读取计量计费使用记录
Usage Record	`usage_record_write`	为计量计费创建使用记录

Checkout

资源	Permission	描述
Checkout Session	`checkout_session_read`	读取 Checkout Session 详情和行项目
Checkout Session	`checkout_session_write`	创建或使 Checkout Sessions 过期
Payment Link	`payment_link_read`	读取 Payment Link 配置
Payment Link	`payment_link_write`	创建或更新 Payment Links

Connect

资源	Permission	描述
Application Fee	`application_fee_read`	读取应用费详情
Connected Account	`connected_account_read`	读取关联账户详情
Connected Account	`connected_account_write`	创建或更新关联账户
Transfer	`transfer_read`	读取账户间转账详情
Transfer	`transfer_write`	创建到关联账户的转账
Top-up	`topup_read`	读取充值详情
Top-up	`topup_write`	创建 Stripe 余额充值

Issuing

资源	Permission	描述
Issuing Card	`issuing_card_read`	读取已发行卡片详情
Issuing Card	`issuing_card_write`	创建、更新或停用已发行卡片
Issuing Cardholder	`issuing_cardholder_read`	读取持卡人信息
Issuing Cardholder	`issuing_cardholder_write`	创建或更新持卡人
Issuing Transaction	`issuing_transaction_read`	读取卡片交易详情
Issuing Authorization	`issuing_authorization_read`	读取授权请求
Issuing Authorization	`issuing_authorization_write`	批准或拒绝授权请求
Issuing Dispute	`issuing_dispute_read`	读取 issuing 争议
Issuing Dispute	`issuing_dispute_write`	创建或提交 issuing 争议

报告

资源	Permission	描述
Report Run	`report_run_read`	读取报告运行结果
Report Run	`report_run_write`	创建新的报告运行
Report Type	`report_type_read`	读取可用报告类型

税务

资源	Permission	描述
Tax Calculation	`tax_calculation_read`	读取税务计算结果
Tax Calculation	`tax_calculation_write`	创建税务计算
Tax Rate	`tax_rate_read`	读取税率配置
Tax Rate	`tax_rate_write`	创建或更新税率
Tax Registration	`tax_registration_read`	读取税务注册详情

Terminal

资源	Permission	描述
Terminal Reader	`terminal_reader_read`	读取 terminal reader 详情
Terminal Reader	`terminal_reader_write`	注册或更新 terminal readers
Terminal Location	`terminal_location_read`	读取 terminal 位置详情
Terminal Location	`terminal_location_write`	创建或更新 terminal 位置

Secret Store

资源	Permission	描述
Secret	`secret_read`	从 Secret Store 读取 secrets
Secret	`secret_write`	创建、更新或删除 secrets

Tajo Brevo 集成推荐 Permissions

对于 Tajo Brevo 集成应用，以下是推荐的 permissions：

{
  "permissions": [
    {
      "permission": "customer_read",
      "purpose": "Sync customer profiles and contact information to Brevo"
    },
    {
      "permission": "customer_write",
      "purpose": "Store Brevo contact ID and sync status on customer metadata"
    },
    {
      "permission": "charge_read",
      "purpose": "Track purchase events and revenue data for Brevo analytics"
    },
    {
      "permission": "product_read",
      "purpose": "Sync product catalog to Brevo for personalized email campaigns"
    },
    {
      "permission": "event_read",
      "purpose": "Listen to real-time events to trigger Brevo automation workflows"
    },
    {
      "permission": "invoice_read",
      "purpose": "Track invoice events for transactional emails via Brevo"
    },
    {
      "permission": "subscription_read",
      "purpose": "Monitor subscription lifecycle for Brevo retention campaigns"
    },
    {
      "permission": "secret_write",
      "purpose": "Securely store Brevo API credentials in Stripe Secret Store"
    },
    {
      "permission": "secret_read",
      "purpose": "Retrieve stored Brevo API credentials for data sync operations"
    },
    {
      "permission": "webhook_endpoint_write",
      "purpose": "Register webhook endpoints for real-time event delivery to Tajo"
    }
  ]
}

Permission 范围

Permissions 可以在不同范围内操作，具体取决于应用是安装在平台账户还是关联账户上：

范围	描述
Account	Permissions 适用于安装账户自己的数据
Connected Account	对于 Connect 平台，permissions 可以扩展到关联账户

Caution

请求 write permissions 时，请准备好在应用审核期间准确解释应用如何以及何时修改数据。不必要的 write permissions 是被拒绝的常见原因。