Accounts - Straddle Docs

Accounts are the foundation of an interaction with Straddle. Each account represents a distinct business entity that has entered into a contractual relationship with Straddle to utilize our payment services. Understanding how to work with accounts is crucial for leveraging Straddle’s full potential.

Understanding Accounts

An account in Straddle is a comprehensive representation of a business entity with the following key aspects:

Legal Entity: Each account corresponds to a specific legal business entity.
Immediate Sandbox Access: Upon creation, accounts can instantly access the Straddle API Sandbox.
Production Readiness: To activate production access, accounts need to complete an automated onboarding process.
Customizable: Accounts can be tailored with specific capabilities, settings, and metadata.
Hierarchical: Accounts can be organized under parent Organizations for streamlined management.

As a platform integrating with Straddle, you have the unique ability to create and manage accounts on behalf of your clients. This process involves several key steps to ensure a smooth onboarding experience for your clients and compliance with Straddle’s requirements.

Step-by-Step Account Creation and Onboarding Process

Always create an Organization before creating an Account.

Create the Account

Use the Create Account endpoint to establish the initial account record for your client. This step sets up the basic structure of the account in Straddle’s system

Add Required Related Objects

After creating the account, you need to add several related objects to complete the account profile:

Representatives

Linked Bank Accounts

Capabilities

Initiate Onboarding

Once all required information and related objects are in place, use the Onboard Account endpoint to start the formal onboarding process. This triggers Straddle’s compliance checks and moves the account towards production readiness

Be sure to capture the Payment Services Agreement consent data prior calling the onboarding endpoint. You must be able to reproduce the agreement consent as requested by Straddle.

Key Considerations

Accurate Information Gathering

Ensure you collect and provide accurate, up-to-date information from your clients. This is crucial for successful onboarding and ongoing compliance.

Progressive Information Collection

Consider implementing a step-by-step process in your platform to collect information from clients gradually, aligning with Straddle’s account creation and onboarding flow.

Error Handling

Implement robust error handling in your integration. Ensure your system can gracefully handle and communicate these errors.

Status Tracking

Enable webhooks to track the status of your accounts to ensure your integration always stays in sync

Best Practices

Automate Wisely

Provide Clear Guidance

Implement Webhooks

Secure Data Handling

Offer Support

By following these guidelines and best practices, you can create a smooth, efficient process for creating and onboarding client accounts through your platform. This not only enhances your clients’ experience but also helps ensure compliance and reduces potential delays in getting accounts production-ready.

Creating an Account

Use the Create Account endpoint to set up a new account in Straddle.

Attributes

When creating an account, you can specify the following attributes:

Field	Type	Description
organization_id	string	The unique identifier of the organization this account belongs to.
account_type	string	The type of account. Currently, only ‘business’ is supported.
business_profile	object	Detailed information about the business associated with this account.
business_profile.name	string	The operating or trade name of the business.
business_profile.website	string	URL of the business’s primary marketing website.
business_profile.legal_name	string	The official registered name of the business.
business_profile.description	string	A brief description of the business and its products or services.
business_profile.use_case	string	A description of how the business intends to use Straddle’s services.
business_profile.tax_id	string	The business’s tax identification number (e.g., EIN in the US).
business_profile.phone	string	The primary contact phone number for the business.
business_profile.address	object	The primary address of the business.
business_profile.address.line1	string	Primary address line (e.g., street, PO Box).
business_profile.address.line2	string	Secondary address line (e.g., apartment, suite, unit, or building).
business_profile.address.city	string	City, district, suburb, town, or village.
business_profile.address.state	string	Two-letter state code.
business_profile.address.postal_code	string	Postal or ZIP code.
business_profile.address.country	string	The country of the address, in ISO 3166-1 alpha-2 format.
business_profile.industry	object	Information about the business’s industry.
business_profile.industry.mcc	string	The Merchant Category Code (MCC) that best describes the business.
business_profile.industry.sector	string	The specific sector within the industry category.
business_profile.industry.category	string	The general category of the industry.
business_profile.support_channels	object	Contact information for customer support.
business_profile.support_channels.email	string	The email address for customer support inquiries.
business_profile.support_channels.phone	string	The phone number for customer support.
business_profile.support_channels.url	string	The URL of the business’s customer support page or contact form.
access_level	string	The desired access level for the account. Can be ‘standard’ or ‘managed’.
metadata	object	Additional key-value pairs for storing extra information about the account.
external_id	string	Your own unique identifier for the account, useful for cross-referencing.

Example Request

Here’s how you might create a new account with all possible fields:

