Stripe Ruby Library

Accessing properties

You can retrieve resource properties using either dot notation (accessors) or bracket notation (indexer).

• Dot notation (customer.id): Raises a NoMethodError if the property is not defined.
• Bracket notation (customer['id']): Returns nil if the property is not defined.

Accessing the response object

To access HTTP metadata like status codes or headers, use the last_response property on the returned resource.

Note: For custom hash fields like Customer.metadata, always use the [] accessor.

To use the Stripe package in your application, install the gem directly using the command line:

gem install stripe

If you need to build the gem from the source code, use:

gem build stripe.gemspec

This project uses just for common development tasks. You can use the just command or run the underlying commands directly.

Run all tests:

just test
# or: bundle exec rake test

Run the linter:

just lint
# or: bundle exec rubocop

Update bundled CA certificates:

just update-certs
# or: bundle exec rake update_certs

The test suite requires stripe-mock to run. You can install it using Go and then start it in a background terminal:

go install github.com/stripe/stripe-mock@latest
stripe-mock

To run an example script located in the examples/ directory, you must set the RUBYLIB environment variable to point to the lib/ directory so the Ruby interpreter can find the stripe gem source. Run the following command from within the examples/ folder:

RUBYLIB=../lib ruby <your_example_file>.rb

RUBYLIB=../lib ruby event_notification_webhook_handler.rb

Stripe features in preview can be accessed by installing specific versions of the gem with -beta.X (Public Preview) or -alpha.X (Private Preview) suffixes.

To install a specific version:

gem install stripe -v <version_with_suffix>

Warning: Preview versions may contain breaking changes between minor releases. It is highly recommended to pin the version in your Gemfile.

Using Beta Features

Some preview features require a specific header (e.g., feature_beta=v3). In public preview SDKs, you can set this using Stripe.add_beta_version (Note: the documentation example shows a Python-style call, but the concept applies to the Ruby SDK for setting beta headers).

If you are not using just, you can run tests directly using bundle exec ruby.

Run a single test suite:

bundle exec ruby -Ilib/ test/stripe/util_test.rb

Run a single test by name:

bundle exec ruby -Ilib/ test/stripe/util_test.rb -n /should.convert.names.to.symbols/

When using Bundler, ensure your Gemfile uses the https source for rubygems.org to prevent compromised gems from being fetched over insecure connections.

source 'https://rubygems.org'

gem 'rails'
gem 'stripe'

To contribute a new example to the repository, follow these steps:

1. Clone an existing example file (e.g., cp existing_example.rb new_example.rb).
2. Implement your example logic.
3. Fill out the file comment at the top of the file, including a description and the key steps being demonstrated.
4. Run the script using the RUBYLIB=../lib ruby <filename> command to verify it works.
5. Submit your changes.

To use the library, initialize a new Stripe::StripeClient with your account's secret key. This is the recommended pattern (introduced in v13) for making API calls.

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')

You can enable logging to gain insight into library activity. The info level is recommended for production, while debug provides more verbosity.

Option 1: Environment Variable

$ export STRIPE_LOG=info

Option 2: Ruby Code

Stripe.log_level = Stripe::LEVEL_INFO

The following global configurations can be set on the Stripe module:

• Proxy: Stripe.proxy = 'https://user:pass@example.com:1234'
• API Version: Stripe.api_version = '2018-02-28'
• CA Bundle: Stripe.ca_bundle_path = 'path/to/ca/bundle'
• Automatic Retries: Stripe.max_network_retries = 2 (retries on transient errors and 409 Conflict)
• Timeouts:
  • Stripe.open_timeout = 30 (seconds)
  • Stripe.read_timeout = 80 (seconds)
  • Stripe.write_timeout = 30 (seconds, requires Ruby 2.6+)
• Telemetry: Stripe.enable_telemetry = false (disables sending latency and usage data to Stripe)