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:
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 = "customer@example.com" , 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()) 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 = "customer@example.com" , 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.io" ), 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 = "customer@example.com" , 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:
SDK Requirements For more detailed information about the SDK structure and usage, refer to our Pypi Package .
