Braintree Python SDK

4.42.0 verified Tue May 12 auth: no python install: verified quickstart: verified

PayPal's Braintree payment gateway Python SDK. Current version: 4.42.0 (Mar 2026). Stable API — no major breaking changes from v3 to v4 for Python. SSL certificate update required: Braintree updated root SSL cert April 2024 — SDKs older than ~4.33 will fail after March 2026. Three-step flow: generate client token server-side → collect payment method nonce client-side → create transaction server-side. Amount as string. submit_for_settlement must be True to actually capture funds.

pip install braintree

Common errors

error 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

error 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.

error 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.

error 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 compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.79s 23.4M

3.10 slim (glibc) - - 0.56s 24M

3.11 alpine (musl) - - 0.98s 25.6M

3.11 slim (glibc) - - 0.81s 26M

3.12 alpine (musl) - - 0.92s 17.4M

3.12 slim (glibc) - - 0.91s 18M

3.13 alpine (musl) - - 0.89s 17.0M

3.13 slim (glibc) - - 0.83s 17M

3.9 alpine (musl) - - 0.76s 22.7M

3.9 slim (glibc) - - 0.66s 23M

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 verified last tested: 2026-04-23

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)