The Straddle Node.js SDK provides type-safe access to the Straddle API, with built-in TypeScript support and convenient methods for all API operations.
The SDK includes comprehensive TypeScript definitions and supports all modern JavaScript environments including Node.js, Deno, and Bun.
Installation Install the SDK using npm:
npm install @straddleio/straddle Or using yarn:
yarn add @straddleio/straddle Setup and Configuration
Import the SDK
Import the appropriate client based on your needs:
import Straddle from '@straddleio/straddle' ;
Initialize the Client
Create a new instance of the Straddle client:
const client = new Straddle ({ apiKey: process . env [ '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 Straddle from '@straddleio/straddle' ; async function accountFlow () { const client = new Straddle ({ apiKey: process . env [ 'STRADDLE_API_KEY' ], environment: 'sandbox' }); // 1. Create a customer const customer_response = await client . customers . create ({ device: { ip_address: '192.168.0.1' }, email: 'customer@example.com' , name: 'Customer Name' , phone: '+15555555555' , type: 'individual' }); const customer = customer_response . data ; // 2. Link a bank account const paykey_response = await client . bridge . link . bankAccount ({ customer_id: customer . id , routing_number: '011000028' , account_number: '000123456789' , account_type: 'checking' }); const paykey = paykey_response . data ; // 3. Create a charge const 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: '2025-01-30' }); } accountFlow (). catch ( console . error ); For account customers (non-platform), the flow is simpler as the account context is inferred from the API key:
import Straddle from '@straddleio/straddle' ; async function accountFlow () { const client = new Straddle ({ apiKey: process . env [ 'STRADDLE_API_KEY' ], environment: 'sandbox' }); // 1. Create a customer const customer_response = await client . customers . create ({ device: { ip_address: '192.168.0.1' }, email: 'customer@example.com' , name: 'Customer Name' , phone: '+15555555555' , type: 'individual' }); const customer = customer_response . data ; // 2. Link a bank account const paykey_response = await client . bridge . link . bankAccount ({ customer_id: customer . id , routing_number: '011000028' , account_number: '000123456789' , account_type: 'checking' }); const paykey = paykey_response . data ; // 3. Create a charge const 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: '2025-01-30' }); } accountFlow (). catch ( console . error ); This example demonstrates the complete flow for Embed customers:
import Straddle from '@straddleio/straddle' ; async function embedFlow () { const client = new Straddle ({ apiKey: process . env [ 'STRADDLE_API_KEY' ], environment: 'sandbox' }); // 1. Create an organization const org_response = await client . embed . organizations . create ({ name: 'SDK Test Organization in Sandbox' }); const organization = org_response . data ; // 2. Create an account for the organization const account_response = await client . embed . accounts . create ({ organization_id: organization . id , account_type: 'business' , business_profile: { name: 'Last SDK Test' , website: 'straddle.io' }, access_level: 'standard' }); const account = account_response . data ; // 3. Create a customer const customer_response = await client . customers . create ({ "Straddle-Account-Id" : account . id , device: { ip_address: '192.168.0.1' }, email: 'customer@example.com' , name: 'Customer Name' , phone: '+15555555555' , type: 'individual' }); const customer = customer_response . data ; // 4. Link a bank account const paykey_response = await client . bridge . link . bankAccount ({ "Straddle-Account-Id" : account . id , customer_id: customer . id , routing_number: '011000028' , account_number: '000123456789' , account_type: 'checking' }); const paykey = paykey_response . data ; // 5. Create a charge const 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: '2025-01-30' }); console . log ( charge . data ); } embedFlow (). catch ( console . error ); Key Features
TypeScript Support Complete TypeScript definitions for all request params and response fields, providing excellent IDE support.
Promise-Based Modern promise-based API with async/await support for clean, readable code.
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:
try { const charge = await client . charges . create ({ amount: 1000 , currency: 'USD' , // ... other required params }); } catch ( error ) { if ( error instanceof Straddle . APIError ) { console . log ( error . status ); // HTTP status code console . log ( error . message ); // Error message } } Common error types include:
BadRequestError (400)UnprocessableEntityError (422)AuthenticationError (401)PermissionDeniedError (403)NotFoundError (404)RateLimitError (429)InternalServerError (>500)
Configure request timeouts:
// Simple timeout const client = new Straddle ({ timeout: 20 * 1000 // 20 seconds }); // Per-request timeout await client . charges . create ({ // ... params }, { timeout: 5 * 1000 // 5 seconds }); SDK Requirements For more detailed information about the SDK structure and usage, refer to our NPM Package .
