Braintree Python SDK

Common errors

• ModuleNotFoundError: No module named 'braintree'

  cause The Braintree Python SDK is not installed in the current Python environment or the environment where the code is being executed.
  fix Install the braintree package using pip: `pip install braintree`

• braintree.exceptions.AuthenticationError

  cause Your Braintree API credentials (Merchant ID, Public Key, Private Key) are incorrect, or you are attempting to use credentials for a different environment (e.g., sandbox keys in production or vice-versa).
  fix Double-check your Braintree API keys and ensure you are using the correct environment (Sandbox vs. Production) when initializing the Braintree gateway.

• SSLError: SSLCertificateError

  cause Braintree updated its root SSL certificate in April 2024. Older Python SDK versions (specifically those older than ~4.33) will fail to connect after March 2026 due to an outdated SSL certificate, or your system's OpenSSL version is too old.
  fix Upgrade your Braintree Python SDK to the latest version (`pip install --upgrade braintree`). If the issue persists, ensure your system's OpenSSL libraries are up to date.

• AttributeError: 'module' object has no attribute 'Configuration' or AttributeError: partially initialized module 'braintree' has no attribute 'BraintreeGateway' (most likely due to a circular import)

  cause You have a Python file named 'braintree.py' in your project's directory, which causes a circular import when you try to import the official 'braintree' SDK.
  fix Rename your local Python file (e.g., to `braintree_utils.py` or `payment_gateway.py`) to avoid naming conflicts with the installed `braintree` package.

Warnings

• breaking SSL certificate update: Braintree updated root SSL cert April 2024. SDK versions older than ~4.33.0 will stop working after March 30, 2026. Update to latest version.
  Fix: pip install --upgrade braintree
• gotcha Amount must be a string ('100.00'), not float or int. Passing a number raises an error or causes unexpected behavior.
  Fix: amount = f'{float_value:.2f}'
• gotcha Without submit_for_settlement: True, transactions are only authorized — not captured. Funds are not collected. Must explicitly settle.
  Fix: 'options': {'submit_for_settlement': True}
• gotcha result.is_success being False doesn't always mean total failure — check result.transaction for processor decline (card declined) vs result.errors for validation errors.
  Fix: Check both: result.transaction for processor errors, result.errors.deep_errors for validation errors.
• breaking AuthenticationError indicates invalid Braintree API credentials (merchant_id, public_key, private_key) or incorrect environment configuration.
  Fix: Verify your Braintree API credentials (merchant_id, public_key, private_key) are correct and correspond to the specified environment (e.g., sandbox, production). Ensure they are properly configured in your Braintree gateway initialization.
• breaking AuthenticationError: This typically indicates incorrect Braintree API credentials (Merchant ID, Public Key, Private Key) or an issue with their configuration. Ensure your gateway credentials are set up correctly.
  Fix: Verify Braintree API credentials (Merchant ID, Public Key, Private Key) are correct and configured properly in your `braintree.Configuration` object.

Install

• pip install braintree Python

Imports

• BraintreeGateway
  wrong:

  # Wrong: amount as float
  result = gateway.transaction.sale({'amount': 100.00, ...})
  
  # Wrong: forgetting submit_for_settlement — authorizes but doesn't capture
  result = gateway.transaction.sale({
      'amount': '100.00',
      'payment_method_nonce': nonce
      # no options — payment authorized but not captured
  })

  correct:

  import braintree
  
  gateway = braintree.BraintreeGateway(
      braintree.Configuration(
          environment=braintree.Environment.Sandbox,
          merchant_id='your_merchant_id',
          public_key='your_public_key',
          private_key='your_private_key'
      )
  )
  
  # Generate client token — send to frontend
  client_token = gateway.client_token.generate()
  
  # Create transaction with nonce from frontend
  result = gateway.transaction.sale({
      'amount': '100.00',   # string, not float
      'payment_method_nonce': nonce_from_client,
      'options': {
          'submit_for_settlement': True  # capture immediately
      }
  })
  
  if result.is_success:
      print(result.transaction.id)
  else:
      for error in result.errors.deep_errors:
          print(error.message)

  Amount must be a string ('100.00'). submit_for_settlement: True is required to capture funds immediately. Without it, transaction is only authorized — not captured.

Quickstart

Braintree Python SDK — client token generation and transaction sale.

# pip install braintree
import braintree

gateway = braintree.BraintreeGateway(
    braintree.Configuration(
        environment=braintree.Environment.Sandbox,
        merchant_id='your_merchant_id',
        public_key='your_public_key',
        private_key='your_private_key'
    )
)

# Step 1: Generate client token for frontend
client_token = gateway.client_token.generate()
# Pass client_token to frontend Braintree Drop-in UI

# Step 2: Receive nonce from frontend, create transaction
result = gateway.transaction.sale({
    'amount': '49.99',
    'payment_method_nonce': 'nonce-from-frontend',
    'options': {'submit_for_settlement': True}
})

if result.is_success:
    print('Success:', result.transaction.id)
elif result.transaction:
    print('Processor error:', result.transaction.processor_response_code)
else:
    for err in result.errors.deep_errors:
        print('Validation error:', err.message)