curl https://api.straddle.com/v1/accounts \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org_12345abcde",
    "account_type": "business",
    "business_profile": {
      "name": "Tech Innovators LLC",
      "website": "https://techinnovators.com",
      "legal_name": "Tech Innovators Limited Liability Company",
      "description": "Cutting-edge software solutions for businesses",
      "use_case": "Providing SaaS products and accepting online payments",
      "tax_id": "12-3456789",
      "phone": "+1 (555) 123-4567",
      "address": {
        "line1": "123 Innovation Drive",
        "line2": "Suite 200",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country": "US"
      },
      "industry": {
        "mcc": "5734",
        "sector": "Technology",
        "category": "Software"
      },
      "support_channels": {
        "email": "support@techinnovators.com",
        "phone": "+1 (555) 987-6543",
        "url": "https://techinnovators.com/support"
      }
    },
    "access_level": "standard",
    "metadata": {
      "internal_id": "TI2023",
      "account_manager": "jane.doe@straddle.com"
    },
    "external_id": "TechInnovators2023"
  }'

Response

Account Created Response

{
  "id": "acc_12345abcde",
  "organization_id": "org_12345abcde",
  "account_type": "business",
  "business_profile": {
    "name": "Tech Innovators LLC",
    "website": "https://techinnovators.com",
    "legal_name": "Tech Innovators Limited Liability Company",
    "description": "Cutting-edge software solutions for businesses",
    "use_case": "Providing SaaS products and accepting online payments",
    "tax_id": "12-3456789",
    "phone": "+1 (555) 123-4567",
    "address": {
      "line1": "123 Innovation Drive",
      "line2": "Suite 200",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country": "US"
    },
    "industry": {
      "mcc": "5734",
      "sector": "Technology",
      "category": "Software"
    },
    "support_channels": {
      "email": "support@techinnovators.com",
      "phone": "+1 (555) 987-6543",
      "url": "https://techinnovators.com/support"
    }
  },
  "capabilities": {
    "payment_types": {
      "charges": {
        "capability_status": "inactive"
      },
      "payouts": {
        "capability_status": "inactive"
      }
    },
    "customer_types": {
      "individuals": {
        "capability_status": "inactive"
      },
      "businesses": {
        "capability_status": "inactive"
      }
    },
    "consent_types": {
      "signed_agreement": {
        "capability_status": "inactive"
      },
      "internet": {
        "capability_status": "inactive"
      }
    }
  },
  "settings": {
    "charges": {},
    "payouts": {}
  },
  "terms_of_service": null,
  "metadata": {
    "internal_id": "TI2023",
    "account_manager": "jane.doe@straddle.com"
  },
  "access_level": "standard",
  "external_id": "TechInnovators2023",
  "created_at": "2023-06-15T10:30:00Z",
  "updated_at": "2023-06-15T10:30:00Z"
}

Account Onboarding

Onboard a Straddle Account

After you’ve created an account, added representatives, and linked a bank account, you’ll need to onboard the account to initiate the straddle process. This endpoint handles the final activation step for the account.

Before calling this endpoint, you must obtain the user’s consent to the Straddle Terms of Service. The full terms can be found at legal.straddle.io.

Request

curl --request POST \
  --url https://{environment}.straddle.io/v1/accounts/{account_id}/onboard \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "terms_of_service": {
      "accepted_date": "2025-03-21T10:30:00Z",
      "accepted_ip": "192.168.1.1",
      "accepted_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
      "agreement_url": null,
      "agreement_type": "embedded"
    }
  }'

Path Parameters

Parameter	Type	Required	Description
`account_id`	string	Yes	The unique identifier of the account to onboard

Request Body Parameters

Parameter	Type	Required	Description
`terms_of_service`	object	Yes	Information about the user’s acceptance of Straddle’s terms of service

terms_of_service Object

Field	Type	Required	Description
`accepted_date`	string	Yes	The datetime when the terms of service were accepted, in ISO 8601 format (e.g., “2025-03-21T10:30:00Z”)
`agreement_type`	enum<string>	Yes	The type or version of the agreement accepted. Available options: `embedded`, `direct` Use `embedded` unless your platform was specifically enabled for `direct` agreements
`accepted_ip`	string	No	The IP address from which the terms of service were accepted
`accepted_user_agent`	string	No	The user agent string of the browser or application used to accept the terms
`agreement_url`	string	Yes	The URL where the full text of the accepted agreement can be found

Response

A successful request returns a 200 OK response with details about the account.

