Python SDK for Straddle

The Straddle Python SDK provides convenient access to the Straddle API from any Python application. The SDK includes type definitions and offers both synchronous and asynchronous clients powered by httpx.

The SDK supports Python 3.8+ and provides comprehensive type hints through TypedDict and Pydantic models.

Installation

Install the SDK using pip:

pip install straddle

For development environments, we recommend using python-dotenv to manage your API keys:

pip install python-dotenv

Setup and Configuration

Import the SDK

Import the appropriate client based on your needs:

from straddle import AsyncStraddle

Initialize the Client

Create a new instance of the Straddle client:

client = AsyncStraddle(
    api_key=os.environ.get("STRADDLE_API_KEY"),
    environment="sandbox", # or "production"
)

Never hardcode your API key directly in your code. Use environment variables or a secure configuration management system.

Implementation Examples

Straddle Account Customers
Embed Customers

For account customers (non-platform), the flow is simpler as the account context is inferred from the API key:

import asyncio
from straddle import AsyncStraddle
from pydantic.v1.datetime_parse import parse_date
from straddle.types import DeviceUnmaskedV1Param

async def account_flow():
    client = AsyncStraddle(
        api_key=os.environ.get("STRADDLE_API_KEY"),
        environment="sandbox"
    )

    # 1. Create a customer
    customer_response = await client.customers.create(
        device=DeviceUnmaskedV1Param(ip_address="192.168.0.1"),
        email="[email protected]",
        name="Customer Name",
        phone="+15555555555",
        type="individual"
    )
    customer = customer_response.data

    # 2. Link a bank account
    paykey_response = await client.bridge.link.bank_account(
        customer_id=customer.id,
        routing_number="011000028",
        account_number="000123456789",
        account_type="checking"
    )
    paykey = paykey_response.data

    # 3. Create a charge
    charge = await client.charges.create(
        amount=1,
        config={"balance_check": "required"},
        consent_type="internet",
        currency="USD",
        description="Monthly subscription fee",
        device={"ip_address": "192.168.1.1"},
        external_id="external_id",
        paykey=paykey.paykey,
        payment_date=parse_date("2025-01-30")
    )
    print(charge.data)

if __name__ == '__main__':
    asyncio.run(account_flow())

This example demonstrates the complete flow for Embed customers using the async client:

import asyncio
from straddle import AsyncStraddle
from pydantic.v1.datetime_parse import parse_date
from straddle.types import DeviceUnmaskedV1Param
from straddle.types.embed import BusinessProfileV1Param

async def embed_flow():
    client = AsyncStraddle(
        api_key=os.environ.get("STRADDLE_API_KEY"),
        environment="sandbox"
    )

    # 1. Create an organization
    org_response = await client.embed.organizations.create(
        name="SDK Test Organization in Sandbox",
    )
    organization = org_response.data

    # 2. Create an account for the organization
    account_response = await client.embed.accounts.create(
        organization_id=organization.id,
        account_type="business",
        business_profile=BusinessProfileV1Param(
            name="SDK Test",
            website="straddle.com"
        ),
        access_level="standard"
    )
    account = account_response.data

    # 3. Create a customer
    customer_response = await client.customers.create(
        straddle_account_id=account.id,
        device=DeviceUnmaskedV1Param(ip_address="192.168.0.1"),
        email="[email protected]",
        name="Customer Name",
        phone="+15555555555",
        type="individual"
    )
    customer = customer_response.data

    # 4. Link a bank account
    paykey_response = await client.bridge.link.bank_account(
        straddle_account_id=account.id,
        customer_id=customer.id,
        routing_number="011000028",
        account_number="000123456789",
        account_type="checking"
    )
    paykey = paykey_response.data

    # 5. Create a charge
    charge = await client.charges.create(
        straddle_account_id=account.id,
        amount=1,
        config={"balance_check": "required"},
        consent_type="internet",
        currency="USD",
        description="Monthly subscription fee",
        device={"ip_address": "192.168.1.1"},
        external_id="external_id",
        paykey=paykey.paykey,
        payment_date=parse_date("2025-01-30"),
    )
    print(charge.data)

if __name__ == '__main__':
    asyncio.run(embed_flow())

Key Features

Type Safety

Built-in type hints with TypedDict for requests and Pydantic models for responses, providing excellent IDE support and catch errors early.

Async Support

First-class async/await support through the AsyncStraddle client, perfect for high-performance applications.

Automatic Pagination

Built-in support for automatic pagination, making it easy to handle large result sets.

Error Handling

Comprehensive error types and helpful error messages for better debugging and error recovery.

Error Handling

The SDK provides specific exception types for different error cases:

Common Error Types

try:
charge = await client.charges.create(
    amount=1000,
    currency="USD",
    # ... other required params
)
except straddle.APIConnectionError as e:
    print("Connection error:", e.__cause__)
except straddle.RateLimitError as e:
    print("Rate limit exceeded:", e.status_code)
except straddle.APIStatusError as e:
    print("API error:", e.status_code)
    print("Response:", e.response)

Common error types include:

BadRequestError (400)
UnprocessableEntityError (422)
AuthenticationError (401)
PermissionDeniedError (403)
NotFoundError (404)
RateLimitError (429)
InternalServerError (>500)

Timeout Configuration

Configure request timeouts:

import httpx

# Simple timeout
client = AsyncStraddle(timeout=20.0) # 20 seconds

# Detailed timeout configuration
client = AsyncStraddle(
    timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0)
)

SDK Requirements

Python Version

Python 3.8 or higher

For more detailed information about the SDK structure and usage, refer to our Pypi Package.

Fundamentals

SDKs

Customers

Bridge

Paykeys

Charges

Payouts

Funding

Payments

Embed

Installation

Setup and Configuration

Implementation Examples

Key Features

Type Safety

Async Support

Automatic Pagination

Error Handling

Error Handling

SDK Requirements

Python Version

​Installation

​Setup and Configuration

​Implementation Examples

​Key Features

Type Safety

Async Support

Automatic Pagination

Error Handling

​Error Handling

​SDK Requirements

Python Version

Installation

Setup and Configuration

Implementation Examples

Key Features

Error Handling

SDK Requirements