availability

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

  • You are using our .NET, Java, or Node SDKs, or
  • You do not plan to start a new Ruby, Python, or PHP integration before the end of 2017, 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)

Over the next few months, we’ll be making some changes to our Ruby, Python, and PHP documentation to recommend a different way to pass your Braintree credentials and make requests to our API. No changes are required for your integration – 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 in the future 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 Braintree Auth).

What’s changing in late 2017

To shift toward this more flexible gateway configuration method, we’re updating the example code snippets throughout our Ruby, Python, and PHP developer docs to use instance methods.

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

PHP
Copy
Copied
Braintree_Configuration::environment('sandbox');
Braintree_Configuration::merchantId('use_your_merchant_id');
Braintree_Configuration::publicKey('use_your_public_key');
Braintree_Configuration::privateKey('use_your_private_key');

will look like this:

PHP
Copy
Copied
$gateway = new Braintree_Gateway(array(
    'environment' => 'sandbox',
    'merchantId' => 'use_your_merchant_id',
    'publicKey' => 'use_your_public_key',
    'privateKey' => 'use_your_private_key'
));

And a PHP transaction sale request that looked like this:

PHP
Copy
Copied
$result = Braintree_Transaction::sale([
  'amount' => '10.00',
  'paymentMethodNonce' => $nonceFromTheClient,
  'options' => [
    'submitForSettlement' => True
  ]
]);

will look like this:

PHP
Copy
Copied
$result = $gateway->transaction()->sale([
  'amount' => '10.00',
  'paymentMethodNonce' => $nonceFromTheClient,
  'options' => [
    'submitForSettlement' => 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. It also means that if you’re using .NET, Java, or Node, your existing integration already supports multiple types of authentication, and you won’t see any changes in the docs you’ve grown to know and love. (You do love them, right?)

What this means for you

  • If you have already integrated or are almost finished integrating with our Ruby, Python, or PHP SDKs:
    • You can continue using class-level methods with no changes – we’ll continue to support both gateway configuration methods.
    • If you return to our docs to make any changes to your integration in the future, 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, Python, or PHP SDKs:
    • While not required, we recommend using instance methods.
    • If the docs are not yet updated for your SDK of choice, refer to the table below to translate the class-level methods in the docs to instance methods for your integration.
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

Class-level method Instance method
Braintree_AddOn::<method> $gateway->addOn()-><method>
Braintree_Address::<method> $gateway->address()-><method>
Braintree_ClientToken::<method> $gateway->clientToken()-><method>
Braintree_CreditCard::<method> $gateway->creditCard()-><method>
Braintree_Customer::<method> $gateway->customer()-><method>
Braintree_Discount::<method> $gateway->discount()-><method>
Braintree_Merchant::<method> $gateway->merchant()-><method>
Braintree_MerchantAccount::<method> $gateway->merchantAccount()-><method>
Braintree_PaymentMethod::<method> $gateway->paymentMethod()-><method>
Braintree_PaymentMethodNonce::<method> $gateway->paymentMethodNonce()-><method>
Braintree_PaypalAccount::<method> $gateway->paypalAccount()-><method>
Braintree_Plan::<method> $gateway->plan()-><method>
Braintree_SettlementBatchSummary::<method> $gateway->settlementBatchSummary()-><method>
Braintree_Subscription::<method> $gateway->subscription()-><method>
Braintree_Testing::<method> $gateway->testing()-><method>
Braintree_Transaction::<method> $gateway->transaction()-><method>
Braintree_Verification::<method> $gateway->verification()-><method>
Braintree_WebhookNotification::<method> $gateway->webhookNotification()-><method>
Braintree_WebhookTesting::<method> $gateway->webhookTesting()-><method>

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 PHP 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’s changing to see an example of a correctly-configured gateway instance.

Configuration exception

In PHP, 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 Braintree_Configuration object. Refer to the section above on what’s changing to see an example of a correctly-formed shared configuration object.

Still have questions?

If you can’t find an answer, contact our Support team.