Stripe Python Library: SDK Chính Thức Cho API Stripe

Truy Cập API Stripe Bằng Python

Stripe Python Library là một gói Python giúp ứng dụng truy cập API Stripe mà không cần tự viết yêu cầu HTTP. Nó đi kèm các class tài nguyên dựng sẵn cho khách hàng và giao dịch, tự khởi tạo trường dữ liệu từ phản hồi API trả về, điều mà README nói giúp thư viện tương thích với nhiều phiên bản khác nhau của API Stripe. Bạn cấu hình nó bằng khóa bí mật lấy từ Stripe Dashboard, rồi gọi các phương thức tài nguyên thông qua class `StripeClient`.

Các Tính Năng Chính Của SDK

• ✓Class `StripeClient`, giới thiệu từ v8, gom các lệnh gọi API vào một đối tượng được cấu hình sẵn, thay cho mẫu toàn cục `stripe.api_key` kiểu cũ mà README nói rồi sẽ bị đánh dấu deprecated.
• ✓Các class tài nguyên có kiểu dữ liệu được tạo từ phản hồi API, nên một đối tượng `Customer` hay `Charge` tự khởi tạo các trường của mình thay vì bạn phải tự phân tích JSON thô.
• ✓Hỗ trợ bất đồng bộ: mọi phương thức yêu cầu đều có bản thêm hậu tố `_async`, như `retrieve_async`, mặc định dùng `httpx` thay vì `requests` như client đồng bộ.
• ✓Tự động thử lại qua `max_network_retries`, kích hoạt khi có lỗi kết nối, timeout, hoặc phản hồi HTTP 409, cùng khóa idempotency được tạo tự động để việc thử lại luôn an toàn.
• ✓HTTP backend có thể thay đổi: `requests`, `httpx`, `aiohttp`, `pycurl`, hoặc `urllib`, thiết lập qua tùy chọn `http_client` trên `StripeClient`.
• ✓Ghi đè theo từng yêu cầu cho API key, tài khoản kết nối, và phiên bản API Stripe qua tham số `options`, hữu ích cho các nền tảng Connect xử lý nhiều tài khoản.
• ✓Chú thích kiểu dữ liệu từ v7.1.0, đã kiểm thử với Pyright, hỗ trợ thử nghiệm `Unpack[TypedDict]` trong MyPy.
• ✓Ghi log yêu cầu tích hợp sẵn qua biến môi trường `STRIPE_LOG` hoặc module `logging` của Python, cùng khả năng đọc mã phản hồi và header thô qua `last_response`.

Bắt Đầu: Cài Đặt

Cài đặt từ PyPI bằng `pip install --upgrade stripe`, hoặc build từ mã nguồn bằng `python -m pip install .`. README ghi Python 3.9 trở lên là mức tối thiểu được hỗ trợ theo Chính sách hỗ trợ phiên bản ngôn ngữ của Stripe; hỗ trợ Python 2.7 kết thúc sau phiên bản 5.5.0, và từ 6.0.0 trở đi thư viện bỏ hoàn toàn Python 2.7. Nếu bạn định dùng client bất đồng bộ mà chưa có sẵn thư viện HTTP hỗ trợ bất đồng bộ nào, `pip install stripe[async]` sẽ cài luôn một thư viện phù hợp, tính năng mà README ghi là mới từ v13.0.1. Các tính năng preview có sẵn qua hậu tố phiên bản riêng: `bX` cho bản xem trước công khai (ví dụ `12.2.0b2`) và `aX` cho bản xem trước riêng tư, cả hai đều cài bằng cách ghim đúng phiên bản với `pip install stripe==<version>`.

Gọi API Bằng Python

Đặt khóa bí mật rồi gọi tài nguyên qua `StripeClient`: `client = StripeClient("sk_test_...")`, sau đó `client.v1.customers.list()` hoặc `client.v1.customers.retrieve("cus_123456789")`. Yêu cầu thất bại sẽ ném ra ngoại lệ mà class của nó cho biết loại lỗi, theo API Reference mà README dẫn tới. Với code bất đồng bộ, thêm hậu tố `_async` vào tên phương thức, ví dụ `await client.v1.customers.retrieve_async("cus_xyz")`, và `.auto_paging_iter()` hoạt động với cả lặp đồng bộ lẫn bất đồng bộ. Bạn cũng có thể bỏ qua hoàn toàn các phương thức định nghĩa sẵn của thư viện bằng `client.raw_request("post", "/v1/beta_endpoint", ...)`, có từ v11, để gọi thẳng tới endpoint chưa tài liệu hóa hoặc đang ở giai đoạn beta.

Các Cách Khác Để Tích Hợp Stripe

Câu Hỏi Thường Gặp Về Stripe Python Library

Vấn đề mà Stripe Python Library giải quyết

Gọi thẳng API Stripe từ Python nghĩa là bạn phải tự xây HTTP client của riêng mình: ký yêu cầu, phân tích JSON thành đối tượng dùng được, tự thử lại an toàn khi yêu cầu thất bại, và theo kịp một API có phiên bản thay đổi theo thời gian. Đó là việc phải làm lại tốn công cho từng dự án. Stripe Python Library tồn tại để nhà phát triển Python không phải làm vậy. README mô tả các class tài nguyên tự khởi tạo từ phản hồi API chính là để thư viện tiếp tục hoạt động qua nhiều phiên bản API Stripe khác nhau mà bạn không phải viết lại code client mỗi khi Stripe thay đổi.

Trường hợp sử dụng tốt nhất

• •Xây dựng backend Django hoặc Flask tạo khách hàng, giao dịch, hoặc gói đăng ký qua API Stripe mà không cần tự viết code gọi HTTP thô.
• •Thêm xử lý thanh toán bất đồng bộ vào dịch vụ dựa trên asyncio, dùng hậu tố phương thức `_async` và client bất đồng bộ chạy trên `httpx`.
• •Chạy trên nền tảng Connect cần gọi API thay mặt các tài khoản đã kết nối, dùng tùy chọn `stripe_account` theo từng yêu cầu.
• •Thử nghiệm sớm các tính năng preview bằng cách cài phiên bản `bX` (xem trước công khai) hoặc `aX` (xem trước riêng tư) được ghim đúng bản phát hành.
• •Debug vấn đề tích hợp bằng cách bật `STRIPE_LOG=debug` hoặc đọc `last_response.code` và `last_response.headers` từ bất kỳ tài nguyên nào trả về.

Ai nên dùng — và ai nên bỏ qua

Hãy thử Stripe Python Library nếu bạn đang xây ứng dụng Python, bằng Django, Flask, FastAPI, hay một script thông thường, cần tạo giao dịch, quản lý khách hàng, hoặc xử lý gói đăng ký qua API Stripe; các tài nguyên có kiểu dữ liệu và cơ chế thử lại tích hợp sẵn giúp bạn khỏi phải tự xây lại lớp đó. Bỏ qua nếu dự án của bạn vẫn ở Python 3.8 trở xuống, vì README yêu cầu 3.9 trở lên, hoặc nếu bạn cần cụ thể SDK cho Ruby hay iOS: xem stripe-ruby hoặc stripe-ios.

Repo liên quan