Stripe Ruby Library: Gem Ruby Chính Thức Cho Stripe
Stripe Ruby Library là gem chính thức bọc Stripe API cho ứng dụng Ruby và Rails, xử lý serialize request, phân trang, và retry thay vì bạn tự viết HTTP call thô. Hãy dùng nó ngay khi app Ruby của bạn nhận thanh toán qua Stripe; không có lý do gì để tự viết lại lớp này. Chỉ bỏ qua nếu Stripe không phải bên xử lý thanh toán bạn dùng, vì gem này vô dụng nếu thiếu tài khoản Stripe.
Tích Hợp Stripe Với Ứng Dụng Ruby
Stripe Ruby Library là gem Ruby chính thức được công bố tại stripe/stripe-ruby, cung cấp cho ứng dụng Ruby và Rails một client để gọi REST API của Stripe. Nó có sẵn các resource class tự điền dữ liệu từ bất kỳ field nào response API trả về, nhờ đó tương thích với nhiều phiên bản Stripe API khác nhau mà một tài khoản có thể đang dùng, thay vì phải phát hành gem mới mỗi khi có field được thêm.
Ai Nên Dùng Stripe Ruby Library?
Nhà phát triển Ruby và Rails cần charge thẻ, chạy subscription, hoặc xử lý payout qua Stripe Connect trong một codebase Ruby có sẵn sẽ tận dụng được nhiều nhất từ gem này, vì nó bỏ đi phần tự viết HTTP request và parse JSON để làm việc với Stripe API. Các đội chạy Stripe Connect được lợi cụ thể từ việc ghi đè API key và account theo từng request, cho phép một process phục vụ nhiều tài khoản kết nối thay vì phải dựng client riêng cho từng cái. Gem này không dành cho đội có logic thanh toán nằm ở một service không phải Ruby; nó chỉ hợp lý khi Ruby đã là ngôn ngữ server của bạn.
Tính Năng Cốt Lõi Để Tích Hợp Stripe API
- ✓Resource class tự điền dữ liệu từ đúng những field mà response API trả về, theo README, nên gem hoạt động được với nhiều phiên bản Stripe API đã pin khác nhau.
- ✓StripeClient, class client mà Stripe thêm vào từ phiên bản 13 của SDK này: cấu hình một lần với secret key, sau đó gọi các phương thức resource như client.v1.customers.list().
- ✓Ghi đè theo từng request cho api_key, stripe_account, và stripe_version, điều mà README gắn trực tiếp với các app dùng Stripe Connect trên nhiều tài khoản kết nối.
- ✓Tự động retry qua Stripe.max_network_retries, kích hoạt khi gặp lỗi kết nối, timeout, hoặc response HTTP 409 Conflict, kèm idempotency key để một request bị retry không vô tình charge hai lần.
- ✓Hook instrumentation qua Stripe::Instrumentation.subscribe(:request_begin) và :request_end, cung cấp thời lượng request, HTTP status, và số lần retry cho hệ thống metrics riêng của bạn.
- ✓Phương thức raw_request trên StripeClient (từ v13 trở lên) để gọi tới endpoint chưa được document hoặc đang ở dạng beta mà không cần qua resource method có sẵn.
- ✓RBI static type annotation cho Sorbet, có từ v14.0.0 và nằm trong thư mục rbi/stripe/, dù README nói rõ đây chỉ dùng cho static analysis.
Bắt Đầu: Cài Đặt
Chạy gem install stripe để lấy gem đã publish; bạn không cần source code của repo này trừ khi định sửa bản thân thư viện. Nếu muốn build từ source, gem build stripe.gemspec sẽ tạo file gem cục bộ. Với Bundler, thêm gem 'stripe' vào Gemfile và đảm bảo dòng source trong Gemfile trỏ tới https://rubygems.org chứ không phải URL http thường, vì gem tải qua http có thể bị can thiệp trên đường truyền. README liệt kê Ruby 2.7+ là yêu cầu hiện tại theo Language Version Support Policy của Stripe, nhưng cũng đánh dấu bản thân Ruby 2.7 là deprecated và sẽ bị loại bỏ ở một major version tương lai.
Kết Nối Với Stripe API
Require gem rồi tạo client bằng secret key lấy từ Stripe Dashboard: client = Stripe::StripeClient.new("sk_test_..."). Từ đó, các lệnh gọi theo dạng client.v1.<resource>.<action>, ví dụ client.v1.customers.list() hoặc client.v1.customers.retrieve('cus_123456789'). Đọc một property của resource có hai cách. customer.id và customer['id'] đều trả về giá trị, nhưng accessor sẽ raise NoMethodError nếu property chưa được định nghĩa, trong khi indexer chỉ trả về nil, điều này quan trọng khi bạn đụng tới field mà Stripe chưa document. Vậy là xong luồng cơ bản. Mỗi resource trả về cũng có property last_response chứa HTTP status và header thô, hữu ích khi có gì đó bất thường và bạn cần xem thực sự thứ gì đã trả về qua đường truyền.
Điểm mạnh
- ✓Được chính Stripe duy trì trực tiếp, nên bám sát mô hình versioning của API thay vì bị chậm lại như một wrapper của bên thứ ba.
- ✓Retry gắn liền với idempotency key theo mặc định, nên một request bị retry sau timeout hay lỗi kết nối sẽ không vô tình charge khách hai lần.
- ✓Ghi đè key và account theo từng request giúp các mô hình multi-tenant dùng Stripe Connect đơn giản hơn, không cần dựng client riêng cho từng tài khoản.
- ✓Hook instrumentation cho bạn thời lượng request, status, và số lần retry mà không cần tự xây thêm một lớp wrapper riêng.
- ✓Giấy phép MIT, không ràng buộc gì khi dùng cho mục đích thương mại.
Lưu Ý Quan Trọng Và Các Thay Đổi Sắp Deprecated
- △Ruby 2.7 đã bị đánh dấu deprecated trong README và sẽ bị loại bỏ ở một major version sắp tới, nên xây dựng trên nó lúc này là một ngõ cụt.
- △Hiện có hai cách gọi song song: class StripeClient mới và cách gọi cũ mà README nói sẽ sớm bị đánh dấu deprecated, nên code viết hôm nay có thể cần migrate sau này.
- △Telemetry (độ trễ request và mức dùng tính năng) được gửi về Stripe theo mặc định; muốn tắt phải tự set Stripe.enable_telemetry = false chứ không phải opt-in từ đầu.
- △README nói pull request từ contributor hoàn toàn mới hiện chưa được nhận, nên thay đổi code từ bên ngoài nên đi qua issue trước.
- △Type annotation RBI chỉ dùng cho static analysis và không nằm trong phạm vi semantic versioning của gem, nên một bản minor có thể đổi kết quả type checker của bạn.
- △Các bản preview beta và alpha (hậu tố -beta.X và -alpha.X) có thể có breaking change giữa hai bản preview mà không tăng major version, theo README.
Các Cách Khác Để Tích Hợp Stripe
Câu Hỏi Thường Gặp Về Stripe Ruby
Stripe Ruby Library hiện yêu cầu Ruby 2.7 trở lên theo Language Version Support Policy của Stripe. Bản thân Ruby 2.7 đã bị đánh dấu deprecated trong README và sẽ bị loại bỏ ở một major version tương lai, nên dự án mới nên nhắm tới bản Ruby mới hơn.
Set Stripe.proxy bằng URL proxy của bạn, ví dụ Stripe.proxy = 'https://user:[email protected]:1234', và Stripe Ruby Library sẽ định tuyến request API qua đó.
Có. Stripe Ruby Library hỗ trợ ghi đè theo từng request: truyền api_key (và tuỳ chọn stripe_account) trên một lệnh gọi riêng lẻ thay vì dùng một key toàn cục duy nhất, điều mà README gắn với các app xây trên Stripe Connect.
Stripe Ruby Library là mã nguồn mở theo giấy phép MIT, như được liệt kê trên repository GitHub của nó.
Set biến môi trường STRIPE_LOG thành debug hoặc info, hoặc set Stripe.log_level = Stripe::LEVEL_INFO trong code. README gợi ý mức info phù hợp cho môi trường production.
StripeClient là class client mà Stripe thêm vào từ phiên bản 13 của SDK này. README nói cách gọi cũ (legacy) sẽ sớm bị đánh dấu deprecated và dẫn tới một migration guide, nên code mới nên viết theo StripeClient.
Vấn đề nó giải quyết
Gọi trực tiếp một REST API như của Stripe từ Ruby nghĩa là bạn phải tự viết HTTP request, encode các tham số lồng nhau đúng định dạng Stripe yêu cầu, và tự phân trang qua các endpoint dạng danh sách. Stripe Ruby Library gánh việc đó thay bạn. Tham số được serialize đúng cách API mong đợi một cách tự động, response dạng danh sách đi kèm helper phân trang có sẵn, và các resource object tự điền dữ liệu từ đúng những field mà response API thực sự trả về, nên bạn không phải duy trì một schema viết tay dễ lệch khỏi API thật của Stripe.
Trường hợp sử dụng tốt nhất
- •Xây dựng luồng checkout trong Rails tạo customer, charge, và subscription qua Stripe API mà không cần tự viết HTTP request.
- •Vận hành một marketplace dùng Stripe Connect, nơi một process Ruby thực hiện thay cho nhiều tài khoản kết nối bằng cách ghi đè stripe_account theo từng request.
- •Debug sự cố thanh toán trên production bằng cách subscribe sự kiện request_begin và request_end rồi đưa thời lượng và số lần retry vào hệ thống metrics sẵn có.
- •Thử các tính năng early-access của Stripe bằng cách pin phiên bản gem có hậu tố -beta.X hoặc -alpha.X từ trang releases trước khi tính năng đó phát hành chính thức.
Repo liên quan
Vẫn đang phân vân về stripe-ruby?
Một cú bấm sẽ gửi câu hỏi kèm trang này cho AI — xem AI nói gì về stripe-ruby.
