Class-Level vs Instance Methods

RubySDK

• Current Braintree SDKs
• Java
• .NET
• Node.js
• PHP
• Python
• Ruby

availability

This page is only relevant for Ruby, Python, and PHP integrations started before early 2018. You can skip it if:

• You are using our .NET, Java, or Node SDKs, or
• You are starting a new Ruby integration after January 4, 2018, or
• You are starting a new Python or PHP integration after February 27, 2018, or
• You are already using authentication credentials other than API keys in your integration (i.e. an OAuth access token or a client ID and client secret)

On January 4, 2018, we made some changes to our Ruby documentation to recommend a different way to pass your Braintree credentials and make requests to our API. No changes are required for existing integrations – your code can stay exactly the same, and we’ll continue to support both gateway configuration methods. Just be aware that the code snippets you see in our developer docs now may reflect a different gateway configuration method than the one you’re currently using.

Background

Our PHP, Python, and Ruby SDKs provide two different ways to interact with the Braintree API:

• Class-level methods that use a single shared configuration object for all requests to Braintree
• Instance methods that use a configurable Braintree gateway object

Using instance methods means you won’t have to manage authentication for your integration at a global level. This in turn makes it easier to add tools to your integration that use different credentials for authentication (like OAuth).

What changed in January 2018

To shift toward this more flexible gateway configuration method, we updated the example code snippets throughout our Ruby developer docs to use instance methods.

For example, a Ruby gateway configuration that looked like this:

Braintree::Configuration.environment = :sandbox
Braintree::Configuration.merchant_id = "use_your_merchant_id"
Braintree::Configuration.public_key = "use_your_public_key"
Braintree::Configuration.private_key = "use_your_private_key"

now looks like this:

gateway = Braintree::Gateway.new(
  :environment => :sandbox,
  :merchant_id => "use_your_merchant_id",
  :public_key => "use_your_public_key",
  :private_key => "use_your_private_key"
)

And a Ruby transaction sale request that looked like this:

result = Braintree::Transaction.sale(
  :amount => "10.00",
  :payment_method_nonce => nonce_from_the_client,
  :options => {
    :submit_for_settlement => true
  }
)

now looks like this:

result = gateway.transaction.sale(
  :amount => "10.00",
  :payment_method_nonce => nonce_from_the_client,
  :options => {
    :submit_for_settlement => true
  }
)

Instance methods are already supported in all 6 of our official server SDKs and are already the default for our .NET, Java, and Node SDKs, so this change will bring all of our server SDKs into alignment.

What this means for you

• If you have already integrated or are almost finished integrating with our Ruby SDK:
  • You can continue using class-level methods with no changes – we’ll continue to support both gateway configuration methods.
  • From this point forward, if you return to our docs to make any changes to your integration, you’ll need to tweak the code snippets before using them in your integration. Refer to the table below to translate the instance methods in the docs to the class-level methods you’re using.
• If you are planning to integrate or have just started integrating with our Ruby SDK:
  • While not required, we recommend using instance methods. The docs are already updated to reflect instance methods, so you can use the code snippets as-is in your integration. If you've already started integrating, just be sure to update your configuration and server requests to use gateway instances.
  • If you choose to use the older class-level methods, you’ll need to tweak the code snippets from the docs before using them in your integration. Refer to the table below to translate instance methods to class-level methods.

important

Regardless of which gateway configuration method you use, it’s very important to be consistent.

• If you configure your integration with a gateway instance, you must use instance methods for all your server requests.
• If you configure your integration with a shared configuration object, you must use class-level methods for all your server requests.
• If you mix the two, you will receive errors.

Class-to-instance method translation table

Common errors

There are a couple of common errors you may see if you make a server request that doesn’t match your gateway configuration method.

For authentication, authorization, or configuration errors related to your authentication credentials themselves, see the Exceptions reference page.

Undefined variable or null object

You’ll see an error like this directly from Ruby if you attempt to use an instance method for a server request, but you’re using a single shared configuration object.

To fix this:

• If you are using class-level methods everywhere else, switch the offending instance method to a class-level method instead. Refer to the translation table above for help forming the corresponding class-level method.
• If you are using instance methods everywhere else, make sure that you have a properly-configured gateway in the current scope (e.g. pass the gateway as an argument to the method). [Refer to the section above on what changed](#what-changed-in-january-2018) to see an example of a correctly-configured gateway instance.

Configuration exception

In Ruby, you’ll receive this exception if you attempt to use a class-level method for a server request, but your gateway doesn’t have a single shared configuration object.

To fix this:

• If you are using instance methods everywhere else, switch the offending class-level method to an instance method instead. Refer to the translation table above for help forming the corresponding instance method.
• If you are using class-level methods everywhere else, make sure your integration is configured with a shared <LanguageMatcher lang="ruby">Braintree::Configuration</LanguageMatcher><LanguageMatcher lang="php">Braintree\Configuration</LanguageMatcher> object. [Refer to the section above on what changed](#what-changed-in-january-2018) to see an example of a correctly-formed shared configuration object.