Node.js SDK for Straddle

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 @straddlecom/straddle

Or using yarn:

yarn add @straddlecom/straddle

Setup and Configuration

Import the SDK

Import the appropriate client based on your needs:

import Straddle from '@straddlecom/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 '@straddlecom/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: '[email protected]',
        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 '@straddlecom/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.com'
        },
        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: '[email protected]',
        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:

Common Error Types

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)

Timeout Configuration

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

Node Version

Node.js 18 LTS or higher

TypeScript Version

TypeScript >= 4.5

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

Fundamentals

SDKs

Customers

Bridge

Paykeys

Charges

Payouts

Funding

Payments

Embed

Node.js SDK for Straddle

Installation

Setup and Configuration

Implementation Examples

Key Features

TypeScript Support

Promise-Based

Automatic Pagination

Error Handling

Error Handling

SDK Requirements

Node Version

TypeScript Version

​Installation

​Setup and Configuration

​Implementation Examples

​Key Features

TypeScript Support

Promise-Based

Automatic Pagination

Error Handling

​Error Handling

​SDK Requirements

Node Version

TypeScript Version

Installation

Setup and Configuration

Implementation Examples

Key Features

Error Handling

SDK Requirements