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

In February 2018, we’re making some changes to our PHP 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 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 February 2018

To shift toward this more flexible gateway configuration method, we’re updating the example code snippets throughout our 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.

What this means for you

  • If you have already integrated or are almost finished integrating with our PHP SDK:
    • 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 PHP SDK:
    • While not required, we recommend using instance methods.
    • Until the docs are updated, 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.