Mọi tích hợp Stripe đều bắt đầu bằng cùng một câu hỏi: khóa nào đặt ở đâu? Stripe cung cấp cho bạn một khóa publishable, một khóa secret, và tùy chọn tạo các khóa restricted, mỗi loại đều có phiên bản test và live. Đặt sai khóa vào sai chỗ, bạn hoặc sẽ để lộ khả năng di chuyển tiền, hoặc mất cả buổi chiều vì lỗi 401. Hướng dẫn này trình bày mỗi khóa API của Stripe làm gì, nó nằm ở đâu, cách gửi yêu cầu thử nghiệm đầu tiên ở chế độ test, và cách giữ khóa live tránh xa mọi thứ được chia sẻ. Để hiểu khái niệm chung trước tiên, hãy bắt đầu với API key là gì. Mọi nội dung dưới đây đều tuân theo tài liệu về API keys của Stripe, được kiểm tra vào tháng 9 năm 2026.
Khóa API Stripe của bạn nằm ở đâu trong Dashboard
Mở trang API keys tại dashboard.stripe.com/apikeys. Trang này nằm trong mục Developers trên Dashboard và hiển thị các khóa của tài khoản hoặc sandbox mà bạn đang xem. Một nút bật/tắt chuyển đổi giữa chế độ sandbox và chế độ live, và danh sách khóa thay đổi theo đó.
Trang có hai danh sách:
- Standard keys chứa khóa publishable và khóa secret của bạn.
- Restricted keys chứa mọi khóa bạn đã tạo với các quyền được giới hạn phạm vi.
Khả năng hiển thị khác nhau tùy theo chế độ. Trong sandbox, bạn có thể tiết lộ mọi khóa bất cứ lúc nào. Ở chế độ live, khóa secret do chính bạn tạo sẽ chỉ được hiển thị một lần, ngay khi tạo. Hãy sao chép nó vào vault của bạn trước khi đóng hộp thoại; mất nó nghĩa là phải xoay vòng khóa. Chỉ những khóa mặc định do Stripe tạo mới có thể được tiết lộ lại ở chế độ live.
Một điều mà trang này không hiển thị: các webhook signing secret. Chúng nằm trong mục Webhooks, theo từng endpoint, và hoàn toàn không phải là API key.
Khóa publishable và khóa secret
Cái tên đã mô tả ranh giới tin cậy.
| Khóa | Tiền tố | An toàn để lộ | Nó có thể làm gì |
|---|---|---|---|
| Publishable | pk_test_ / pk_live_ |
Có | Nhận diện tài khoản của bạn, tạo token và PaymentMethods từ thông tin thẻ trong Stripe.js, Elements và các SDK di động |
| Secret | sk_test_ / sk_live_ |
Không | Mọi thứ: tạo charge, phát hành refund, đọc dữ liệu khách hàng, kích hoạt payout |
| Restricted | rk_test_ / rk_live_ |
Không | Chỉ những tài nguyên và quyền mà bạn cấp |
Khóa publishable thuộc về trình duyệt hoặc ứng dụng di động. Nó chuyển số thẻ thành token và gần như không làm gì khác. Nó không thể tạo charge hay đọc dữ liệu tài khoản, nên việc đưa nó vào mã front-end là điều được mong đợi.
Khóa secret thuộc về server của bạn và không nơi nào khác. Hướng dẫn của Stripe đã thay đổi: tài liệu giờ nói rằng họ "không khuyến nghị dùng khóa secret cho các trường hợp sử dụng mới" và hướng đến khóa restricted thay thế. Khóa secret không giới hạn vẫn hoạt động, nhưng hãy coi nó như phương án dự phòng khẩn cấp, không phải mặc định.
Khóa ở chế độ test và live
Stripe vận hành hai thế giới riêng biệt, mỗi thế giới có bộ khóa riêng. Khóa test (tài liệu mới hơn gọi phía test là sandbox, dù tiền tố vẫn là _test_) trả về các đối tượng mô phỏng: khách hàng giả, PaymentIntent giả, thẻ test thành công hoặc từ chối theo lệnh, không có tiền thật. Khóa live kết nối đến các mạng lưới thẻ và di chuyển tiền thật.
Sự tách biệt rất nghiêm ngặt. Một khách hàng được tạo bằng sk_test_ không tồn tại đối với sk_live_, và ngược lại. Mã lỗi của Stripe cho việc trộn lẫn hai luồng, livemode_mismatch, nói rõ điều đó: "Khóa API, yêu cầu và đối tượng ở chế độ test và live chỉ khả dụng trong chế độ tương ứng."
Hai quy tắc thực tế rút ra:
- Xây dựng và kiểm thử hoàn toàn dựa trên
sk_test_hoặcrk_test_. Stripe khuyến nghị một sandbox chung riêng cho các tích hợp mới để cài đặt và dữ liệu của nó được cách ly. - Chuyển sang live là một thay đổi cấu hình, không phải thay đổi mã. Server của bạn đọc khóa từ biến môi trường hoặc vault, và chuyển sang live nghĩa là thay đổi giá trị đó.
Mọi phản hồi API đều bao gồm một boolean livemode. Hãy kiểm tra nó trong các bài test của bạn; đây là biện pháp bảo vệ rẻ nhất chống lại việc triển khai sai khóa.
Khóa restricted và nguyên tắc đặc quyền tối thiểu
Một khóa API restricted (Stripe viết tắt là RAK) là một khóa secret với mặt nạ quyền. Khi bạn tạo một khóa như vậy, bạn chọn một quyền cho mỗi nhóm tài nguyên: None, Read hoặc Write. Mọi thứ mặc định là None. Write bao gồm Read, và ánh xạ sang HTTP rất đơn giản: GET cần Read, POST và DELETE cần Write.
Để tạo một khóa như vậy, nhấp vào Create restricted key trên trang API keys, chọn một bộ quyền được cấu hình sẵn hoặc bắt đầu từ con số không, đặt tên, thiết lập quyền, và hoàn tất bước xác thực hai yếu tố. Cũng như với khóa secret tự tạo ở chế độ live, bạn chỉ nhìn thấy giá trị một lần.
Hướng dẫn về khóa restricted gợi ý một khóa cho mỗi dịch vụ: dịch vụ thanh toán có quyền Write trên Invoices và Customers, một job báo cáo có quyền Read trên Charges và Disputes. Nếu một dịch vụ bị xâm phạm, kẻ tấn công bị giới hạn trong quyền của khóa đó. Một khóa disputes chỉ đọc không thể tạo charge hay chạm vào payout.
Hãy cấp cho khóa mới quyền rộng trong sandbox, chạy bộ test của bạn, sau đó mở nhật ký yêu cầu của khóa đó (menu tràn, View request logs) và cắt bỏ mọi quyền không thấy lưu lượng truy cập. Stripe cũng cho phép bạn gắn thẻ các khóa dành cho AI agent tự hành để chúng nằm dưới các quy tắc phê duyệt cho payout và refund; hãy dùng cách đó thay vì một khóa secret thông thường.
Yêu cầu đầu tiên của bạn với curl và Python
Stripe xác thực bằng HTTP Basic Auth: khóa là username và mật khẩu để trống. Dấu hai chấm ở cuối báo cho curl biết không cần nhắc:
export STRIPE_API_KEY=sk_test_... # khóa secret sandbox của bạn
curl https://api.stripe.com/v1/payment_intents \
-u "$STRIPE_API_KEY:" \
-d amount=2000 \
-d currency=usd \
-d "automatic_payment_methods[enabled]=true"
Phản hồi là một PaymentIntent với id bắt đầu bằng pi_, status: "requires_payment_method", và livemode: false. Trường cuối cùng đó xác nhận bạn đã dùng khóa test.
Stripe cũng chấp nhận -H "Authorization: Bearer $STRIPE_API_KEY", đây là dạng mà Apidog và hầu hết các HTTP client sử dụng. Cả hai đều mang cùng một khóa; nếu bạn không chắc dạng nào phù hợp với stack của mình, so sánh của chúng tôi về API keys và bearer tokens sẽ trình bày các đánh đổi. Các yêu cầu phải đi qua HTTPS; HTTP thông thường sẽ thất bại hoàn toàn, theo tài liệu tham khảo về xác thực.
Trong Python, mẫu SDK hiện tại là một StripeClient đọc khóa từ biến môi trường:
import os
import stripe
client = stripe.StripeClient(os.environ["STRIPE_API_KEY"])
intent = client.v1.payment_intents.create({
"amount": 2000,
"currency": "usd",
"automatic_payment_methods": {"enabled": True},
})
print(intent.id, intent.livemode) # pi_..., False
Không có chuỗi khóa nào xuất hiện trong file. Cùng đoạn mã đó chạy với test hoặc live tùy thuộc vào thứ mà môi trường cung cấp.
Để coding agent của bạn kiểm tra khóa Stripe với Apidog CLI
Curl chứng minh khóa hoạt động một lần. Coding agent của bạn có thể biến nó thành một kiểm tra lặp lại được thông qua Apidog CLI và giữ khóa tránh xa dự án được chia sẻ. Thiết lập một lần (token nằm trong Account Settings, API Access Token):
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com # chọn agent của bạn khi được nhắc
Sau đó đưa cho agent một prompt:
Use Apidog CLI on project <id>. Create a "Stripe Test" environment with base URL
https://api.stripe.com. Add POST /v1/payment_intents with Bearer auth from
{{stripe_secret_key}} and a form-urlencoded body: amount=2000, currency=usd.
Create a test case asserting status 200, an id starting with pi_ and
livemode false, then run it and summarize any failures.
Các lệnh nó chạy, được kiểm tra với Apidog CLI 2.2.7:
apidog environment create "Stripe Test" --project <id> --base-url https://api.stripe.com
apidog cli-schema get endpoint-create
apidog endpoint create --project <id> --file payment-intents.json
apidog cli-schema validate test-case-create --file pi-case.json
apidog test-case create --project <id> --file pi-case.json
apidog run --test-case <caseId> --project <id> -e <envId> \
--env-var "stripe_secret_key=$STRIPE_API_KEY" -r cli,json
Prompt nêu rõ form encoding vì các endpoint v1 của Stripe không nhận JSON. Phép kiểm tra livemode là dây bẫy của bạn: nếu ai đó chạy case với khóa live, nó sẽ thất bại trước khi yêu cầu thứ hai được gửi đi. Trong CI, cùng dòng apidog run đó đọc khóa từ kho bí mật của pipeline; hướng dẫn Apidog CLI trong pipeline CI/CD của chúng tôi có bản sao chép dán được. Định nghĩa yêu cầu được chia sẻ; thông tin xác thực live thì không bao giờ.
Xoay vòng khóa và phải làm gì nếu một khóa bị lộ
Hướng dẫn xử lý khóa của chính Stripe rất thẳng thắn: hãy giả định mọi thứ đã được commit vào repo, dán trong chat, hoặc in ra trong log đều đã bị xâm phạm, kể cả khi bạn không chắc có ai đó đã nhìn thấy nó.
Việc xoay vòng khóa đã được tích hợp sẵn trong Dashboard. Từ menu tràn của một khóa, chọn Rotate key, đặt thời hạn cho khóa cũ, và sao chép khóa thay thế. Cả hai đều hoạt động trong thời gian ân hạn, tối đa 7 ngày, để bạn có thể triển khai dần dần và theo dõi nhật ký yêu cầu để phát hiện những chỗ còn sót. Now sẽ thu hồi khóa cũ ngay lập tức.
Nếu một khóa secret hoặc restricted bị lộ:
- Xoay vòng nó ngay lập tức với thời hạn ngắn.
- Cập nhật mọi server đã dùng nó, xác nhận lưu lượng trong nhật ký yêu cầu, rồi để khóa cũ hết hạn.
- Xem lại hoạt động gần đây trong Workbench để tìm bất cứ thứ gì mà tích hợp của bạn sẽ không làm: các connected account không nhận ra, các payout bạn không khởi tạo, các tài khoản ngân hàng mới.
- Tạm dừng các payout đáng ngờ, đảo ngược bất kỳ khoản nào đã gửi, và hoàn tiền cho các charge gian lận thật nhanh để ngăn chặn tranh chấp.
- Xoay vòng luôn các khóa khác của bạn. Nếu một khóa bị lộ, hãy giả định kênh đã làm lộ nó cũng đã thấy nhiều hơn thế.
Stripe quét tìm các khóa bị lộ và sẽ thông báo cho bạn, đôi khi vô hiệu hóa khóa trước, nhưng việc phát hiện không được đảm bảo. Tìm kiếm sk_live_ và rk_live_ trong các repo và cấu hình CI của bạn là một cuộc kiểm tra mất năm phút, và một secret scanner trong pre-commit hook sẽ ngăn lần rò rỉ tiếp theo xảy ra. Stripe không bao giờ yêu cầu khóa secret của bạn, nên bất kỳ tin nhắn nào yêu cầu nó đều là lừa đảo.
Các lỗi khóa API Stripe phổ biến
| Triệu chứng | Nghĩa là gì | Cách khắc phục |
|---|---|---|
401 "No valid API key provided" |
Khóa bị thiếu, sai định dạng hoặc đã bị thu hồi | Kiểm tra header; xác nhận khóa chưa bị xoay vòng |
api_key_expired |
Khóa đã bị xoay vòng hoặc hết hạn | Lấy khóa hiện tại từ Dashboard |
secret_key_required |
Bạn đã gửi khóa pk_ đến một endpoint phía server |
Dùng sk_ hoặc rk_ ở backend |
resource_missing với một id bạn biết là tồn tại |
Sai chế độ: khóa test dùng với đối tượng live, hoặc ngược lại | Khớp chế độ khóa với đối tượng |
403 "doesn't have permissions to perform the request" |
Khóa restricted thiếu quyền Read hoặc Write trên tài nguyên đó | Chỉnh sửa quyền của khóa; phần thân lỗi nêu rõ thứ còn thiếu |
livemode_mismatch |
Trộn khóa hoặc đối tượng test và live trong một yêu cầu | Giữ mỗi môi trường hoàn toàn trong một chế độ |
Hai trường hợp 401 và 403 tương ứng với stripe.AuthenticationError và stripe.PermissionError trong SDK Python, theo tài liệu tham khảo về lỗi, nên bạn có thể bắt riêng chúng. Một trường hợp ít rõ ràng hơn: một khóa live chưa tạo transfer hay payout trong 180 ngày sẽ bị hạn chế cho các hành động đó, với tùy chọn Restore access trên khóa.
Câu hỏi thường gặp
Có an toàn khi đặt khóa publishable của Stripe trong mã frontend không?
Có. Khóa pk_ chuyển thông tin thẻ thành token nhưng không thể tạo charge, đọc khách hàng hay di chuyển tiền. Chỉ khóa secret và restricted mới phải giữ ở phía server.
Tôi có thể dùng khóa restricted ở chế độ test không?
Có. Khóa restricted tồn tại ở cả hai chế độ (rk_test_ và rk_live_). Stripe khuyến nghị tinh chỉnh phiên bản test trước, rồi tạo khóa live với các quyền tương ứng.
Webhook signing secret có giống với API key của tôi không?
Không. Signing secret được cấp theo từng endpoint webhook và chỉ dùng để xác minh một sự kiện đến là từ Stripe. Chúng nằm trong mục Webhooks, không phải trang API keys. Nếu bạn đang thiết lập những thứ đó, hãy xem cách kiểm thử Stripe webhooks trong CI.
Điều gì xảy ra nếu tôi dùng khóa test trong môi trường production?
Các yêu cầu thành công nhưng không có thẻ nào bị tính phí và không có tiền nào di chuyển. Vì livemode trả về false trên mọi đối tượng, một phép kiểm tra trên trường đó sẽ phát hiện sai sót trước cả khách hàng.
Phiên bản ngắn gọn
Khóa publishable đi vào client, khóa secret và restricted ở lại trên server, test và live không bao giờ trộn lẫn, và restricted tốt hơn secret mỗi khi bạn có thể giới hạn phạm vi. Giữ khóa live trong một vault, truyền khóa test cho Apidog CLI tại thời điểm chạy, và giữ một phép kiểm tra livemode trong mọi test case mà agent của bạn viết.