{
  "meta": {
    "api_request_id": "123e4567-e89b-12d3-a456-426614174000",
    "api_request_timestamp": "2025-03-21T16:14:51.342Z"
  },
  "response_type": "object",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "business",
    "status": "created",
    "status_detail": {
      "reason": "unverified",
      "source": "watchtower",
      "code": "…",
      "message": "…"
    },
    "business_profile": {
      "name": "…",
      "website": "https://example.com",
      "legal_name": null,
      "description": null,
      "use_case": null,
      "tax_id": null,
      "phone": null,
      "address": {
        "line1": null,
        "line2": null,
        "city": null,
        "state": null,
        "postal_code": null,
        "country": null
      },
      "industry": {
        "mcc": null,
        "sector": null,
        "category": null
      },
      "support_channels": {
        "email": null,
        "phone": null,
        "url": null
      }
    },
    "capabilities": {
      "payment_types": {
        "charges": {
          "capability_status": "active"
        },
        "payouts": {
          "capability_status": "active"
        }
      },
      "customer_types": {
        "individuals": {
          "capability_status": "active"
        },
        "businesses": {
          "capability_status": "active"
        }
      },
      "consent_types": {
        "signed_agreement": {
          "capability_status": "active"
        },
        "internet": {
          "capability_status": "active"
        }
      }
    },
    "settings": {
      "charges": {
        "max_amount": 1,
        "monthly_amount": 1,
        "daily_amount": 1,
        "monthly_count": 1,
        "funding_time": "immediate",
        "linked_bank_account_id": "123e4567-e89b-12d3-a456-426614174000"
      },
      "payouts": {
        "max_amount": 1,
        "monthly_amount": 1,
        "daily_amount": 1,
        "monthly_count": 1,
        "funding_time": "immediate",
        "linked_bank_account_id": "123e4567-e89b-12d3-a456-426614174000"
      }
    },
    "terms_of_service": {
      "accepted_date": "2025-03-21T16:14:51.342Z",
      "accepted_ip": null,
      "accepted_user_agent": null,
      "agreement_url": null,
      "agreement_type": "embedded"
    },
    "metadata": null,
    "access_level": "standard",
    "external_id": null,
    "created_at": null,
    "updated_at": null
  }
}

Account Status

Account statuses in Straddle reflect the current state of an account in its lifecycle. Understanding these statuses is crucial for managing accounts effectively and knowing when certain actions can be performed.

Status	Description
Created	Initial status when an account is first created.
Onboarding	The account is going through the onboarding process.
Active	The account has completed onboarding and is fully operational.
Rejected	The account has failed the onboarding process or compliance checks.
Inactive	The account has been temporarily or permanently suspended.

Created

Onboarding

Active

Rejected

Inactive

Understanding status_detail

The status_detail object provides more granular information about the account’s current status. It includes the following fields:

reason

string

A more specific reason for the current status. Possible values include:

unverified

: Initial state, pending verification

in_review

: Account is being reviewed

pending

: Waiting for additional information

stuck

: Issues in the verification process

verified

: Successfully verified

failed_verification

: Verification process failed

disabled

: Account has been disabled

terminated

: Account has been permanently closed

source

string

Indicates the system or process that set the current status. Currently, this is always “watchtower”, Straddle’s compliance monitoring system.

code

string

A specific code related to the status reason. This can be useful for programmatically handling different status scenarios.

message

string

A human-readable message providing more context about the current status.

Always check both the status and status_detail when handling accounts in your integration. The status_detail can provide crucial information for resolving issues or proceeding with account management.

Next Steps

Once your platform has successfully created an account, you can move forward with the next steps: adding representatives and linking bank accounts. These actions ensure that the account is fully set up to operate and receive funds. Representatives allow you to associate key individuals with the account for compliance purposes, while adding bank accounts enables the platform to facilitate payouts and other financial transactions. Moving through these stages will complete the onboarding process and prepare the account for full functionality on the Straddle platform.

Updates

​Understanding Accounts

​Step-by-Step Account Creation and Onboarding Process

​Key Considerations

Accurate Information Gathering

Progressive Information Collection

Error Handling

Status Tracking

​Best Practices

​Creating an Account

​Attributes

​Example Request

​Response

​Account Onboarding

​Onboard a Straddle Account

​Important: Consent Requirement

​Request

​Path Parameters

​Request Body Parameters

​terms_of_service Object

​Response

​Account Status

​Understanding status_detail

​Next Steps

Understanding Accounts

Step-by-Step Account Creation and Onboarding Process

Key Considerations

Best Practices

Creating an Account

Attributes

Example Request

Response

Account Onboarding

Onboard a Straddle Account

Important: Consent Requirement

Request

Path Parameters

Request Body Parameters

terms_of_service Object

Response

Account Status

Understanding status_detail

Next Steps