On this page

Tham Chiếu Permissions

Stripe Apps sử dụng hệ thống quyền để kiểm soát quyền truy cập vào các tài nguyên Stripe API. Mỗi quyền phải được khai báo rõ ràng trong app manifest với mục đích rõ ràng. Người dùng phê duyệt các quyền này khi cài đặt app.

Quản Lý Permissions

Khai Báo Permissions

Thêm permissions vào manifest stripe-app.json:

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

Cấp Permissions Qua CLI

Trong quá trình phát triển, bạn có thể cấp permissions bằng Stripe CLI:

# Cấp một quyền cụ thể
stripe apps grant permission "customer_read" \
  --purpose "Read customer profiles to sync with Brevo contacts"

# Cấp nhiều quyền
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"

Thực Hành Tốt Về Permissions

Tối thiểu cần thiết: Chỉ yêu cầu quyền mà app thực sự sử dụng
Mục đích rõ ràng: Viết mục đích mà người dùng không chuyên kỹ thuật có thể hiểu
Biện minh cho read+write: Nếu cần cả đọc và ghi, hãy giải thích lý do trong mỗi mục đích
Xem xét thường xuyên: Xóa các quyền không còn cần thiết khi cập nhật app

Tip

Yêu cầu quá nhiều quyền là một trong những lý do phổ biến nhất khiến app bị từ chối. Chỉ yêu cầu những gì bạn cần.

Permissions Theo Sản Phẩm

Core

Tài Nguyên	Permission	Mô Tả
Account	`account_read`	Đọc chi tiết và cài đặt tài khoản
Account	`account_write`	Cập nhật cài đặt tài khoản
Balance	`balance_read`	Xem số dư và giao dịch tài khoản
Customer	`customer_read`	Đọc hồ sơ khách hàng, metadata và phương thức thanh toán
Customer	`customer_write`	Tạo, cập nhật hoặc xóa hồ sơ khách hàng
Event	`event_read`	Đọc và đăng ký sự kiện tài khoản
File	`file_read`	Đọc các file đã tải lên và liên kết file
File	`file_write`	Tải file lên và tạo liên kết file
Mandate	`mandate_read`	Đọc ủy quyền thanh toán
Product	`product_read`	Đọc danh mục sản phẩm và giá
Product	`product_write`	Tạo, cập nhật hoặc xóa sản phẩm và giá
Token	`token_read`	Đọc dữ liệu thanh toán đã tokenize
Webhook Endpoint	`webhook_endpoint_read`	Đọc cấu hình webhook endpoint
Webhook Endpoint	`webhook_endpoint_write`	Tạo, cập nhật hoặc xóa webhook endpoints

Thanh Toán

Tài Nguyên	Permission	Mô Tả
Charge	`charge_read`	Đọc charges và refunds
Charge	`charge_write`	Tạo charges, capture payments, phát hành refunds
Dispute	`dispute_read`	Đọc tranh chấp và bằng chứng
Dispute	`dispute_write`	Gửi bằng chứng tranh chấp và phản hồi
Payment Intent	`payment_intent_read`	Đọc chi tiết và trạng thái payment intent
Payment Intent	`payment_intent_write`	Tạo, xác nhận hoặc hủy payment intents
Payment Method	`payment_method_read`	Đọc các phương thức thanh toán đã lưu
Payment Method	`payment_method_write`	Đính kèm hoặc tách phương thức thanh toán khỏi khách hàng
Payout	`payout_read`	Đọc chi tiết và lịch payout
Payout	`payout_write`	Tạo hoặc hủy payouts
Refund	`refund_read`	Đọc chi tiết refund
Refund	`refund_write`	Tạo hoặc cập nhật refunds
Setup Intent	`setup_intent_read`	Đọc chi tiết setup intent
Setup Intent	`setup_intent_write`	Tạo hoặc xác nhận setup intents

Thanh Toán Định Kỳ

Tài Nguyên	Permission	Mô Tả
Coupon	`coupon_read`	Đọc coupon giảm giá và mã khuyến mãi
Coupon	`coupon_write`	Tạo, cập nhật hoặc xóa coupons
Credit Note	`credit_note_read`	Đọc credit notes
Credit Note	`credit_note_write`	Tạo hoặc vô hiệu hóa credit notes
Invoice	`invoice_read`	Đọc chi tiết hóa đơn, mục hàng và trạng thái
Invoice	`invoice_write`	Tạo, cập nhật, hoàn thiện hoặc hủy hóa đơn
Invoice Item	`invoice_item_read`	Đọc các mục hóa đơn đang chờ
Invoice Item	`invoice_item_write`	Tạo hoặc xóa mục hóa đơn
Plan	`plan_read`	Đọc subscription plans và giá
Plan	`plan_write`	Tạo, cập nhật hoặc xóa plans
Price	`price_read`	Đọc cấu hình giá
Price	`price_write`	Tạo hoặc cập nhật giá
Quote	`quote_read`	Đọc báo giá
Quote	`quote_write`	Tạo, hoàn thiện hoặc chấp nhận báo giá
Subscription	`subscription_read`	Đọc chi tiết, lịch và trạng thái đăng ký
Subscription	`subscription_write`	Tạo, cập nhật hoặc hủy đăng ký
Subscription Schedule	`subscription_schedule_read`	Đọc lịch đăng ký
Subscription Schedule	`subscription_schedule_write`	Tạo, cập nhật hoặc giải phóng lịch đăng ký
Usage Record	`usage_record_read`	Đọc bản ghi sử dụng billing theo đồng hồ
Usage Record	`usage_record_write`	Tạo bản ghi sử dụng cho billing theo đồng hồ

