2,187
stars
701
forks
67
watchers
1,506
prs
465
issues
431
releases
README
Stripe Ruby Library
[!TIP]
Want to chat live with Stripe engineers? Join us on our Discord server.
The Stripe Ruby library provides convenient access to the Stripe API from
applications written in the Ruby language. It includes a pre-defined set of
classes for API resources that initialize themselves dynamically from API
responses which makes it compatible with a wide range of versions of the Stripe
API.
The library also provides other features. For example:
- Easy configuration path for fast setup and use.
- Helpers for pagination.
- Built-in mechanisms for the serialization of parameters according to the
expectations of Stripe's API.
Documentation
See the Ruby API docs.
Installation
You don't need this source code unless you want to modify the gem. If you just
want to use the package, just run:
sh
gem install stripe
If you want to build the gem from source:
sh
gem build stripe.gemspec
Requirements
Per our Language Version Support Policy, we currently support Ruby 3.0+.
Support for Ruby 3.0 is deprecated and will be removed in upcoming major versions. Read more and see the full schedule in the docs: https://docs.stripe.com/sdks/versioning?lang=rubystripe-sdk-language-version-support-policy
Bundler
If you are installing via bundler, you should be sure to use the https rubygems
source in your Gemfile, as any gems fetched over http could potentially be
compromised in transit and alter the code of gems fetched securely over https:
ruby
source 'https://rubygems.org'
gem 'rails'
gem 'stripe'
Usage
The library needs to be configured with your account's secret key which is
available in your [Stripe Dashboard][api-keys]. Initialize a new client with your API key:
ruby
require 'stripe'
client = Stripe::StripeClient.new("sk_test_...")
list customers
customers = client.v1.customers.list()
retrieve single customer
customer = client.v1.customers.retrieve('cus_123456789')
Per-request Configuration
For apps that need to use multiple keys during the lifetime of a process, like
one that uses [Stripe Connect][connect], it's also possible to set a
per-request key and/or account:
ruby
require "stripe"
client = Stripe::StripeClient.new("sk_test_...")
client.v1.customers.list(
{},
{
api_key: 'sk_test_...',
stripe_account: 'acct_...',
stripe_version: '2018-02-28',
}
)
StripeClient vs legacy pattern
We introduced the StripeClient class in v13 of the Ruby SDK. The legacy pattern used prior to that version is still available to use but will be marked as deprecated soon. Review the migration guide to use StripeClient to move from the legacy pattern.
Once the legacy pattern is deprecated, new API endpoints will only be accessible in the StripeClient. While there are no current plans to remove the legacy pattern for existing API endpoints, this may change in the future.
Accessing resource properties
Both indexer and accessors can be used to retrieve values of resource properties.
ruby
customer = clienTop issues
#243Testing stubs13 comments · 2015-04-16#872Simplify version override11 comments · 2019-10-24#313Configurable HTTP client11 comments · 2015-10-02#1783Stop bundling root certificates and use the system certs instead7 comments · 2026-02-11#1634Add additional headers on request7 comments · 2025-08-13#1994`construct_event_without_verification` cannot parse an ASCII-8BIT payload4 comments · 2026-10-12#1178Include a representation of the Stripe "concept" and action in instrumentation event payloads4 comments · 2023-02-15#1114Handle rate limiting4 comments · 2022-08-16
Latest release
v21.0.0 v21.0.0 2026-11-11See the changelog for the full release notes.