Skip to content

Migration guide for v5

Brandur edited this page Feb 9, 2021 · 6 revisions

Version 5 of the stripe Ruby gem contains a large number of changes. This guide will help you update your Stripe integration so that it keeps working as expected after you upgrade to v5.

Table of Contents

Breaking changes

Old Ruby versions

The stripe gem no longer supports Ruby 2.1 and 2.2. The minimum required version is now Ruby 2.3.

Removed classes

Removed class Replacement class Notes
FileUpload File There is a File class in Ruby's stdlib. You can use Stripe::File to remove ambiguity.
IssuerFraudRecord Radar::EarlyFraudWarning -

Removed methods

Removed method Replacement method Notes
*.all *.list -
Account#bank_account= Account#external_account= -
ApplicationFee#refund ApplicationFee.create_refund -
Charge#close_dispute Dispute.close ID: charge.dispute
Charge#mark_as_fraudulent Charge.update Parameters: fraud_details: { user_report: "fraudulent" }
Charge#mark_as_safe Charge.update Parameters: fraud_details: { user_report: "safe" })
Charge#refund Refund.create -
Charge#update_dispute Dispute.update ID: charge.dispute
Customer#add_invoice_item InvoiceItem.create Parameters: {customer:, ...}
Customer#cancel_subscription Subscription.delete ID:[0].id
Customer#charges Charge.list Parameters: {customer:, ...}
Customer#create_subscription Subscription.create Parameters: {customer:, ...}
Customer#create_upcoming_invoice Invoice.create Parameters: {customer:, ...}
Customer#invoice_items InvoiceItem.list Parameters: {customer:, ...}
Customer#invoices Invoice.list Parameters: {customer:, ...}
Customer#upcoming_invoice Invoice.upcoming Parameters: {customer:, ...}
Customer#update_subscription Subscription.update ID:[0].id
Recipient#transfers Transfer.list Parameters: {recipient:, ...}
Source#delete Customer.detach_source -
UsageRecord.create SubscriptionItem.create_usage_record -

Faraday removal

Faraday has been replaced by Ruby's built-in Net::HTTP module. The library will still behave the same, but some of the old properties on StripeClient have been removed or changed type, and you may need to update your integration if you were using them.


  • Connections should only be configured by using top-level configuration like Stripe.api_base, Stripe.ca_store, Stripe.proxy, and Stripe.verify_ssl_certs. Behavior of all these properties remains unchanged.
  • StripeClient.conn and StripeClient.default_conn have been removed. There's no longer a way to create a customized connection, so use the properties above instead of creating a connection to set your own.
  • Likewise, thread-local store for these values has also been removed like Thread.current[:stripe_client_default_conn].
  • StripeClient's constructor now takes a connection manager instead of a connection. You shouldn't ever need to manually instantiate a StripeClient.
  • Connections are now persistent by default, so there's no need to configure a specific adapter as you may have done with Faraday.
  • If you were overriding connections to use Faraday's Rack adapter, consider using webmock instead.
  • There is no direct replacement for Faraday middleware. If you were using it for something that's difficult to reimplement under the new system, open an issue and we'll take a closer look to see if we can come up with an alternative.


The Stripe::Customer#delete_discount method used to return the customer object for which the discount has been deleted. It now returns the discount which was deleted instead. The underlying customer object must also be refreshed manually (by using #refresh for example) to reflect the deleted discount.