Best Practices

PHPSDK

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

Autocomplete

When building a web form that has an input for a credit card number, turn off autocomplete so that your customer's browser won't save their credit card number.

<form method="POST" action="..." autocomplete="off">

Code vs text

Most responses from Braintree will include both a code and text. The text is the human-readable description and the code is meant to be consumed programmatically. For example, the processor response on transactions has both a code and text.

$result->transaction->processorResponseCode
# e.g. 2000

$result->transaction->processorResponseText

# e.g. "Do Not Honor"

If you wanted to build some behavior around transactions that were declined due to insufficient funds (for example, asking the users if they would like to only purchase a subset of items in their cart) you would want to check the code rather than the text. The text may vary as we refine it to provide more clarity or additional details, but the codes will remain consistent.

Internet Explorer Quirks Mode

By writing invalid HTML syntax, you can cause versions of IE to enter Quirks Mode - a parsing mode that is designed to help render very old and/or invalid pages. Quirks Mode is unreliable and not supported by the JavaScript SDK, so the Drop-in UI may not appear in such cases. To avoid this, include DOCTYPE declarations that meet W3C standards and review your HTML syntax.

Server SDK versions

Minimum required server SDK versions

It goes without saying, but we'll say it anyway: we always recommend using the latest versions of our SDKs. While older versions may still be supported, in order to communicate securely with the Braintree gateway, you must use at least the version indicated below.

• Java 2.67.0
• .NET 5.14.0
• Node 2.0.0
• PHP 3.8.0
• Python 4.17.1
• Ruby 2.57.0

Check your current server SDK version

To verify which version of the Braintree PHP SDK you’re currently using, run:

composer show

Upgrade your server SDK version

note

See the Braintree PHP version changelog.

If you're ready to update to a newer version of the PHP SDK, see our recommended approach below.

Using Composer

First, update your composer.json with the desired version for the Braintree package. There are a couple of different ways to do this, depending on how you installed Composer. Either update the JSON manually:

{
  "require" : {
    "braintree/braintree_php" : "6.21.0"
  }
}

Or run the following on the command line:

php composer.phar require braintree/braintree_php:6.21.0

Then, update the required Braintree package:

composer update braintree/braintree_php

See the Composer documentation for details on the require command and updating your dependencies.

Timeouts

When using the server SDKs, keep in mind that some requests (like creating transactions) can take longer than expected since they rely on communicating with a payment processor. The Braintree gateway has a timeout of 60 seconds to accommodate for this. If you do not want to wait this long, you can set a custom timeout in the server SDKs. However, if this timeout is less than 60 seconds, the request may trigger a timeout exception and you may not see the result of the request.

For example, let's say you set the server SDK timeout to 10 seconds, and you create a transaction sale request. If the request has not completed successfully at 10 seconds, you'll receive a timeout exception. However, if the transaction then completes successfully at 19 seconds, the customer will be charged, but you will not receive any notification of this. You will need to check the state of the transaction in the gateway to verify whether the transaction was successful or not.

BraintreeConfiguration::timeout(10);
$config = new BraintreeConfiguration([
    'environment' => 'sandbox',
    'merchantId' => 'sandbox_merchant_id',
    'publicKey' => 'sandbox_public_key',
    'privateKey' => 'sandbox_private_key'
]);
$config->timeout(10);

$gateway = new BraintreeGateway($config);

Token and ID lengths and formats

In order to avoid interruptions in processing, it's best to make minimal assumptions about what our gateway-generated tokens and identifiers will look like in the future. The length and format of these identifiers – including payment method tokens and transaction IDs – can change at any time, with or without advance notice. However, it is safe to assume that they will remain 1 to 64 characters (alphanumeric, dashes, and underscores).

Transport Layer Security

Following the PCI Data Security Standard (PCI DSS) 3.1 requirements, it's critical that you secure your connection to the Braintree gateway using Transport Layer Security (TLS) 1.2 and serve any form that collects payment data in production over HTTPS.

Older TLS versions

On June 26, 2018, Braintree ended support for server-side API requests via TLS 1.0 and 1.1 in production. The sandbox no longer accepts connections using these older TLS versions as of December 13, 2016.

If you are using older TLS or SSL versions, you may need to upgrade your Braintree SDK versions in addition to upgrading to TLS 1.2. See our full list of TLS 1.2-compatible SDKs on GitHub.

TLS certificates

We don't have a specific preferred vendor for TLS/SSL certificates, but we recommend that you stick with a well-known provider (e.g. Network Solutions, GoDaddy). Generally speaking, most certificates will be similar, so it's up to you to determine what fits your needs best.

Testing

While you can successfully test our Drop-in UI, Hosted Fields, and client-side PayPal flow over HTTP in all supported desktop and mobile browsers, you must use HTTPS if you wish to test our PayPal button in mobile webviews. Ultimately, we strongly encourage you to test all your flows over HTTPS to create a more realistic test environment.

SSL Certificates

We make periodic updates to our root SSL provider for API traffic to align with security standards. For some integrations, this requires updating certificates that are pinned to Braintree-owned domains or updating certificate authorities (CA) and intermediaries associated with Braintree-owned domains.

important

We do not recommend you follow this practice as we are unable to proactively contact you of upcoming changes that can impact your processing.

If you still feel it is necessary for your integration, you should know that these certificates are subject to change, and the best way to be apprised of upcoming changes is to regularly check this page.

Further reading

• Server SDK deprecation policy
• Server SDK migration guides