Checkout

Tài Nguyên	Permission	Mô Tả
Checkout Session	`checkout_session_read`	Đọc chi tiết Checkout Session và mục hàng
Checkout Session	`checkout_session_write`	Tạo hoặc hết hạn Checkout Sessions
Payment Link	`payment_link_read`	Đọc cấu hình Payment Link
Payment Link	`payment_link_write`	Tạo hoặc cập nhật Payment Links

Connect

Tài Nguyên	Permission	Mô Tả
Application Fee	`application_fee_read`	Đọc chi tiết application fee
Connected Account	`connected_account_read`	Đọc chi tiết tài khoản connected
Connected Account	`connected_account_write`	Tạo hoặc cập nhật tài khoản connected
Transfer	`transfer_read`	Đọc chi tiết transfer giữa các tài khoản
Transfer	`transfer_write`	Tạo transfers đến tài khoản connected
Top-up	`topup_read`	Đọc chi tiết top-up
Top-up	`topup_write`	Tạo top-ups cho Stripe balance

Issuing

Tài Nguyên	Permission	Mô Tả
Issuing Card	`issuing_card_read`	Đọc chi tiết thẻ đã phát hành
Issuing Card	`issuing_card_write`	Tạo, cập nhật hoặc vô hiệu hóa thẻ đã phát hành
Issuing Cardholder	`issuing_cardholder_read`	Đọc thông tin chủ thẻ
Issuing Cardholder	`issuing_cardholder_write`	Tạo hoặc cập nhật chủ thẻ
Issuing Transaction	`issuing_transaction_read`	Đọc chi tiết giao dịch thẻ
Issuing Authorization	`issuing_authorization_read`	Đọc yêu cầu ủy quyền
Issuing Authorization	`issuing_authorization_write`	Phê duyệt hoặc từ chối yêu cầu ủy quyền
Issuing Dispute	`issuing_dispute_read`	Đọc tranh chấp issuing
Issuing Dispute	`issuing_dispute_write`	Tạo hoặc gửi tranh chấp issuing

Báo Cáo

Tài Nguyên	Permission	Mô Tả
Report Run	`report_run_read`	Đọc kết quả report run
Report Run	`report_run_write`	Tạo report runs mới
Report Type	`report_type_read`	Đọc các loại báo cáo có sẵn

Thuế

Tài Nguyên	Permission	Mô Tả
Tax Calculation	`tax_calculation_read`	Đọc kết quả tính thuế
Tax Calculation	`tax_calculation_write`	Tạo tính thuế
Tax Rate	`tax_rate_read`	Đọc cấu hình thuế suất
Tax Rate	`tax_rate_write`	Tạo hoặc cập nhật thuế suất
Tax Registration	`tax_registration_read`	Đọc chi tiết đăng ký thuế

Terminal

Tài Nguyên	Permission	Mô Tả
Terminal Reader	`terminal_reader_read`	Đọc chi tiết terminal reader
Terminal Reader	`terminal_reader_write`	Đăng ký hoặc cập nhật terminal readers
Terminal Location	`terminal_location_read`	Đọc chi tiết vị trí terminal
Terminal Location	`terminal_location_write`	Tạo hoặc cập nhật vị trí terminal

Secret Store

Tài Nguyên	Permission	Mô Tả
Secret	`secret_read`	Đọc secrets từ Secret Store
Secret	`secret_write`	Tạo, cập nhật hoặc xóa secrets

Permissions Được Khuyến Nghị Cho Tích Hợp Tajo Brevo

Đối với app tích hợp Tajo Brevo, đây là các permissions được khuyến nghị:

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

Phạm Vi Permissions

Permissions có thể hoạt động ở các phạm vi khác nhau tùy thuộc vào việc app của bạn được cài đặt trên tài khoản nền tảng hay tài khoản connected:

Phạm Vi	Mô Tả
Account	Permissions áp dụng cho dữ liệu riêng của tài khoản cài đặt
Connected Account	Đối với Connect platforms, permissions có thể mở rộng đến tài khoản connected

Caution

Khi yêu cầu write permissions, hãy chuẩn bị giải thích trong quá trình xem xét app chính xác cách và khi nào app của bạn sửa đổi dữ liệu. Các write permissions không cần thiết là lý do phổ biến để bị từ chối.